Document revision date: 15 July 2002

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

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_ACCDATE 12	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 2 4 5 10	1	File access level.
ATR$C_ACLLENGTH 10 11	4	Returns the size, in bytes, of the object's ACL.
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_ALCONTROL	14	Compatibility mode allocation data.
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_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 Section 1.3.5.2 for additional information.
ATR$C_ATTDATE 12	8	Corresponds to POSIX st_ctime and reflects the last time a file attribute was modified.
ATR$C_BACKLINK 10	6	File back link pointer.
ATR$C_BAKDATE 4 5 8 10	8	64-bit backup date and time.
ATR$C_BLOCKSIZE	2	Magnetic tape block size.
ATR$C_BUFFER_OFFSET 3	2	Offset length for ANSI magnetic tape header label buffer.
ATR$C_CREDATE 2	8	64-bit creation date and time.
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_DELETE_ALL 7 10 11	255	Delete the entire ACL, including protected entries.
ATR$C_DELETEACL 7 10 11	255	Deletes the entire ACL with the exception of protected ACEs.
ATR$C_DIRSEQ 10	2	Directory update sequence count.
ATR$C_ENDLBLAST	4	End of magnetic tape label processing; provides AST control block.
ATR$C_EXPDAT 2	7	Expiration date in ASCII. Format: DDMMMYY.
ATR$C_EXPDATE 2	8	64-bit expiration date and time.
ATR$C_FILE_SPEC 10	4098 (ODS-5) 512 (ODS-2)	Convert FID to file specification. See Section 1.3.5.2 for additional information.
ATR$C_FILNAM	10	6-byte Radix-50 file name plus ATR$C_FILTYP and ATR$C_FILVER. See Section 1.3.5.2 for additional information.
ATR$C_FILTYP	4	2-byte Radix-50 file type plus ATR$C_FILVER. See Section 1.3.5.2 for additional information.
ATR$C_FILVER	2	2-byte binary version number. See Section 1.3.5.2 for additional information.
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_FPRO 2 4	2	File protection.
ATR$C_GRANT_ACE 10 11	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 10	4	High-water mark (user read-only).
ATR$C_JOURNAL 10	1	Journal control flags.
ATR$C_LINKCOUNT	2	Count of hardlinks.
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_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_MODDATE 12	8	Corresponds to POSIX st_mtime and reflects the last time data was modified.
ATR$C_NEXT_ACE 10 11	4	Advance to the next ACE in the ACL.
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_READACE 10 11	255	Reads the ACE pointed to by ACL$C_FNDACETYP or ACL$C_FNDACLENT into the buffer.
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_RECATTR 4	32	Record attribute area. Section 1.4 describes the record attribute area in detail.
ATR$C_RESERVED 9 10	380	Modifies the reserve area.
ATR$C_REVDATE 2 4	8	64-bit revision date and time.
ATR$C_RPRO 10	2	2-byte record protection.
ATR$C_SEMASK 10	8	File security mask and limit.
ATR$C_STATBLK	32	Statistics block. This attribute is read only. Section 1.5 describes the statistics block in detail.
ATR$C_UCHAR 2 3	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 2	4	4-byte file owner UIC.
ATR$C_UIC_RO	4	4-byte file owner UIC. This attribute is read only.

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.

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.

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 expressible 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 above restriction also applies to this attribute.

	privacy and legal statement
6136PRO_002.HTML