HP OpenVMS Systems Documentation

Content starts here

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 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). 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 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.
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 arereturned 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 withthe ATR$C_ prefix for the code and one with an ATR$S_ prefix for thesize, which is not included in the list.
7Exclusive access required. This operation does not completesuccessfully if other readers or writers are allowed.
8Can be written only by the system, owner, or someoneholding READALL privilege.
9The actual length available can decrease if the file isextended in a noncontiguous manner or if an ACL is applied to the file.
10Not supported for Files-11 On-Disk Structure Level 1 ormagnetic tapes.
11The 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 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 aretransposed for compatibility with PDP-11 software.
3When 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.
4Variable-length record format (FAT$C_VARIABLE) only.

Previous Next Contents Index