The operations that the ACP performs
can be organized into two categories: major ACP functions and subfunctions.
Each ACP operation performs one major function. That function is specified
by an I/O function code, such as IO$_ACCESS, IO$_CREATE, or IO$_MODIFY.
While executing the major function, one or more subfunctions can be
performed. A subfunction is an operation such as looking up, accessing,
or extending a file. Most subfunctions can be executed by more than
one of the major functions. Sections “Directory Lookup” through “Read/Write Attributes” describe the following subfunctions
“Major Functions”, which contains the descriptions
of the major functions, lists the subfunctions available to each major
1.3.1 Directory Lookup
The directory lookup subfunction is used to search for
a file in a disk directory or on a magnetic tape. This subfunction
can be invoked using the major functions IO$_ACCESS, IO$_MODIFY, IO$_DELETE,
and IO$_ACPCONTROL. A directory lookup occurs if the directory file ID
field in the FIB (FIB$W_DID) is a nonzero number.
18.104.22.168 Input Parameters
Table 1-2 lists the FIB fields that control the processing of a lookup subfunction.
Table 1-2 FIB Fields (Lookup Control)
Name string control. The following name
control bits are applicable to a lookup operation:
Set to match all name field values.
Set to match all field type values.
Set to match all version field
When set, performs case-sensitive
lookup; when clear, performs case-blind lookup.
Set to search a directory for
the file ID in FIB$W_FID.
Caller can accept (8-bit) ODS-2
or ISO Latin-1 formats.
Caller can accept (16-bit) Unicode
Set if name string contains wildcards.
Setting this bit causes wildcard context to be returned in FIB$L_WCC.
File identification. The file ID of the
file found is returned in this field.
Contains the file identifier of the directory
file. This field must be a nonzero number.
Maintains position context when processing
wildcard directory operations.
The following access control flag is
applicable to a lookup subfunction:
Set to rewind magnetic tape before
lookup. If not set, a magnetic tape is searched from its current position.
Contains the format of the input file
specification. The following formats are valid:
ODS-2 Format (default)
ISO Latin-1 Format
Unicode (UCS-2) Format
Contains the format of the output file
specification. The following formats are valid:
ODS-2 Format (default)
ISO Latin-1 Format
Unicode (UCS-2) Format
QIO arguments P2 through P5 (see Figure 1-1) are passed as values. The
second argument, P2, specifies the address of the descriptor for the
file name string to be searched for in the directory.
The file name string must have one of the following
The name and type can be any combination of alphanumeric
characters, and the dollar sign ($), asterisk (*), and percent (%)
characters. The version must consist of numeric characters optionally
preceded by a minus sign (-) (only for disk devices) or a single asterisk.
The total number of alphanumeric and percent characters in the name
field and in the type field must not exceed 39. Any number of additional
asterisks can be present.
If any of the bits FIB$V_ALLNAM, FIB$V_ALLTYP,
and FIB$V_ALLVER are set, then the contents of the corresponding field
in the name string are ignored and the contents are assumed to be
Note that the file name string cannot contain
a directory string. The directory is specified by the FIB$W_DID field
(see Table 1-2). Only RMS can
process directory strings.
Argument P3 is the address of a word to receive
the resultant file name string length. Argument P4 is the address
of a descriptor for a buffer to receive the resultant file name string.
The resultant string is not padded. The P3 and P4 arguments are optional.
The system searches either the directory file
specified by FIB$W_DID or the magnetic tape for the file name specified
in the P2 file name parameter. The actual file name found and its
length are returned in the P3 and P4 length and result string buffers.
The file ID of the file found is returned in FIB$W_FID and can be
used in subsequent operations as the major function is processed.
Zero and negative version numbers have special
significance in a disk lookup operation. Specifying 0 as a version
number causes the latest version of the file to be found. Specifying
-1 locates the second most recent version, -2 the third most recent,
and so forth. Specifying a version of -0 locates the lowest numbered
version of the file. For magnetic tape lookups, a version number of
0 locates the first occurrence of the file encountered; negative version
numbers are not allowed.
Wildcard lookups are performed by specifying the
appropriate wildcard characters in the name string and setting FIB$V_WILD.
(The name control bits FIB$V_ALLNAM, FIB$V_ALLTYP, and FIB$V_ALLVER
can also be used in searching for wildcard entries, but they are intended
primarily for compatibility mode use.) On the first lookup, FIB$L_WCC
should contain zero entries. On each lookup, the ACP returns a nonzero
value in FIB$L_WCC, which must be passed back on the next lookup call.
In addition, you must pass the resultant name string returned by the
previous lookup using the P4 result string buffer, and its length
in the P3 result length word. This string is used together with FIB$L_WCC
to continue the wildcard search at the correct position in the directory.
To perform a lookup by file ID, set the name control
bit FIB$V_FINDFID. When this bit is set, the system searches SYS$EI1000.EXE
the directory for an entry containing the file ID specified in FIB$W_FID,
and the name of the entry found is returned in the P3 and P4 result
parameters. Note that if a directory contains multiple entries with
the same file ID, only the first entry can be located with this technique.
Lookups by file ID should be done only when the
file name is not available, because lookups by this method are often
significantly slower than lookups by file name.
Because not all programs can handle all of the
available name formats, the FIB$W_NMCTL flags govern the name formats,
and are returned as follows:
FIB$V_ NAMES_8BIT clear
FIB$V_ NAMES_16BIT clear
Only ODS-2 format names are returned. Note that
this includes specifications that were originally in ISO Latin-1 format
or Unicode (UCS-2) format but converted to ODS-2 format before being
stored on the volume. All specifications are converted to uppercase
before being returned.
FIB$V_ NAMES_8BIT set
FIB$V_ NAMES_16BIT clear
Only those file specifications stored in ODS-2
and ISO Latin-1 formats are returned. The value in the FIB$B_NAME_FORMAT_OUT
field indicates the format of the particular name being returned.
ODS-2 format file specifications are not converted to uppercase before
FIB$V_ NAMES_8BIT clear
FIB$V_ NAMES_16BIT set
All file specifications are returned in Unicode
FIB$V_ NAMES_8BIT set
FIB$V_ NAMES_16BIT set
File specifications are returned in the format
stored on the volume. This is the simplest format compatible with
the file name syntax and the characters it contains. For example,
a specification originally in Unicode format that only contains characters
that are part of the ISO Latin-1 character set are returned in ISO
22.214.171.124 Directory Entry Protection
A directory entry is protected with the same protection
code as the file itself. For example, if a directory file is protected
against delete access, then the file name has the same protection.
Consequently, a nonprivileged user (that is, a user who is not the
volume owner, or a user who does not have SYSPRV) cannot rename a
file because renaming a file is essentially the same as deleting the
file name. This protection is applied regardless of the protection
on the directory file.
Nonprivileged users can neither write directly
into a .DIR;1 directory file nor turn off the directory bit in a directory
The access subfunction is
used to open a file so that virtual read or write operations can be
performed. This subfunction can be invoked using the major functions
IO$_CREATE and IO$_ACCESS (see “Create File” and “Access File”). An access subfunction is performed
if the IO$M_ACCESS modifier is specified in the I/O function code.
126.96.36.199 Input Parameters
Table 1-3 lists
the FIB fields that control the processing of an access subfunction.
Table 1-3 FIB Fields (Access Control)
Specifies field values that control access
to the file. The following access control bits are applicable to the
Set for write access; clear for
Set to deny read access to others.
(You must have write privilege to the file to use this option.)
Set to deny write access to others.
Set to prevent the file from being
truncated; clear to allow truncation.
Set for control access. If this
bit is set, you cannot access the file if you do not have control
Set to deny read access to the
Set to enable deaccess lock (close
check). Used only for disk devices.
Used to flag a file as inconsistent if the program currently
modifying the file terminates abnormally. If the program deaccesses
the file without performing a write attributes operation, the file
is marked as locked and cannot be accessed until it is unlocked.
Set to position at the start of
a magnetic tape file when opening a file for write; clear to position
Set to enable read checking of
the file. Virtual reads to the file are performed using a data check
Set to enable write checking of
the file. Virtual writes to the file are performed using a data check
Set to access the file in execute
mode. The protection check is made against the EXECUTE bit instead
of the READ bit. Valid only for requests issued from SUPERVISOR, EXEC,
or KERNEL mode.
Set to override exclusive access
to the file, allowing you to access the file when another user has
the file open with FIB$V_NOREAD specified. You must have SYSPRV privilege
to use this option. FIB$V_NOREAD and FIB$V_NOWRITE must be clear for
this option to work.
You must have either SYSPRV privilege
or control access to use this option.
Set to inhibit recording of the
file's modification and expiration dates. If not set, the file's
expiration date can be modified, depending on the file retention parameters
of the volume.
Set to inform the file system
that the file is to be processed sequentially only.
size of the file window used to map a disk file. The ACP uses the
volume default if FIB$B_WSIZE is 0. A value of 1 to 127 indicates
the number of retrieval pointers to be allocated to the window. A
value of -1 indicates that the window should be as large as necessary
to map the entire file. Note that the window is charged to the user's
Specifies the file identification of the file to be accessed.
The file is opened according to the access control
specified (see Table 1-3).
The extend subfunction is used to allocate space to a disk file.
This subfunction can be invoked using the major I/O functions IO$_CREATE
and IO$_MODIFY (see “Create File” and “Modify File”). The extend subfunction is performed
if the bit FIB$V_EXTEND is set in the extend control word FIB$W_EXCTL.
188.8.131.52 Input Parameters
Table 1-4 lists
the FIB fields that control the processing of an extend subfunction.
Table 1-4 FIB Fields (Extend Control)
Extend control flags. The following flags
are applicable to the extend subfunction:
Set to enable extension.
Set to inhibit generation of extension
Allocates contiguous space. The
extend operation fails if the necessary contiguous space is not available.
Allocates the maximum amount of
If both FIB$V_ALCON and FIB$V_ALCONB are set, a single contiguous
area, whose size is the largest available but not greater than the
size requested, is allocated.
Marks the file as contiguous.
This bit can only be set if the file does not have space already allocated
Allocates the extend size (FIB$L_EXSZ)
or the system default, whichever is greater.
Specifies the number of blocks to allocate
to the file.
The number of blocks actually allocated for this operation
is returned in this longword. More blocks than requested can be allocated
to meet cluster boundaries.
Returns the starting virtual block number
of the blocks allocated. FIB$L_EXVBN must initially contain 0 blocks.
Contains option bits that control the
placement of allocated blocks. The following bits are defined:
Set to require exact placement;
clear to specify approximate placement. If this bit is set and the
specified blocks are not available, the extend operation fails.
Set to locate allocated space
within a cylinder. This option functions correctly only when FIB$V_ALCON
or FIB$V_ALCONB is specified.
Contains the interpretation mode of the
allocation (FIB$W_ALLOC) field. One of the following values can be
No placement data. The remainder of the
allocation field is ignored.
Location is specified as a byte relative
volume number (RVN) in FIB$B_LOC_RVN and a cylinder number in FIB$L_LOC_ADDR.
Location is specified as a byte RVN in
FIB$B_LOC_RVN, followed by a longword logical block number (LBN) in
Location is specified as a longword virtual
block number (VBN) of the file being extended in FIB$L_LOC_ADDR. A
0 VBN or one that fails to map indicates the end of the file.
Location is specified as a three-word
file ID in FIB$W_LOC_FID, followed by a longword VBN of that file
in FIB$L_LOC_ADDR. A 0 file ID indicates the file being extended.
A 0 VBN or one that fails to map indicates the end of that file.
Contains the desired physical location
of the blocks being allocated. Interpretation of the field is controlled
by the FIB$B_ALALIGN field. The following subfields are defined:
Three-word related file ID for
Related file number.
Related file sequence number.
Related file RVN or placement
Related file number extension.
Placement LBN, cylinder, or VBN.
The specified number of blocks are allocated and
appended to the file. The virtual block number assigned to the first
block allocated is returned in FIB$L_EXVBN. The actual number of blocks
allocated is returned in FIB$L_EXSZ.
The actual number of blocks allocated is also
returned in the second longword of the user's I/O status block.
If a contiguous allocation (FIB$V_ALCON) fails, the size of the largest
contiguous space available on the disk is returned in the second longword
of the user's I/O status block.
The truncate subfunction is used to remove space from
a disk file. This subfunction can be invoked by the major I/O functions
IO$_DEACCESS and IO$_MODIFY (see “Deaccess File” and “Modify File”). The truncate subfunction is performed
if the bit FIB$V_TRUNC is set in the extend control word FIB$W_EXCTL.
184.108.40.206 Input Parameters
Table 1-5 lists the FIB fields that control the processing of a truncate
Table 1-5 FIB Fields (Truncate Control)
Extend control flags. The following flags
are applicable to the truncate subfunction:
Must be set to enable truncation.
Set to append the truncated blocks
to the bad block file, instead of returning them to the free storage
pool. Only one cluster can be deallocated. This is most easily accomplished
by specifying the last VBN of the file in FIB$L_EXVBN. SYSPRV privilege
or ownership of the volume is required to deallocate blocks to the
bad block file.
Returns the actual number of blocks deallocated.
FIB$L_EXSZ must initially contain a value of 0.
Specifies the first virtual block number to be removed from
the file. The actual starting virtual block number of the truncate
operation is returned in this field.
Blocks are deallocated from the file, starting
with the virtual block specified in FIB$L_EXVBN and continuing through
the end of the file. The actual number of blocks deallocated is returned
in FIB$L_EXSZ. The virtual block number of the first block actually
deallocated is returned in FIB$L_EXVBN. Because of cluster round-up,
this value might be greater than the value specified. If FIB$V_MARKBAD
is specified, the truncation VBN is rounded down instead of up, and
the value returned in FIB$L_EXVBN might be less than that specified.
The number of blocks by which FIB$L_EXVBN was
rounded up is returned in the second longword of the I/O status block.
The truncate subfunction normally requires exclusive
access to the file at run time. This means, for example, that a file
cannot be truncated while multiple writers have access to it.
An exception occurs when a truncate subfunction
is requested for a write-accessed file that allows other readers.
Although the truncate subfunction returns success status in this instance,
the actual file truncation (the return of the truncated blocks to
free storage) is deferred until the last reader deaccesses the file.
If a new writer accesses the file after the truncate subfunction is
requested, but before the last deaccess, the deferred truncation is
Once the truncate operation has started, the file
is locked from other writers for the duration of the truncate operation.
Attempts to access the file for shared write access during this time
results in an SS$_ACCONFLICT error.
1.3.5 Read/Write Attributes
The read and write attributes
subfunctions are used for operations such as reading and writing file
protection and creating and revising dates. A read or write attributes
operation is invoked by specifying an attribute list with the QIO
parameter P5. A read attributes operation can be invoked by the major
I/O function IO$_ACCESS (see “Access File”); a write attributes operation can
be invoked by the major I/O functions IO$_CREATE, IO$_DEACCESS, and
IO$_MODIFY (see “Create File”, “Deaccess File”, and “Modify File”).
220.127.116.11 Input Parameters
The read or write attributes subfunction is controlled
by the attribute
list specified by P5. The list consists of a variable number of two
longword control blocks, terminated by a 0 longword, as shown in Figure 1-4. The maximum number of attribute
control blocks in one list is 30. Table 1-6 describes the attribute control block fields.
Figure 1-4 Attribute Control Block Format
Table 1-6 Attribute Control Block Fields
Specifies the number
of bytes of the attribute to be written, or the size of the buffer
into which the attribute is to be read. Legal values for writing attributes
are from 0 to the maximum size of the particular attribute (see Table 1-7), and legal values
for the reading attributes are from 0 to the maximum unsigned 16-bit
Identifies the individual
attribute to be read or written.
Contains the buffer address of the
memory space to or from which the attribute is to be transferred.
The attribute buffer must be writable.
Table 1-7 lists the valid attributes for ACP-QIO functions. The maximum size
(in bytes) is determined by the required attribute configuration.
For example, the Radix-50 file name (ATR$S_FILNAM) uses only 6 bytes,
but it is always accompanied by the file type and file version, so
a total of 10 bytes is required. Each attribute has two names: one
for the code (for example, ATR$C_UCHAR) and one for the size (for
Adds an ACE to the beginning of the ACL when the ACE context value
is 0; to the end of the ACL when the ACE context value is -1; or at
a location pointed to by a prior ACL$C_FNDACETYP or ACL$C_FNDACLENT.
count (2 binary bytes), revision date, creation date, and expiration
date, in ASCII. Format: DDMMMYY (revision date), HHMMSS (time), DDMMMYY
(creation date), HHMMSS (time), DDMMMYY (expiration date). (The format
contains no embedded spaces or commas.)
name, type, and version, in ASCII, including punctuation. Format:
Magnetic tape: contains 17-character
file identifier (ANSI a); no version number. Overrides all other file
name and file type specifications if supplied on input operations.
If specified on an access operation and you want only a value to be
returned, specify (in ATR$W_SIZE) a buffer of greater than 17 bytes.
This section contains descriptions of the following
attribute codes that are listed in Table 1-7:
The ATR$C_ASCNAME attribute allows the file specification
stored in a file's primary file header to be read and written.
Reading the ATR$C_ASCNAME
For ODS-5 volumes, the file specification is returned
in the supplied buffer, and the name format is returned in the FIB$B_ASCNAME_FORMAT
The format in which the name is returned is controlled
by the settings of the FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags
in the same way as the output file specification parameter. A pseudoname
can be returned in place of the actual file specification if the format
is not one of those the calling program can accept.
Unlike the output file specification parameter,
the length of a file specification contained in the ASCNAME attribute
is not passed back explicitly. To determine the length of the file
specification, the calling program must search the attribute buffer
for the first occurrence of the padding character. If neither the
FIB$V_NAMES_8BIT nor the FIB$V_NAMES_16BIT flag is set, the buffer
is padded with space (note that only ODS-2 format names are returned
in this case). If one or more of the flags are set, the attribute
buffer is padded with zeros.
NOTE: The file system does not enforce a minimum length
on the attribute buffer. If the file specification is longer than
the attribute buffer, the value returned is truncated without signaling
an error or warning.
In contrast, the file system does enforce a maximum
size for the attribute buffer. Supplying a larger buffer returns a
Writing the ATR$C_ASCNAME Attribute
The ASCNAME attribute can only be written for
files on ODS-2 or ODS-5 volumes provided that the FIB$V_NAMES_8BIT
and FIB$V_NAMES_16BIT flags are clear.
The ability to write this attribute is only intended
to provide compatibility with existing applications that do so. New
and modified programs should not write this attribute. Changing its
value can prevent a file from being permanently deleted.
In those cases where it is legal to write the
attribute, the contents of the attribute buffer (up to 252 bytes)
are copied to the file name field in the file header. For ODS-5 headers,
the format is set to ODS-2, and the file name length is set to the
offset of the first space character. This can be 252 bytes or the
length of the supplied buffer, whichever is the least.
The FILE_SPEC attribute is a read-only attribute
that returns the physical file specification in the form:
The file name returned is that from the file header,
which may be different from that in the directory. The specification
may be incomplete if any errors are encountered while reading the
file headers of any of the directories in the path.
For files on ODS-5 volumes, the path may contain
file names that are in any of the three name formats. This creates
a number of problems; for instance, the presence of periods in a directory
name could return an ambiguous path specification. To avoid this and
other problems, the file system makes use of services provided by
RMS to translate the file specification and the components of the
path to their escaped form.
If the escaped form of the path is longer than
can be accommodated by the buffer for the attribute, one or more directories
in the path may be replaced by the DID of the rightmost of those replaced.
This process is identical to that performed by RMS.
However, if the file specification, even after
DID abbreviation, is longer than can be accommodated by the buffer,
the file name is truncated. The file specification string returned
to the user buffer has a 2-byte count prefix. The count contains the
number of bytes for the untruncated file specification. If the count
is greater than the size of the user buffer (minus the two bytes that
contain the count), the user can conclude that the returned file specification
has been truncated.
ATR$C_FILNAM, ATR$C_FILTYP, and ATR$C_FILVER
The first two of these attributes allow the file
name and file type to be read and written using Radix-50 encoding.
This encoding scheme enables 3 characters to be packed into a 16-bit
word. Only 38 characters in the ODS-2 format set are valid for Radix-50
names, with the exceptions being dash (-) and underscore (_).
The maximum component lengths of a Radix-50 encoded
file specification are:
File name: 15 characters
File type: 6 characters
As a result of the additional character and length
restrictions, only a subset of legal ODS-2 file names is can be expressed
in the Radix-50 encoding.
The file system only attempts to read or write
the three attributes if the format of the existing file name in the
file header is ODS-2. If this is not the case, a NORAD50 error will
be returned. If the existing file name is in ODS-2 format, but is
incompatible with the Radix-50 encoding or the length limits on Radix-50
file names, a BADFILENAME error will be returned.
The ATR$C_FILVER attribute allows the file version
number in the file header to be read or written as a 2-byte integer.
As the process requires the existing file name to be converted into
a Radix-50 file name, the previous restriction also applies to this