HP OpenVMS Systems Documentation

OpenVMS I/O User's Reference Manual

1.3.5 Read/Write Attributes

The read and write attributes subfunctions are used for operations suchas reading and writing file protection and creating and revising dates.A read or write attributes operation is invoked by specifying anattribute list with the QIO parameter P5. A read attributes operationcan be invoked by the major I/O function IO$_ACCESS (see Section 1.6.2);a write attributes operation can be invoked by the major I/O functionsIO$_CREATE, IO$_DEACCESS, and IO$_MODIFY (see Sections 1.6.1,1.6.3, and 1.6.4).

1.3.5.1 Input Parameters

The read or write attributes subfunction is controlled by theattribute list specified by P5. The list consists of a variable numberof two longword control blocks, terminated by a 0 longword, as shown inFigure 1-6. The maximum number of attribute control blocks in onelist is 30. Table 1-6 describes the attribute control block fields.

Figure 1-6 Attribute Control Block Format

**Table 1-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 Table 1-7), 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 1-7 lists the valid attributes for ACP-QIO functions. Themaximum size (in bytes) is determined by the required attributeconfiguration. For example, the Radix-50 file name (ATR$S_FILNAM) usesonly 6 bytes, but it is always accompanied by the file type and fileversion, so a total of 10 bytes is required. Each attribute has twonames: one for the code (for example, ATR$C_UCHAR) and one for the size(for example, ATR$S_UCHAR).

**Table 1-7 ACP-QIO Attributes**
Attribute Name⁶	Maximum Size (bytes)	Meaning
ATR$C_UCHAR ² ³	4	4-byte file characteristics. (The file characteristics bits are listed following this table.)
ATR$C_RECATTR ⁴	32	Record attribute area. Section 1.4 describes the record attribute area in detail.
ATR$C_FILNAM	10	6-byte Radix-50 file name plus ATR$C_FILTYP and ATR$C_FILVER.
ATR$C_FILTYP	4	2-byte Radix-50 file type plus ATR$C_FILVER.
ATR$C_FILVER	2	2-byte binary version number.
ATR$C_EXPDAT ²	7	Expiration date in ASCII. Format: DDMMMYY.
ATR$C_STATBLK	32	Statistics block. This attribute is read only. Section 1.5 describes the statistics block in detail.
ATR$C_HEADER	512	Complete file header. This attribute is read only.
ATR$C_BLOCKSIZE	2	Magnetic tape block size.
ATR$C_USERLABEL	80	User file label. This attribute is not supported for disk devices.
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_ALCONTROL	14	Compatibility mode allocation data.
ATR$C_ENDLBLAST	4	End of magnetic tape label processing; provides AST control block.
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.
ATR$C_CREDATE ²	8	64-bit creation date and time.
ATR$C_REVDATE ² ⁴	8	64-bit revision date and time.
ATR$C_EXPDATE ²	8	64-bit expiration date and time.
ATR$C_BAKDATE ⁴ ⁵ ⁸ ¹⁰	8	64-bit backup date and time.
ATR$C_UIC ²	4	4-byte file owner UIC.
ATR$C_FPRO ² ⁴	2	File protection.
ATR$C_RPRO ¹⁰	2	2-byte record protection.
ATR$C_ACLEVEL ² ⁴ ⁵ ¹⁰	1	File access level.
ATR$C_SEMASK ¹⁰	8	File security mask and limit.
ATR$C_UIC_RO	4	4-byte file owner UIC. This attribute is read only.
ATR$C_DIRSEQ ¹⁰	2	Directory update sequence count.
ATR$C_BACKLINK ¹⁰	6	File back link pointer.
ATR$C_JOURNAL ¹⁰	1	Journal control flags.
ATR$C_HDR1_ACC	1	ANSI magnetic tape header label accessibility character.
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_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_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_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_DELETEACL ⁷ ¹⁰ ¹¹	255	Deletes the entire ACL with the exception of protected ACEs.
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_ACLLENGTH ¹⁰ ¹¹	4	Returns the size, in bytes, of the object's ACL.
ATR$C_READACE ¹⁰ ¹¹	255	Reads the ACE pointed to by ACL$C_FNDACETYP or ACL$C_FNDACLENT into the buffer.
ATR$C_RESERVED ⁹ ¹⁰	380	Modifies the reserve area.
ATR$C_HIGHWATER ¹⁰	4	High-water mark (user read-only).
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_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_ACCESS_MODE	1	Access mode for following attribute descriptors.
ATR$C_FILE_SPEC ¹⁰	512	Convert FID to file specification.
ATR$C_BUFFER_OFFSET ³	2	Offset length for ANSI magnetic tape header label buffer.
ATR$C_DELETE_ALL ⁷ ¹⁰ ¹¹	255	Delete the entire ACL, including protected entries.
ATR$C_GRANT_ACE ¹⁰ ¹¹	255	Return an ACE that grants or denies access to the object.
ATR$C_NEXT_ACE ¹⁰ ¹¹	4	Advance to the next ACE in the ACL.

¹Not supported for Files-11 C/D.
²Protected (can be written to only by system or owner).
³Not supported on write operations to MTAACP; defaults arereturned on read operations.
⁴Locked (cannot be written to while the file is locked).
⁵For Files-11 C/D, returns 0.
⁶Attributes with an ATR$C_ prefix have two names: one withthe ATR$C_ prefix for the code and one with an ATR$S_ prefix for thesize, which is not included in the list.
⁷Exclusive access required. This operation does not completesuccessfully if other readers or writers are allowed.
⁸Can be written only by the system, owner, or someoneholding READALL privilege.
⁹The actual length available can decrease if the file isextended in a noncontiguous manner or if an ACL is applied to the file.
¹⁰Not supported for Files-11 On-Disk Structure Level 1 ormagnetic tapes.
¹¹The status from this attribute operation is returned inFIB$L_ACL_STATUS.

Table 1-8 lists the bits contained in the file characteristicslongword, which is read with the ATR$C_UCHAR attribute.

**Table 1-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.

¹Files-11 C/D only.

1.4 ACP-QIO Record Attributes Area

Figure 1-7 shows the format of the record attributes area.

Figure 1-7 ACP-QIO Record Attributes Area

Table 1-9 lists the record attributes values and their meanings.

Table 1-9 ACP Record Attributes Values

Field Value

Meaning

FAT$B_RTYPE

Record type. Contains FAT$V_RTYPE and FAT$V_FILEORG.

FAT$V_RTYPE

Record type. The following bit values are defined:

FAT$C_FIXED	Fixed-length record
FAT$C_VARIABLE	Variable-length record
FAT$C_VFC	Variable-length record with fixed control
FAT$C_UNDEFINED	Undefined record format (stream binary)
FAT$C_STREAM	RMS stream format
FAT$C_STREAMLF	Stream terminated by LF
FAT$C_STREAMCR	Stream terminated by CR

FAT$V_FILEORG

File organization. The following bit values are defined:

FAT$C_DIRECT	Direct file organization ¹
FAT$C_INDEXED	Indexed file organization
FAT$C_RELATIVE	Relative file organization
FAT$C_SEQUENTIAL	Sequential file organization

FAT$B_RATTRIB

Record attributes. The following bit values are defined:

FAT$M_FORTRANCC	Fortran carriage control
FAT$M_IMPLIEDCC	Implied carriage control
FAT$M_PRINTCC	Print file carriage control
FAT$M_NOSPAN	No spanned records
FAT$M_MSBRCW ⁴	Record count word (RCW) is MSB formatted

FAT$W_RSIZE

Record size in bytes.

FAT$L_HIBLK ²

Highest allocated VBN. The ACP maintains this field when the file is extended or truncated. Attempts to modify this field in a write attributes operation are ignored.

FAT$W_HIBLKH	High-order 16 bits
FAT$W_HIBLKL	Low-order 16 bits

FAT$L_EFBLK ² ³

End-of-file VBN

FAT$W_EFBLKH	High-order 16 bits
FAT$W_EFBLKL	Low-order 16 bits

FAT$W_FFBYTE ³

First free byte in FAT$L_EFBLK.

FAT$B_BKTSIZE

Bucket size in blocks.

FAT$B_VFCSIZE

Size in bytes of fixed-length control for VFC records.

FAT$W_MAXREC

Maximum record size in bytes.

FAT$W_DEFEXT

Default extend quantity.

FAT$W_GBC

Global buffer count.

FAT$W_VERSIONS

Default version limit; valid only if the file is a directory.

¹Defined but not implemented.
²Inverted format field. The high- and low-order 16 bits aretransposed for compatibility with PDP-11 software.
³When the end-of-file position corresponds to a blockboundary, by convention FAT$L_EFBLK contains the end-of-file VBN plus1, and FAT$W_FFBYTE contains 0.
⁴Variable-length record format (FAT$C_VARIABLE) only.

Contents

Index