ACP Subfunctions

If both a Table of Contents and Search form are not displayed in separate frames along with this one, you may wish to redisplay this book in a frameset, beginning with the first page.

HP OpenVMS I/O User's Reference Manual

ACP-QIO Interface

File Information Block (FIB)

ACP-QIO Record Attributes Area

ACP Subfunctions

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 in detail:

Directory Lookup

Access

Extend

Truncate

Read/Write Attributes

Major Functions, which contains the descriptions of the major functions, lists the subfunctions available to each major function.

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.

Input Parameters

FIB Fields (Lookup Control) lists the FIB fields that control the processing of a lookup subfunction.

Table 2 FIB Fields (Lookup Control)
Field Subfields Meaning

FIB$W_NMCTL

Name string control. The following name control bits are applicable to a lookup operation:

FIB$V_ALLNAM
Set to match all name field values.

FIB$V_ALLTYP
Set to match all field type values.

FIB$V_ALLVER
Set to match all version field values.

FIB$V_CASE_SENSITIVE
When set, performs case-sensitive lookup; when clear, performs case-blind lookup.

FIB$V_FINDFID
Set to search a directory for the file ID in FIB$W_FID.

FIB$V_NAMES_8BIT
Caller can accept (8-bit) ODS-2 or ISO Latin-1 formats.

FIB$V_NAMES_16BIT
Caller can accept (16-bit) Unicode (UCS-2) formats.

FIB$V_WILD
Set if name string contains wildcards. Setting this bit causes wildcard context to be returned in FIB$L_WCC.

FIB$W_FID

File identification. The file ID of the file found is returned in this field.

FIB$W_DID

Contains the file identifier of the directory file. This field must be a nonzero number.

FIB$L_WCC

Maintains position context when processing wildcard directory operations.

FIB$L_ACCTL

The following access control flag is applicable to a lookup subfunction:

FIB$V_REWIND
Set to rewind magnetic tape before lookup. If not set, a magnetic tape is searched from its current position.

FIB$B_NAME_FORMAT_IN

Contains the format of the input file specification. The following formats are valid:

FIB$C_ODS2
ODS-2 Format (default)

FIB$C_ISO_LATIN
ISO Latin-1 Format

FIB$C_UCS2
Unicode (UCS-2) Format

FIB$B_NAME_FORMAT_OUT

Contains the format of the output file specification. The following formats are valid:

FIB$C_ODS2
ODS-2 Format (default)

FIB$C_ISO_LATIN
ISO Latin-1 Format

FIB$C_UCS2
Unicode (UCS-2) Format

**Table 2** **FIB Fields (Lookup Control)**
Field	Subfields	Meaning
FIB$W_NMCTL		Name string control. The following name control bits are applicable to a lookup operation:
	FIB$V_ALLNAM	Set to match all name field values.
	FIB$V_ALLTYP	Set to match all field type values.
	FIB$V_ALLVER	Set to match all version field values.
	FIB$V_CASE_SENSITIVE	When set, performs case-sensitive lookup; when clear, performs case-blind lookup.
	FIB$V_FINDFID	Set to search a directory for the file ID in FIB$W_FID.
	FIB$V_NAMES_8BIT	Caller can accept (8-bit) ODS-2 or ISO Latin-1 formats.
	FIB$V_NAMES_16BIT	Caller can accept (16-bit) Unicode (UCS-2) formats.
	FIB$V_WILD	Set if name string contains wildcards. Setting this bit causes wildcard context to be returned in FIB$L_WCC.
FIB$W_FID		File identification. The file ID of the file found is returned in this field.
FIB$W_DID		Contains the file identifier of the directory file. This field must be a nonzero number.
FIB$L_WCC		Maintains position context when processing wildcard directory operations.
FIB$L_ACCTL		The following access control flag is applicable to a lookup subfunction:
	FIB$V_REWIND	Set to rewind magnetic tape before lookup. If not set, a magnetic tape is searched from its current position.
FIB$B_NAME_FORMAT_IN		Contains the format of the input file specification. The following formats are valid:
	FIB$C_ODS2	ODS-2 Format (default)
	FIB$C_ISO_LATIN	ISO Latin-1 Format
	FIB$C_UCS2	Unicode (UCS-2) Format
FIB$B_NAME_FORMAT_OUT		Contains the format of the output file specification. The following formats are valid:
	FIB$C_ODS2	ODS-2 Format (default)
	FIB$C_ISO_LATIN	ISO Latin-1 Format
	FIB$C_UCS2	Unicode (UCS-2) Format

QIO arguments P2 through P5 (see ACP Device- or Function-Dependent Arguments) 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 two formats: name.type;version name.type.version

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 an asterisk.

Note that the file name string cannot contain a directory string. The directory is specified by the FIB$W_DID field (see FIB Fields (Lookup Control)). 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.

Operation

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 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 being returned.

FIB$V_ NAMES_8BIT clear

FIB$V_ NAMES_16BIT set

All file specifications are returned in Unicode (UCS-2) format.

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 Latin-1 format.

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 file header.

Access

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 Sections Create File and Access File). An access subfunction is performed if the IO$M_ACCESS modifier is specified in the I/O function code.

Input Parameters

FIB Fields (Access Control) lists the FIB fields that control the processing of an access subfunction.

Table 3 FIB Fields (Access Control)
Field Subfields Meaning

FIB$L_ACCTL

Specifies field values that control access to the file. The following access control bits are applicable to the access subfunction:

FIB$V_WRITE
Set for write access; clear for read-only access.

FIB$V_NOREAD
Set to deny read access to others. (You must have write privilege to the file to use this option.)

FIB$V_NOWRITE
Set to deny write access to others.

FIB$V_NOTRUNC
Set to prevent the file from being truncated; clear to allow truncation.

FIB$V_CONTROL
Set for control access. If this bit is set, you cannot access the file if you do not have control access.

FIB$V_NO_READ_DATA
Set to deny read access to the file.

FIB$V_DLOCK
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.

FIB$V_UPDATE
Set to position at the start of a magnetic tape file when opening a file for write; clear to position at end-of-file.

FIB$V_READCK
Set to enable read checking of the file. Virtual reads to the file are performed using a data check operation.

FIB$V_WRITECK
Set to enable write checking of the file. Virtual writes to the file are performed using a data check operation.

FIB$V_EXECUTE
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.

FIB$V_NOLOCK
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.

FIB$V_NORECORD
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.

FIB$V_SEQONLY
Set to inform the file system that the file is to be processed sequentially only.

FIB$B_WSIZE

Controls the 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 BYTELIM quota.

FIB$W_FID

Specifies the file identification of the file to be accessed.

**Table 3** **FIB Fields (Access Control)**
Field	Subfields	Meaning
FIB$L_ACCTL		Specifies field values that control access to the file. The following access control bits are applicable to the access subfunction:
	FIB$V_WRITE	Set for write access; clear for read-only access.
	FIB$V_NOREAD	Set to deny read access to others. (You must have write privilege to the file to use this option.)
	FIB$V_NOWRITE	Set to deny write access to others.
	FIB$V_NOTRUNC	Set to prevent the file from being truncated; clear to allow truncation.
	FIB$V_CONTROL	Set for control access. If this bit is set, you cannot access the file if you do not have control access.
	FIB$V_NO_READ_DATA	Set to deny read access to the file.
	FIB$V_DLOCK	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.
	FIB$V_UPDATE	Set to position at the start of a magnetic tape file when opening a file for write; clear to position at end-of-file.
	FIB$V_READCK	Set to enable read checking of the file. Virtual reads to the file are performed using a data check operation.
	FIB$V_WRITECK	Set to enable write checking of the file. Virtual writes to the file are performed using a data check operation.
	FIB$V_EXECUTE	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.
	FIB$V_NOLOCK	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.
	FIB$V_NORECORD	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.
	FIB$V_SEQONLY	Set to inform the file system that the file is to be processed sequentially only.
FIB$B_WSIZE		Controls the 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 BYTELIM quota.
FIB$W_FID		Specifies the file identification of the file to be accessed.

Operation

The file is opened according to the access control specified (see FIB Fields (Access Control)).

Extend

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 Sections 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.

Input Parameters

FIB Fields (Extend Control) lists the FIB fields that control the processing of an extend subfunction.

Table 4 FIB Fields (Extend Control)
Field Subfields Meaning

FIB$W_EXCTL

Extend control flags. The following flags are applicable to the extend subfunction:

FIB$V_EXTEND
Set to enable extension.

FIB$V_NOHDREXT
Set to inhibit generation of extension file headers.

FIB$V_ALCON
Allocates contiguous space. The extend operation fails if the necessary contiguous space is not available.

FIB$V_ALCONB
Allocates the maximum amount of contiguous space.

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.

FIB$V_FILCON
Marks the file as contiguous. This bit can only be set if the file does not have space already allocated to it.

FIB$V_ALDEF
Allocates the extend size (FIB$L_EXSZ) or the system default, whichever is greater.

FIB$L_EXSZ

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.

FIB$L_EXVBN

Returns the starting virtual block number of the blocks allocated. FIB$L_EXVBN must initially contain 0 blocks.

FIB$B_ALOPTS

Contains option bits that control the placement of allocated blocks. The following bits are defined:

FIB$V_EXACT
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.

FIB$V_ONCYL
Set to locate allocated space within a cylinder. This option functions correctly only when FIB$V_ALCON or FIB$V_ALCONB is specified.

FIB$B_ALALIGN

Contains the interpretation mode of the allocation (FIB$W_ALLOC) field. One of the following values can be specified:

(zero)
No placement data. The remainder of the allocation field is ignored.

FIB$C_CYL
Location is specified as a byte relative volume number (RVN) in FIB$B_LOC_RVN and a cylinder number in FIB$L_LOC_ADDR.

FIB$C_LBN
Location is specified as a byte RVN in FIB$B_LOC_RVN, followed by a longword logical block number (LBN) in FIB$L_LOC_ADDR.

FIB$C_VBN
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.

FIB$C_RFI
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.

FIB$W_ALLOC

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:

FIB$W_LOC_FID
Three-word related file ID for RFI placement.

FIB$W_LOC_NUM
Related file number.

FIB$W_LOC_SEQ
Related file sequence number.

FIB$B_LOC_RVN
Related file RVN or placement RVN.

FIB$B_LOC_NMX
Related file number extension.

FIB$L_LOC_ADDR
Placement LBN, cylinder, or VBN.

**Table 4** **FIB Fields (Extend Control)**
Field	Subfields	Meaning
FIB$W_EXCTL		Extend control flags. The following flags are applicable to the extend subfunction:
	FIB$V_EXTEND	Set to enable extension.
	FIB$V_NOHDREXT	Set to inhibit generation of extension file headers.
	FIB$V_ALCON	Allocates contiguous space. The extend operation fails if the necessary contiguous space is not available.
	FIB$V_ALCONB	Allocates the maximum amount of contiguous space.
		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.
	FIB$V_FILCON	Marks the file as contiguous. This bit can only be set if the file does not have space already allocated to it.
	FIB$V_ALDEF	Allocates the extend size (FIB$L_EXSZ) or the system default, whichever is greater.
FIB$L_EXSZ		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.
FIB$L_EXVBN		Returns the starting virtual block number of the blocks allocated. FIB$L_EXVBN must initially contain 0 blocks.
FIB$B_ALOPTS		Contains option bits that control the placement of allocated blocks. The following bits are defined:
	FIB$V_EXACT	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.
	FIB$V_ONCYL	Set to locate allocated space within a cylinder. This option functions correctly only when FIB$V_ALCON or FIB$V_ALCONB is specified.
FIB$B_ALALIGN		Contains the interpretation mode of the allocation (FIB$W_ALLOC) field. One of the following values can be specified:
	(zero)	No placement data. The remainder of the allocation field is ignored.
	FIB$C_CYL	Location is specified as a byte relative volume number (RVN) in FIB$B_LOC_RVN and a cylinder number in FIB$L_LOC_ADDR.
	FIB$C_LBN	Location is specified as a byte RVN in FIB$B_LOC_RVN, followed by a longword logical block number (LBN) in FIB$L_LOC_ADDR.
	FIB$C_VBN	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.
	FIB$C_RFI	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.
FIB$W_ALLOC		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:
	FIB$W_LOC_FID	Three-word related file ID for RFI placement.
	FIB$W_LOC_NUM	Related file number.
	FIB$W_LOC_SEQ	Related file sequence number.
	FIB$B_LOC_RVN	Related file RVN or placement RVN.
	FIB$B_LOC_NMX	Related file number extension.
	FIB$L_LOC_ADDR	Placement LBN, cylinder, or VBN.

Operation

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.

Truncate

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 Sections 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.

Input Parameters

FIB Fields (Truncate Control) lists the FIB fields that control the processing of a truncate subfunction.

Table 5 FIB Fields (Truncate Control)
Field Subfields Meaning

FIB$W_EXCTL

Extend control flags. The following flags are applicable to the truncate subfunction:

FIB$V_TRUNC
Must be set to enable truncation.

FIB$V_MARKBAD
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.

FIB$L_EXSZ

Returns the actual number of blocks deallocated. FIB$L_EXSZ must initially contain a value of 0.

FIB$L_EXVBN

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.

**Table 5** **FIB Fields (Truncate Control)**
Field	Subfields	Meaning
FIB$W_EXCTL		Extend control flags. The following flags are applicable to the truncate subfunction:
	FIB$V_TRUNC	Must be set to enable truncation.
	FIB$V_MARKBAD	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.
FIB$L_EXSZ		Returns the actual number of blocks deallocated. FIB$L_EXSZ must initially contain a value of 0.
FIB$L_EXVBN		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.

Operation

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 ignored.

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 will result in an SS$_ACCONFLICT error.

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 Sections Create File, Deaccess File, and Modify File).

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 Attribute Control Block Format. The maximum number of attribute control blocks in one list is 30. Attribute Control Block Fields describes the attribute control block fields.

Figure 4 Attribute Control Block Format

Table 6 Attribute Control Block Fields
Field Meaning

ATR$W_SIZE
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 ACP-QIO Attributes), and legal values for the reading attributes are from 0 to the maximum unsigned 16-bit integer.

ATR$W_TYPE
Identifies the individual attribute to be read or written.

ATR$L_ADDR
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 6** **Attribute Control Block Fields**
Field	Meaning
ATR$W_SIZE	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 ACP-QIO Attributes), and legal values for the reading attributes are from 0 to the maximum unsigned 16-bit integer.
ATR$W_TYPE	Identifies the individual attribute to be read or written.
ATR$L_ADDR	Contains the buffer address of the memory space to or from which the attribute is to be transferred. The attribute buffer must be writable.

ACP-QIO Attributes 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 example, ATR$S_UCHAR).

Table 7 ACP-QIO Attributes
Attribute Name¹ Maximum Size (bytes) Meaning

ATR$C_ACCDATE²
8
Corresponds to POSIX st_atime and reflects the last time a file was accessed.

ATR$C_ACCESS_MODE
1
Access mode for following attribute descriptors.

ATR$C_ACLEVEL³ ⁴ ⁵ ⁶
1
File access level.

ATR$C_ACLLENGTH ⁷
4
Returns the size, in bytes, of the object's ACL.

ATR$C_ADDACLENT⁸
255
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.

ATR$C_ALCONTROL
14
Compatibility mode allocation data.

ATR$C_ASCDATES ⁹
35
Revision 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.)

ATR$C_ASCNAME
252 (ODS-5) 86 (ODS-2)
File name, type, and version, in ASCII, including punctuation. Format: name.type;version.

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.

See Attribute Descriptions for additional information.

ATR$C_ATTDATE
8
Corresponds to POSIX st_ctime and reflects the last time a file attribute was modified.

ATR$C_BACKLINK
6
File back link pointer.

ATR$C_BAKDATE ¹⁰
8
64-bit backup date and time.

ATR$C_BLOCKSIZE
2
Magnetic tape block size.

ATR$C_BUFFER_OFFSET
2
Offset length for ANSI magnetic tape header label buffer.

ATR$C_CREDATE
8
64-bit creation date and time.

ATR$C_DELACLENT
255
Deletes an access control entry pointed to by the buffer address or, if the buffer address is 0, the ACE pointed to by a prior ACL$C_FNDACETYP or ACL$C_FNDACLENT.

ATR$C_DELETE_ALL
255
Delete the entire ACL, including protected entries.

ATR$C_DELETEACL
255
Deletes the entire ACL with the exception of protected ACEs.

ATR$C_DIRSEQ
2
Directory update sequence count.

ATR$C_ENDLBLAST
4
End of magnetic tape label processing; provides AST control block.

ATR$C_EXPDAT
7
Expiration date in ASCII. Format: DDMMMYY.

ATR$C_EXPDATE
8
64-bit expiration date and time.

ATR$C_FILE_SPEC
4098 (ODS-5)

512 (ODS-2)
Convert FID to file specification. See Attribute Descriptions for additional information.

ATR$C_FILNAM
10
6-byte Radix-50 file name plus ATR$C_FILTYP and ATR$C_FILVER. See Attribute Descriptions for additional information.

ATR$C_FILTYP
4
2-byte Radix-50 file type plus ATR$C_FILVER. See Attribute Descriptions for additional information.

ATR$C_FILVER
2
2-byte binary version number. See Attribute Descriptions for additional information.

ATR$C_FNDACLENT
255
Locates an ACE pointed to by its buffer address.

ATR$C_FNDACETYP
255
Locates an ACE of the type pointed to by its buffer address.

ATR$C_FPRO
2
File protection.

ATR$C_GRANT_ACE
255
Return an ACE that grants or denies access to the object.

ATR$C_HDR1_ACC
1
ANSI magnetic tape header label accessibility character.

ATR$C_HEADER
512
Complete file header. This attribute is read only.

ATR$C_HIGHWATER
4
High-water mark (user read-only).

ATR$C_JOURNAL
1
Journal control flags.

ATR$C_LINKCOUNT
2
Count of hardlinks.

ATR$C_MATCHING_ACE
255
ACE used to gain access (if any). This attribute can only be retrieved on the initial file access or create operation.

ATR$C_MODACLENT
255
Replaces the ACE pointed to by a prior ACL$C_FNDACETYP or ACL$C_FNDACLENT with the ACE pointed to by its buffer address.

ATR$C_MODDATE
8
Corresponds to POSIX st_mtime and reflects the last time data was modified.

ATR$C_NEXT_ACE
4
Advance to the next ACE in the ACL.

ATR$C_PRIVS_USED
4
Privileges used to gain access. This attribute can only be retrieved on the initial file access or create operation.

ATR$C_READACE
255
Reads the ACE pointed to by ACL$C_FNDACETYP or ACL$C_FNDACLENT into the buffer.

ATR$C_READACL
512
Reads the entire ACL or as much as will fit in the supplied buffer. Only complete ACEs are transferred.

ATR$C_RECATTR
32
Record attribute area. ACP-QIO Record Attributes Area describes the record attribute area in detail.

ATR$C_RESERVED¹¹
380
Modifies the reserve area.

ATR$C_REVDATE
8
64-bit revision date and time.

ATR$C_RPRO
2
2-byte record protection.

ATR$C_SEMASK
8
File security mask and limit.

ATR$C_STATBLK
32
Statistics block. This attribute is read only. ACP-QIO Attributes Statistics Block describes the statistics block in detail.

ATR$C_UCHAR
4
4-byte file characteristics. (The file characteristics bits are listed following this table.)

ATR$C_USERLABEL
80
User file label. This attribute is not supported for disk devices.

ATR$C_UIC
4
4-byte file owner UIC.

ATR$C_UIC_RO
4
4-byte file owner UIC. This attribute is read only.

**Table 7** **ACP-QIO Attributes**
Attribute Name¹	Maximum Size (bytes)	Meaning
ATR$C_ACCDATE²	8	Corresponds to POSIX `st_atime` and reflects the last time a file was accessed.
ATR$C_ACCESS_MODE	1	Access mode for following attribute descriptors.
ATR$C_ACLEVEL³ ⁴ ⁵ ⁶	1	File access level.
ATR$C_ACLLENGTH ⁷	4	Returns the size, in bytes, of the object's ACL.
ATR$C_ADDACLENT⁸	255	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.
ATR$C_ALCONTROL	14	Compatibility mode allocation data.
ATR$C_ASCDATES ⁹	35	Revision 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.)
ATR$C_ASCNAME	252 (ODS-5) 86 (ODS-2)	File name, type, and version, in ASCII, including punctuation. Format: name.type;version. 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. See Attribute Descriptions for additional information.
ATR$C_ATTDATE	8	Corresponds to POSIX `st_ctime` and reflects the last time a file attribute was modified.
ATR$C_BACKLINK	6	File back link pointer.
ATR$C_BAKDATE ¹⁰	8	64-bit backup date and time.
ATR$C_BLOCKSIZE	2	Magnetic tape block size.
ATR$C_BUFFER_OFFSET	2	Offset length for ANSI magnetic tape header label buffer.
ATR$C_CREDATE	8	64-bit creation date and time.
ATR$C_DELACLENT	255	Deletes an access control entry pointed to by the buffer address or, if the buffer address is 0, the ACE pointed to by a prior ACL$C_FNDACETYP or ACL$C_FNDACLENT.
ATR$C_DELETE_ALL	255	Delete the entire ACL, including protected entries.
ATR$C_DELETEACL	255	Deletes the entire ACL with the exception of protected ACEs.
ATR$C_DIRSEQ	2	Directory update sequence count.
ATR$C_ENDLBLAST	4	End of magnetic tape label processing; provides AST control block.
ATR$C_EXPDAT	7	Expiration date in ASCII. Format: DDMMMYY.
ATR$C_EXPDATE	8	64-bit expiration date and time.
ATR$C_FILE_SPEC	4098 (ODS-5) 512 (ODS-2)	Convert FID to file specification. See Attribute Descriptions for additional information.
ATR$C_FILNAM	10	6-byte Radix-50 file name plus ATR$C_FILTYP and ATR$C_FILVER. See Attribute Descriptions for additional information.
ATR$C_FILTYP	4	2-byte Radix-50 file type plus ATR$C_FILVER. See Attribute Descriptions for additional information.
ATR$C_FILVER	2	2-byte binary version number. See Attribute Descriptions for additional information.
ATR$C_FNDACLENT	255	Locates an ACE pointed to by its buffer address.
ATR$C_FNDACETYP	255	Locates an ACE of the type pointed to by its buffer address.
ATR$C_FPRO	2	File protection.
ATR$C_GRANT_ACE	255	Return an ACE that grants or denies access to the object.
ATR$C_HDR1_ACC	1	ANSI magnetic tape header label accessibility character.
ATR$C_HEADER	512	Complete file header. This attribute is read only.
ATR$C_HIGHWATER	4	High-water mark (user read-only).
ATR$C_JOURNAL	1	Journal control flags.
ATR$C_LINKCOUNT	2	Count of hardlinks.
ATR$C_MATCHING_ACE	255	ACE used to gain access (if any). This attribute can only be retrieved on the initial file access or create operation.
ATR$C_MODACLENT	255	Replaces the ACE pointed to by a prior ACL$C_FNDACETYP or ACL$C_FNDACLENT with the ACE pointed to by its buffer address.
ATR$C_MODDATE	8	Corresponds to POSIX `st_mtime` and reflects the last time data was modified.
ATR$C_NEXT_ACE	4	Advance to the next ACE in the ACL.
ATR$C_PRIVS_USED	4	Privileges used to gain access. This attribute can only be retrieved on the initial file access or create operation.
ATR$C_READACE	255	Reads the ACE pointed to by ACL$C_FNDACETYP or ACL$C_FNDACLENT into the buffer.
ATR$C_READACL	512	Reads the entire ACL or as much as will fit in the supplied buffer. Only complete ACEs are transferred.
ATR$C_RECATTR	32	Record attribute area. ACP-QIO Record Attributes Area describes the record attribute area in detail.
ATR$C_RESERVED¹¹	380	Modifies the reserve area.
ATR$C_REVDATE	8	64-bit revision date and time.
ATR$C_RPRO	2	2-byte record protection.
ATR$C_SEMASK	8	File security mask and limit.
ATR$C_STATBLK	32	Statistics block. This attribute is read only. ACP-QIO Attributes Statistics Block describes the statistics block in detail.
ATR$C_UCHAR	4	4-byte file characteristics. (The file characteristics bits are listed following this table.)
ATR$C_USERLABEL	80	User file label. This attribute is not supported for disk devices.
ATR$C_UIC	4	4-byte file owner UIC.
ATR$C_UIC_RO	4	4-byte file owner UIC. This attribute is read only.

File Characteristics Bits lists the bits contained in the file characteristics longword, which is read with the ATR$C_UCHAR attribute.

Table 8 File Characteristics Bits
FCH$M_NOBACKUP
Do not back up file.

FCH$M_READCHECK
Verify all read operations.

FCH$M_WRITCHECK
Verify all write operations.

FCH$M_CONTIGB
Keep file as contiguous as possible.

FCH$M_LOCKED
File is deaccess-locked.

FCH$M_CONTIG
File is contiguous.

FCH$M_BADACL
File's ACL is corrupt.

FCH$M_SPOOL
File is an intermediate spool file.

FCH$M_DIRECTORY
File is a directory.

FCH$M_BADBLOCK
File contains bad blocks.

FCH$M_MARKDEL
File is marked for deletion.

FCH$M_ERASE
Erase file contents before deletion.

FCH$M_ASSOCIATED¹²
File has an associated file.

FCH$M_EXISTENCE
Suppress existence of file.

FCH$M_NOMOVE
Disable movefile operations on this file.

FCH$M_NOSHELVABLE
File is not shelvable.

FCH$M_SHELVED
File is shelved.

**Table 8** **File Characteristics Bits**
FCH$M_NOBACKUP	Do not back up file.
FCH$M_READCHECK	Verify all read operations.
FCH$M_WRITCHECK	Verify all write operations.
FCH$M_CONTIGB	Keep file as contiguous as possible.
FCH$M_LOCKED	File is deaccess-locked.
FCH$M_CONTIG	File is contiguous.
FCH$M_BADACL	File's ACL is corrupt.
FCH$M_SPOOL	File is an intermediate spool file.
FCH$M_DIRECTORY	File is a directory.
FCH$M_BADBLOCK	File contains bad blocks.
FCH$M_MARKDEL	File is marked for deletion.
FCH$M_ERASE	Erase file contents before deletion.
FCH$M_ASSOCIATED¹²	File has an associated file.
FCH$M_EXISTENCE	Suppress existence of file.
FCH$M_NOMOVE	Disable movefile operations on this file.
FCH$M_NOSHELVABLE	File is not shelvable.
FCH$M_SHELVED	File is shelved.

Attribute Descriptions

This section contains descriptions of the following attribute codes that are listed in ACP-QIO Attributes:

ATR$C_ASCNAME

ATR$C_FILE_SPEC

ATR$C_FILNAM

ATR$C_FILTYP

ATR$C_FILVER

ATR$C_ASCNAME

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 Attribute

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 cell.

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.

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 BADPARAM error.

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.

ATR$C_FILE_SPEC

The FILE_SPEC attribute is a read-only attribute that returns the physical file specification in the form:

DDnn:[DIR1.DIR2_DIRn]name.type;1

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.

When you access files on an ODS-5 volume from a VAX system in a mixed architecture OpenVMS system, no escaped forms are returned. For an ODS-2 or ISO Latin-1 file format, the name stored in the file header is returned. For a UCS-2 file format, a pseudoname is returned, followed by the file identifier in parentheses. For example: DKA100:[ABC]\pUNICODE\.??? (10095,5,0)

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 (10 bytes)

File type: 6 characters (4 bytes)

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 attribute.

Footnotes

1 Attributes with an ATR$C_ prefix have two names: one with the ATR$C prefix for the code and one with an ATR$S_ prefix for the size, which is not included in the list.

2 Not supported by all ACPs. Maintained on ODS-5 volumes when access dates are enabled using the DCL INITIALIZE or SET VOLUME commands. Not maintained on ODS-2 volumes.

3 Protected (can be written to only by system or owner).

4 Locked (cannot be written to while the file is locked).

5 For Files-11 C/D; returns 0.

6 Not supported for Files-11 On Disk Structure Level 1 or magnetic tapes.

7 The status from this attribute operation is returned in FIB$L_ACL_STATUS.

8 Exclusive access required. This operation does not complete successfully if other readers or writers are allowed.

9 Not supported on writer operations to MTAACP; defaults are returned on read operations.

10 Can be written only by the system, owner, or someone holding READALL privilege.

11 The actual length available can decrease if the file is extended in a noncontiguous manner or if an ACL is applied to the file.

12 Files-11 C/D only.

( Number takes you back )

File Information Block (FIB)

ACP-QIO Record Attributes Area