[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here 1.3 ACP Subfunctions
HP OpenVMS I/O User’s Reference Manual: OpenVMS Version 8.4 > Chapter 1 ACP-QIO Interface

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

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.

1.3.1.1 Input Parameters

Table 1-2 lists the FIB fields that control the processing of a lookup subfunction.

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

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

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

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

1.3.2.1 Input Parameters

Table 1-3 lists the FIB fields that control the processing of an access subfunction.

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

 

1.3.2.2 Operation

The file is opened according to the access control specified (see Table 1-3).

1.3.3 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 “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.

1.3.3.1 Input Parameters

Table 1-4 lists the FIB fields that control the processing of an extend subfunction.

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

 

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

1.3.4 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 “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.

1.3.4.1 Input Parameters

Table 1-5 lists the FIB fields that control the processing of a truncate subfunction.

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

 

1.3.4.2 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 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”).

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

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 Name[1]

Maximum Size (bytes)

Meaning

ATR$C_ACCDATE[2]

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[3] [4] [5] [6]

1

File access level.

ATR$C_ACLLENGTH[6] [7]

4

Returns the size, in bytes, of the object's ACL.

ATR$C_ADDACLENT[8] [6] [7]

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[3] [9]

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[2]

8

Corresponds to POSIX st_ctime and reflects the last time a file attribute was modified.

ATR$C_BACKLINK[6]

6

File back link pointer.

ATR$C_BAKDATE[4] [5] [10] [6]

8

64-bit backup date and time.

ATR$C_BLOCKSIZE

2

Magnetic tape block size.

ATR$C_BUFFER_OFFSET[9]

2

Offset length for ANSI magnetic tape header label buffer.

ATR$C_CREDATE

8

64-bit creation date and time.

ATR$C_DELACLENT[8] [6] [7]

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[8] [6] [7]

255

Delete the entire ACL, including protected entries.

ATR$C_DELETEACL[8] [6] [7]

255

Deletes the entire ACL with the exception of protected ACEs.

ATR$C_DIRSEQ[6]

2

Directory update sequence count.

ATR$C_ENDLBLAST

4

End of magnetic tape label processing; provides AST control block.

ATR$C_EXPDAT[3]

7

Expiration date in ASCII. Format: DDMMMYY.

ATR$C_EXPDATE[3]

8

64-bit expiration date and time.

ATR$C_FILE_SPEC[6]

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[6] [7]

255

Locates an ACE pointed to by its buffer address.

ATR$C_FNDACETYP[6] [7]

255

Locates an ACE of the type pointed to by its buffer address.

ATR$C_FPRO[3] [4]

2

File protection.

ATR$C_GRANT_ACE[6] [7]

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[6]

4

High-water mark (user read-only).

ATR$C_JOURNAL[6]

1

Journal control flags.

ATR$C_LINKCOUNT

2

Count of hardlinks.

ATR$C_MATCHING_ACE[10] [6]

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[8] [6] [7]

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[2]

8

Corresponds to POSIX st_mtime and reflects the last time data was modified.

ATR$C_NEXT_ACE[6] [7]

4

Advance to the next ACE in the ACL.

ATR$C_PRIVS_USED[6]

4

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

ATR$C_READACE[6] [7]

255

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

ATR$C_READACL[6] [7]

512

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

ATR$C_RECATTR[4]

32

Record attribute area. “ACP-QIO Record Attributes Area” describes the record attribute area in detail.

ATR$C_RESERVED[11]

380

Modifies the reserve area.

ATR$C_REVDATE[3] [4]

8

64-bit revision date and time.

ATR$C_RPRO[6]

2

2-byte record protection.

ATR$C_SEMASK[6]

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[3] [9]

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[3]

4

4-byte file owner UIC.

ATR$C_UIC_RO

4

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

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

 

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

Bits

Meaning

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.

[1] Files-11 C/D only.

 

1.3.5.2 Attribute Descriptions

This section contains descriptions of the following attribute codes that are listed in Table 1-7:

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

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

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.