Document revision date: 30 March 2001

## OpenVMS I/O User's Reference Manual

Previous | Contents | Index

### 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 Section 1.6.2); a write attributes operation can be invoked by the major I/O functions IO$_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 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-6. The maximum number of attribute control blocks in one list 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. 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 1-7 ACP-QIO Attributes
Attribute Name6 | Maximum Size (bytes) | Meaning
--- | --- | ---
ATR$C_UCHAR 2 3 | 4 | 4-byte file characteristics. (The file characteristics bits are listed following this table.)
ATR$C_RECATTR 4 | 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 2 | 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 2 3 | 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 2 | 8 | 64-bit creation date and time.
ATR$C_REVDATE 2 4 | 8 | 64-bit revision date and time.
ATR$C_EXPDATE 2 | 8 | 64-bit expiration date and time.
ATR$C_BAKDATE 4 5 8 10 | 8 | 64-bit backup date and time.
ATR$C_UIC 2 | 4 | 4-byte file owner UIC.
ATR$C_FPRO 2 4 | 2 | File protection.
ATR$C_RPRO 10 | 2 | 2-byte record protection.
ATR$C_ACLEVEL 2 4 5 10 | 1 | File access level.
ATR$C_SEMASK 10 | 8 | File security mask and limit.
ATR$C_UIC_RO | 4 | 4-byte file owner UIC. This attribute is read only.
ATR$C_DIRSEQ 10 | 2 | Directory update sequence count.
ATR$C_BACKLINK 10 | 6 | File back link pointer.
ATR$C_JOURNAL 10 | 1 | Journal control flags.
ATR$C_HDR1_ACC | 1 | ANSI magnetic tape header label accessibility character.
ATR$C_ADDACLENT 7 10 11 | 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 7 10 11 | 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 7 10 11 | 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 10 11 | 255 | Locates an ACE pointed to by its buffer address.
ATR$C_FNDACETYP 10 11 | 255 | Locates an ACE of the type pointed to by its buffer address.
ATR$C_DELETEACL 7 10 11 | 255 | Deletes the entire ACL with the exception of protected ACEs.
ATR$C_READACL 10 11 | 512 | Reads the entire ACL or as much as will fit in the supplied buffer. Only complete ACEs are transferred.
ATR$C_ACLLENGTH 10 11 | 4 | Returns the size, in bytes, of the object's ACL.
ATR$C_READACE 10 11 | 255 | Reads the ACE pointed to by ACL$C_FNDACETYP or ACL$C_FNDACLENT into the buffer.
ATR$C_RESERVED 9 10 | 380 | Modifies the reserve area.
ATR$C_HIGHWATER 10 | 4 | High-water mark (user read-only).
ATR$C_PRIVS_USED 10 | 4 | Privileges used to gain access. This attribute can only be retrieved on the initial file access or create operation.
ATR$C_MATCHING_ACE 8 10 | 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 10 | 512 | Convert FID to file specification.
ATR$C_BUFFER_OFFSET 3 | 2 | Offset length for ANSI magnetic tape header label buffer.
ATR$C_DELETE_ALL 7 10 11 | 255 | Delete the entire ACL, including protected entries.
ATR$C_GRANT_ACE 10 11 | 255 | Return an ACE that grants or denies access to the object.
ATR$C_NEXT_ACE 10 11 | 4 | Advance to the next ACE in the ACL.

1Not supported for Files-11 C/D.
2Protected (can be written to only by system or owner).
3Not supported on write operations to MTAACP; defaults are returned on read operations.
4Locked (cannot be written to while the file is locked).
5For Files-11 C/D, returns 0.
6Attributes 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.
7Exclusive access required. This operation does not complete successfully if other readers or writers are allowed.
8Can be written only by the system, owner, or someone holding READALL privilege.
9The actual length available can decrease if the file is extended in a noncontiguous manner or if an ACL is applied to the file.
10Not supported for Files-11 On-Disk Structure Level 1 or magnetic tapes.
11The status from this attribute operation is returned in FIB$L_ACL_STATUS.

Table 1-8 lists the bits contained in the file characteristics longword, 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 1 | File has an associated file.
FCH$M_EXISTENCE 1 | 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.

1Files-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 1
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 4 | Record count word (RCW) is MSB formatted
FAT$W_RSIZE | Record size in bytes.
FAT$L_HIBLK 2 | 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 2 3 | End-of-file VBN
FAT$W_EFBLKH | High-order 16 bits
FAT$W_EFBLKL | Low-order 16 bits
FAT$W_FFBYTE 3 | 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.

1Defined but not implemented.
2Inverted format field. The high- and low-order 16 bits are transposed for compatibility with PDP-11 software.
3When the end-of-file position corresponds to a block boundary, by convention FAT$L_EFBLK contains the end-of-file VBN plus 1, and FAT$W_FFBYTE contains 0.
4Variable-length record format (FAT$C_VARIABLE) only.

Previous | Next | Contents | Index

| privacy and legal statement |
6136PRO_002.HTML