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.

name.type;version name.type.version

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

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 Section 1.6.1, “Create File” and Section 1.6.4, “Modify File”). The extend subfunction is performed if the bit FIB$V_EXTEND is set in the extend control word FIB$W_EXCTL.

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 Section 1.6.3, “Deaccess File” and Section 1.6.4, “Modify File”). The truncate subfunction is performed if the bit FIB$V_TRUNC is set in the extend control word FIB$W_EXCTL.

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, “Access File”); a write attributes operation can be invoked by the major I/O functions IO$_CREATE, IO$_DEACCESS, and IO$_MODIFY (see Section 1.6.1, “Create File”, Section 1.6.3, “Deaccess File”, and Section 1.6.4, “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, “Attribute Control Block Format”.The maximum number of attribute control blocks in one list is 30. Table 1.6, “Attribute Control Block Fields” describes the 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, “ACP-QIO Attributes”), 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, “ACP-QIO Attributes” 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).

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

Table 1.8, “File Characteristics Bits” lists the bits contained in the file characteristics longword, which is read with the ATR$C_UCHAR attribute.

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?	File has an associated file.
FCH$M_EXISTENCE?	Suppress existence of file.
FCH$M_NOMOVE	Disable move file operations on this file.
FCH$M_NOSHELVABLE	File is not shelvable.
FCH$M_SHELVED	File is shelved.

DDnn:[DIR1.DIR2_DIRn]name.type;1

Create file is a virtual I/O function that creates a directory entry or a file on a disk device, or a file on a magnetic tape device.

This virtual I/O function searches a directory on a disk device or a magnetic tape for a specified file and accesses that file if found.

The following is the function code:

The following are the function modifiers:

De access file is a virtual I/O function that deaccesses a file and, if specified, writes final attributes in the file header.

IO$_DEACCESS takes no function modifiers.

Modify file is a virtual I/O function that modifies the file attributes or allocation of a disk file. The IO$_MODIFY function is not applicable to magnetic tape; that is, the function returns success, but no action is performed.

The following is the function code:

The following is the function modifier:

Delete file is a virtual I/O function that removes a directory entry or file header from a disk volume.

The following is the function code:

The following is the function modifier:

The following are the device- or function-dependent arguments for IO$_DELETE:

The following FIB fields are applicable to the IO$_DELETE function:

The movefile subfunction permits you to move the contents of a file, or part of the contents of a file, to a new disk location. This subfunction can, for example, form the basis of a disk defragmentation application.

You can disable movefile operations on specific user files by specifying the /NOMOVE qualifier on the SET FILE command. Use the DIRECTORY/FULL and the DUMP/HEADER commands to find out if movefile operations are disabled on a file.

On Alpha and Integrity server systems, mount is a virtual I/O function that informs the ACP when a disk or magnetic tape volume is mounted. MOUNT privilege is required. IO$_MOUNT takes no arguments or function modifiers. This function is part of the volume mounting operation only, and it is not meant for general use. Most of the actual processing is performed by the MOUNT command or the Mount Volume ($MOUNT) system service.

ACP Control is a virtual I/O function that performs ancillary control functions, depending on the arguments specified.

The following is the function code:

The following is the function modifier:

1.6.8.4. Disk Quotas

Disk quota enforcement is enabled by a quota file on the volume, or relative volume 1 if the file is on a volume set. The quota file appears in the volume's master file directory (MFD) under the name QUOTA.SYS;1. This section describes the control functions that operate on the quota file.

Table 1.16, “Disk Quota Functions (Enable/Disable)” lists the enable and disable quota control functions.

Value	Meaning
FIB$C_ENA_QUOTA	Enable the disk quota file. If a nonzero directory file ID is specified in FIB$W_DID, a lookup subfunction is performed to locate the quota file (see Section 1.3.1, “Directory Lookup”). To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume. The quota file specified by FIB$W_FID, if present, is accessed by the ACP, and quota enforcement is turned on. By convention, the quota file is named [0,0]QUOTA.SYS;1. Therefore, FIB$W_DID should contain the value 4,4,0 and the name string specified with P2 should be “QUOTA.SYS;1”.
FIB$C_DSA_QUOTA	Disable the disk quota file. The quota file is deaccessed and quota enforcement is turned off. To issue this function, you must have either a system UIC or SYSPRV privilege, or be the owner of the volume.

Table 1.17, “Disk Quota Functions (Individual Entries)” lists the quota control functions that operate on individual entries in the quota file. Each operation transfers quota file data to and from the ACP using a quota data block. This block has the same format as a record in the quota file. Figure 1.7, “Quota File Transfer Block” shows the format of this block.

Value	Meaning
FIB$C_ADD_QUOTA	Add an entry to the disk quota file, using the UIC and quota specified in the P2 argument block. FIB$C_ADD_QUOTA requires write access to the quota file.
FIB$C_EXA_QUOTA	Examine a disk quota file entry. The entry whose UIC is specified in the P2 argument block is returned in the P4 argument block, and its length is returned in the P3 argument word. Using two flags in FIB$L_CNTRLVAL, it is possible to search through the quota file using wildcards. The two flags are:
	FIB$V_ALL_MEM	Match all UIC members
	FIB$V_ALL_GRP	Match all UIC groups
	The ACP maintains position context in FIB$L_WCC. On the first examine call, you specify 0 in FIB$L_WCC; the ACP returns a nonzero value so that each succeeding examine call returns the next matching entry. Read access to the quota file is required to examine all nonuser entries.
FIB$C_MOD_QUOTA	Modify a disk quota file entry. The quota file entry specified by the UIC in the P2 argument block is modified according to the values in the block, as controlled by the following three flags in FIB$L_CNTRLVAL:
	FIB$V_MOD_PERM	Change the permanent quota
	FIB$V_MOD_OVER	Change the overdraft quota
	FIB$V_MOD_USE	Change the usage data
	The usage data can be changed only if the volume is locked by FIB$C_LOCK_VOL (see Section 1.6.8.3, “Miscellaneous Disk Control Functions”). FIB$C_MOD_QUOTA requires write access to the quota file. The P3 and P4 arguments return the modified quota entry to you. By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search through the quota file using wildcards just as you would with the FIB$C_EXA_QUOTA function.
FIB$C_REM_QUOTA	Remove a disk quota file entry whose UIC is specified in the P2 argument block. FIB$C_REM_QUOTA requires write access to the quota file. The P3 and P4 arguments return the removed quota file entry to you. By using the flags FIB$V_ALL_MEM and FIB$V_ALL_GRP, you can search through the quota file using wildcards just as you would with the FIB$C_EXAQUOTA function.

IO$_ACPCONTROL functions that transfer quota file data between the caller and the ACP use the following device- or function-dependent arguments:

• P2—The address of a descriptor for the quota data block being sent to the ACP.

• P3—The address of a word that returns the data length.

• P4—The address of a descriptor for a buffer to receive the quota data block returned from the ACP.

A data check is made after successful completion of a read or write operation and, except for the TU58, compares the data in memory with the data on disk to make sure they match.

Disk drivers support data checks at the following levels:

Offset recovery is performed during a data check, but error code correction (ECC) is not performed (see Section 2.1.3, “Error Recovery”). For example, if a read operation is performed and an ECC correction is applied, the data check would fail even though the data in memory is correct. In this case, the driver returns a status code indicating that the operation was completed successfully, but the data check could not be performed because of an ECC correction.

Data checks on read operations are extremely rare, and you can either accept the data as is, treat the ECC correction as an error, or accept the data but immediately move it to another area on the disk volume.

A data check operation directed to a TU58 does not compare the data in memory with the data on tape. Instead, either a read check or a write check operation is performed (see Section 2.3.1, “Read” and Section 2.3.2, “Write”).

The operating system ensures that when an I/O write operation returns a successful completion status, the data is available on the disk or tape media. Applications that must guarantee the successful completion of a write operation can verify that the data is on the media by specifying the data check function modifier IO$M_DATACHECK. Note that the IO$M_DATACHECK data check function, which compares the data in memory with the data on disk, affects performance because the function incurs the overhead of an additional read operation to the media.

If a system failure occurs while a multiple-block write operation is in progress, the operating system does not guarantee the successful completion of the write operation. (OpenVMS does guarantee single-block write operations to DSA drives.) When a failure interrupts a write operation, the data may be left in any one of the following conditions:

To guarantee that a write operation either finishes successfully or (in the event of failure) is redone or rolled back as if it were never started, use additional techniques to ensure data correctness and recovery. For example, using database journaling and recovery techniques allows applications to recover automatically from failures such as the following:

Error recovery in the operating system is aimed at performing all possible operations to complete an I/O operation successfully. Error recovery operations fall into the following categories:

The error recovery algorithm uses a combination of these four types of error recovery operations to complete an I/O operation:

Although SCSI disks do not conform to DSA, they do support the following error recovery features:

All SCSI disks supplied by HPE implement the REASSIGN BLOCKS command, which relocates data for a specific logical block to a different physical location on the disk. The SCSI disk class driver reassigns the block in the following instances: (1) when the retry threshold is exceeded during an attempt to read or write a block of data on the disk or (2) when an irrecoverable error occurs during a write operation.

Unlike DSA, there is no forced error flag in SCSI. Blocks that produce irrecoverable errors during read operations are not reassigned in order to prevent undetected loss of user data. Instead, the SCSI disk class driver returns the SS$_PARITY status whenever a read operation results in an irrecoverable error.

The operating system provides audio functionality through the SCSI disk class driver. The SCSI disk class driver provides an interface by which the audio commands can be issued to SCSI devices. These commands can be issued through the QIO function call. This functionality is available for devices, such as CD-ROMs that have audio capability.

The IO$_AUDIO function code allows the SCSI disk class driver to process the SCSI audio commands. An Audio Control Block (AUCB) must be defined for a specific SCSI audio command. This AUCB provides the SCSI disk class driver with command-specific arguments and control information. An application program must use the IO$_AUDIO function code and provide the AUCB for the SCSI driver to process the audio commands.

For more information, see Section 2.3.11.1, “$QIO Interface to Audio Functionality of the SCSI Disk Class Driver”.

The read function reads data into a specified buffer from disk starting at a specified disk address.

The operating system provides the following read function codes:

If a read virtual block function is directed to a volume that is mounted foreign, that function is converted to read logical block. If a read virtual block function is directed to a volume that is mounted structured, the volume is handled in the same way as for a file-structured device.

Three function-dependent arguments are used with these codes: P1, P2, and P3. These arguments are described in Section 2.3, “Disk Function Codes”.

The data check function modifier (IO$M_DATACHECK) can be used with all read functions. If this modifier is specified, a data check operation is performed after the read operation completes. A data check operation is also performed if the volume that has been read, or the volume on which the file resides (virtual read) has the characteristic “data check all reads.” Furthermore, a data check is performed after a virtual read if the file has the attribute “data check on read.” The RX01 and RX02 drivers do not support the data check function.

If IO$M_DATACHECK is specified with a read function code to a TU58, or if the volume read has the characteristic “data check all reads,” a read check operation is performed. This alters certain TU58 hardware parameters when the tape is read. (The read threshold in the data recovery circuit is increased; if the tape has any weak spots, errors are detected.)

The data check function modifier to a disk or tape can return five error codes in the I/O status block:

If no errors are detected, the disk or tape data is considered reliable.

The inhibit retry function modifier (IO$M_INHRETRY) can be used with all read functions. If this modifier is specified, all error recovery attempts are inhibited. IO$M_INHRETRY takes precedence over IO$M_DATACHECK. If both are specified and an error occurs, there is no attempt at error recovery and no data check operation is performed. If an error does not occur, the data check operation is performed.

The write function writes data from a specified buffer to disk starting at a specified disk address.

The operating system provides the following write function codes:

If a write virtual block function is directed to a volume that is mounted foreign, the function is converted to write logical block. If a write virtual block function is directed to a volume that is mounted structured, the volume is handled in the same way as for a file-structured device.

Three function-dependent arguments are used with these codes: P1, P2, and P3. These arguments are described in Section 2.3, “Disk Function Codes”.

The data check function modifier (IO$M_DATACHECK) can be used with all write operations. If this modifier is specified, a data check operation is performed after the write operation completes. A data check operation is also performed if the volume written, or the volume on which the file resides (virtual write), has the characteristic “data check all writes.” Furthermore, a data check is performed after a virtual write if the file has the attribute “data check on write.” The RX01 and RX02 drivers do not support the data check function.

If IO$M_DATACHECK is specified with a write function code to a TU58, or if the volume written has the characteristic “data check all writes,” a write check operation is performed. The write check verifies data written on the tape. First, the specified data is written on the tape. Then the tape is reversed and the TU58 controller reads the data internally to perform a checksum verification. If the checksum verification is unsuccessful after eight attempts, the write check operation is aborted and an error status is returned.

The inhibit retry function modifier (IO$M_INHRETRY) can be used with all write functions. If that modifier is specified, all error recovery attempts are inhibited. IO$M_INHRETRY takes precedence over IO$M_DATACHECK. If both IO$M_INHRETRY and IO$M_DATACHECK are specified and an error occurs, there is no attempt at error recovery, and no data check operation is performed. If an error does not occur, the data check operation is performed. IO$M_INHRETRY has no effect on DSA disks.

The write deleted data function modifier (IO$M_DELDATA) can be used with the write physical block (IO$_WRITEPBLK) function to the RX02. If this modifier is specified, a deleted data address mark instead of the standard data address mark is written preceding the data. Otherwise, the operation of the IO$_WRITEPBLK function is the same; write data is transferred to the disk. When a successful read operation is performed on this data, the status code SS$_RDDELDATA is returned in the I/O status block rather than the usual SS$_NORMAL status code.

The IO$M_ERASE function modifier can be used with all write function codes to erase a user-selected part of a disk. This modifier propagates an erase pattern through the specified range. Section 2.3, “Disk Function Codes” describes the write function arguments to be used with IO$M_ERASE.

Sense mode operations obtain current disk device-dependent characteristics that are returned to the caller in the second longword of the I/O status block (see Figure 2.6, “IOSB Contents for the Sense Mode Function”). The operating system provides the following function codes:

IO$_SENSEMODE is a logical function. IO$_SENSECHAR is a physical I/O function and requires the access privilege necessary to perform physical I/O. No device- or function-dependent arguments are used with either function.

The set density function assigns a new density to an entire RX02 diskette. The diskette is also reformatted: new data address marks are written (single or double density) and all data fields are zeroed. Set density is a physical I/O function and requires the access privilege necessary to perform physical I/O. The following function code is provided:

IO$_FORMAT takes the following function-dependent argument:

The set density operation should not be interrupted before it is completed (about 15 seconds). If the operation is interrupted, the resulting diskette might contain illegal data address marks in both densities. The diskette must then be completely reformatted and the function reissued.

The search function positions a TU58 magnetic tape to the block specified. Search is a physical I/O function and requires the access privilege necessary to perform physical I/O. The operating system provides a single function code:

This function code takes the following function-dependent argument:

IO$_SEARCH can save time between read and write operations. For example, nearly 30 seconds are required to completely rewind a tape. If the last read or write operation is near the end of the tape and the next operation is near the beginning of the tape, the search operation can begin after the last operation completes, and the tape rewinds while the process is otherwise occupied. (The search QIO is not completed until the search is completed. Consequently, if a $QIOW system service request is issued, the process is held up until the search is completed.)

The pack acknowledge function sets the volume valid bit for all disk devices. Pack acknowledge is a physical I/O function and requires the access privilege to perform physical I/O. If directed to an RX02 disk, pack acknowledge also determines the diskette density and updates the device-dependent information returned by $GETDVI item codes DVI$_CYLINDERS, DVI$_TRACKS, DVI$_SECTORS, DVI$_DEVTYPE, DVI$_CLASS, and DVI$_MAXBLOCK. If directed to a DSA disk, pack acknowledge also sends the online packet to the controller. The following function code is provided:

This function code takes no function-dependent arguments.

IO$_PACKACK must be the first function issued when a volume (pack, cartridge, or diskette) is placed in a disk drive. IO$_PACKACK is issued automatically when the DCL commands INITIALIZE or MOUNT are issued.

For DSA disks, the IO$_PACKACK function locks the drive's port selector on the port that initiated the pack acknowledge function.

In addition, the IO$_PACKACK function updates device-dependent information about DSA disks returned by $GETDVI.

The unload function clears the volume valid bit for all disk drives, makes DSA disks available, and issues an unload command to the drive (spins down the volume). The unload function reverses the function performed by pack acknowledge (see Section 2.3.6, “Pack Acknowledge”). The following function code is provided:

This function takes no function-dependent arguments.

The available function clears the volume valid bit for all disk drives; that is, it reverses the function performed by pack acknowledge (see Section 2.3.6, “Pack Acknowledge”). No unload function is issued to the drive; therefore, those drives capable of spinning down do not spin down. The following function code is provided:

This function takes no function-dependent arguments.

The seek function directs the read/write heads to move to the cylinder specified in the P1 argument (see Section 2.3, “Disk Function Codes” and Figure 2.2, “Physical Cylinder Number Format”).

The write check function verifies that data was written to disk correctly. The data to be checked is addressed using physical disk addressing (sector, track, and cylinder) (see Figure 2.1, “Starting Physical Address”). If the request is directed to a DSA disk, you must specify a logical block number, even though IO$_WRITECHECK is a physical I/O function. The following function code is provided:

A write QIO must be used to write data to disk before you enter this command. IO$_WRITECHECK then reads the same block of data and compares it with the data in the specified buffer. Three function-dependent arguments are used with this code: P1, P2, and P3. These arguments are described in Section 2.3, “Disk Function Codes”.

IO$_WRITECHECK is similar to the IO$M_DATACHECK function modifier for write QIOs, except that IO$_WRITECHECK does not write the data to disk; it is specified after data is written by a separate write QIO. Nonprivileged processes can use the IO$M_DATACHECK modifier with IO$_WRITEVBLK (which does not require access privilege) to determine whether data is written correctly. The RX01 and RX02 drivers do not support the write check function.

The write check function and the data check function modifier to a TU58 can return six error codes in the I/O status block: SS$_NORMAL, SS$_CTRLERR, SS$_DRVERR, SS$_MEDOFL, SS$_NONEXDRV, and SS$_WRTLCK.

The OpenVMS operating system provides audio functionality through the SCSI disk class driver. The SCSI disk class driver provides an interface by which the audio commands can be issued to SCSI devices. The audio commands can be issued through the QIO function call. This functionality is available for devices, such as CD-ROMs which have audio capability.

The function code IO$_AUDIO allows the SCSI disk class driver to process the SCSI audio commands. An Audio Control Block (AUCB) must be defined for a specific SCSI audio command. The AUCB provides the SCSI disk class driver with command-specific arguments and control information. An application program must use the IO$_AUDIO function code and provide the AUCB in order for the SCSI driver to process the audio commands.

For more information, see

This section describes the SCSI disk class driver audio commands and the $QIO interface by which the operating system provides audio functionality to the SCSI disk.

Table 2.2, “SCSI Disk Class Driver Audio Commands” lists the SCSI audio commands supported by the SCSI disk class driver.

status=SYS$QIO ([efn] ,[chan] ,func [,iosb] [,astadr] [,astprm] [,p1] [,p2]
                [,p3] [,p4] [,p5] [,p6])

2.3.11.2. Defining an Audio Control Block (AUCB)

An application program that issues a call to the $QIO system service that specifies the IO$_AUDIO function code in the func argument must supply the address of an AUCB structure in the p1 argument and its size in the p2 argument.

An AUCB defines a specific SCSI audio command and provides the SCSI disk class driver with command-specific arguments and control information. Table 2.3, “Contents of AUCB” defines the fields that appear in an AUCB; these fields are shown in Figure 2.3, “Audio Control Block (AUCB)”. See SYS$EXAMPLES:CDROM_AUDIO.C for a code example that shows how an AUCB is defined in the C programming language.

Field	Use
Audio Function Code	Numeric or symbolic code representing the audio function desired by the application program. (See Table 2.2, “SCSI Disk Class Driver Audio Commands”.) The application program must provide a valid audio function code for each operation.
AUCB Version Number	Version of the AUCB and SCSI disk class driver audio interface. For the current version of the interface the value of this field should be 1. This field must never contain a zero.
Argument 1	This field is audio command-specific and contains the first argument of the function as follows:
	Audio Function Code?	Field Contents
	AUDIO_PLAY_AUDIO_MSF (5)	Starting Frames|(Sec shifted left 8 bits)|(Min shifted left 16 bits)
	AUDIO_PLAY_AUDIO_ TRACK (6)	Starting (Track shifted left 8 bits) |Index
	AUDIO_PLAY_AUDIO (4)	Starting logical block address.
	AUDIO_GET_STATUS (9)	0 if LBA format, 1 if MSF format. See the SCSI II specification for information about these formats.
	AUDIO_SET_VOLUME (11)	Longword representing the values to be used to determine the new output channel selection and volume settings for CD-ROM ports 0 through 3. Figure 2.4, “Output Channel Selection and Volume Settings for CD-ROM Ports as Used by the SET_VOLUME Function” shows the format of this longword. Note that many CD-ROM drives do not support ports 2 and 3.
	AUDIO_GET_VOLUME (12)	Longword to receive the current values determining output channel selection and volume settings for CD-ROM ports 0 through 3. Figure 2.4, “Output Channel Selection and Volume Settings for CD-ROM Ports as Used by the SET_VOLUME Function” shows the format of this longword. Note that many CD-ROM drives do not support ports 2 and 3.
	AUDIO_GET_TOC (10)	0 if LBA format, 1 if MSF format. See the SCSI II specification for information about these formats.
Argument 2	This field is audio command-specific and contains the second argument of the function as follows:
	Audio Function Code?	Field Contents
	AUDIO_PLAY_AUDIO_MSF (5)	Starting frames|(sec shifted left 8 bits)|(min shifted left 16 bits)
	AUDIO_PLAY_AUDIO_ TRACK (6)	Ending (track shifted left 8 bits)|index
	AUDIO_PLAY_AUDIO (4)	Transfer count in number of contiguous blocks to be played
	AUDIO_GET_TOC (10)	Starting track
Reserved	Must be zero.
Destination Buffer Address	Address of the application program's buffer from which the status from a GET_STATUS or GET_TOC function is returned.
Destination Buffer Count	Size, in bytes, of the destination buffer specified in the Destination Buffer Address field. For the GET_STATUS function, this field must contain the value 48 to receive complete status information. For the GET_TOC function, this field must contain the value 804 to receive full status. The SCSI disk class driver truncates the status data, if the destination buffer size is smaller than the size of the data.
Destination Buffer Transfer Count	The SCSI disk class driver returns to this field the actual number of bytes transferred to the buffer specified in the Destination Buffer Address field. Before accessing data returned by the GET_TOC or GET_STATUS commands, an application program must check the contents of this field to determine precisely how many bytes were returned by the CD-ROM. The application program initializes this field to zero.
Operating System Command Status	Completion status of the SCSI audio function. This value is also returned in the I/O status block of specified in the iosb argument to the $QIO system service call. See Table 2.4, “Status Codes Returned to the IOSB and AUCB by the SCSI Disk Class Driver” for a description of these status codes. The application program initializes this field to zero.
SCSI Command Status (optional)	SCSI status of the current operation. The SCSI disk class driver returns the SCSI status byte for the SCSI audio command described by this AUCB in the low byte of the low-order word of this field. It returns the sense key in the low byte of the high-order word. See the SCSI specification for information regarding SCSI status and SCSI sense keys. The application program initializes this field to zero.
Sense Data Buffer Address (optional)	Address of buffer to which the SCSI disk class driver returns sense data when errors occur during audio function execution. When this field is specified, in the event of a check condition on an Audio command, the SCSI disk class driver automatically issues a Request Sense command to retrieve the Sense Key/Sense Data from the target. The target returns this data to the buffer specified in this field before the failing $QIO audio function completes.
Sense Data Buffer Count (optional)	Size, in bytes, of the buffer specified in the Sense Data Buffer Address field. During request sense processing, the target device truncates the sense data to fit in this buffer.
Sense Data Buffer Transfer Count (optional)	Actual number of bytes of sense data returned to the application in the buffer specified in the Sense Data Buffer Address field. The application program initializes this field to zero.
Reserved	Must be zero.

The output channel selection and volume settings for CD-ROM ports as used by the SET_VOLUME function appear as shown in Figure 2.4, “Output Channel Selection and Volume Settings for CD-ROM Ports as Used by the SET_VOLUME Function”.

2.3.11.3. Error Handling in Applications Using SCSI Audio Functions

As indicated in Table 2.3, “Contents of AUCB”, the AUCB provides for three levels of error status reporting:

• Condition values, returned in the Operating System Command Status field of the AUCB, as well as in the I/O status block of specified in the iosb argument to the $QIO system service call. (See Table 2.4, “Status Codes Returned to the IOSB and AUCB by the SCSI Disk Class Driver” for a description of these status codes.)

  If this status is SS$_NORMAL, the function has completed without error. If the status is not SS$_NORMAL, the application program should check the SCSI Command Status field and the Sense Data buffer to fully determine the cause of the failure.

• SCSI command status, returned in the SCSI Command Status field of the AUCB. The SCSI disk class driver returns to this field SCSI status as well as the sense key in the event of a check condition SCSI status. The sense key can be used to determine the first level of error reporting supported by SCSI. See the SCSI specification for further information.

• Sense data, returned in the buffer specified in the Sense Data Buffer Address field of the AUCB. Sense data bytes are assigned as defined in the SCSI II specification. Sophisticated programmers can use the data in this to obtain detailed information about the error-causing condition.

If the CD-ROM device is currently software-enabled (that is, the volume has been mounted) and a unit attention is detected, then mount verification is initiated by the driver. However, if the CD-ROM is not software-enabled, the event returns to the application issuing the Audio $QIO function.

Code	Meaning
SS$_NORMAL	AUCB command completed successfully.
SS$_ABORT	Returned by the SCSI disk port driver. In general, you should retry commands that fail with this status.
SS$_BADPARM	The driver detected an illegal value or missing value in the AUCB.
SS$_CTRLERR	CD-ROM failed some part of its initialization sequence. When this status is returned, it is unlikely that the CD-ROM is usable.
SS$_DEVOFFLINE	Device returned a not-ready sense key or failed the TEST UNIT READY/START sequence.
SS$_DRVERR	CD-ROM failed to execute the command, either because the drive has failed or an illegal command was issued. Such a command could be a command that requested the drive to issue an audio command to a data track or attempted to perform a play operation on nonexistent tracks.
SS$_ILLIOFUNC	Illegal I/O function was specified in the func argument of the $QIO request.
SS$_IVADDR	Specified block number is larger than UCB$L_MAXBLOCK.
SS$_MEDOFL	Last command failed because the drive detected the removal and replacement of the CD carrier, or the unsuccessful completion of a Request Sense command after a check condition error. In general, you should not retry commands that fail with this status.
SS$_NOPRIV	Caller does not have sufficient privileges to execute this function. If the CD-ROM has not been mounted before an IO$_READVBLK function is issued, this status may be returned.
SS$_OPINCOMPL	Number of bytes requested is less than the number of bytes returned.
SS$_PARITY	Nonrecoverable media error (does not apply to audio functions).
SS$_RECOVERR	Recovered media error (does not apply to audio functions).
SS$_VOLINV	CD-ROM has not been mounted.
SS$_WRITLCK	Write operations not permitted on read-only devices.

The read function reads data into a specified buffer in the forward or reverse direction starting at the next block position.

The operating system provides the following read function codes:

If a read virtual block function is directed to a volume that is mounted foreign, it is converted to a read logical block function. If a read virtual block function is directed to a volume that is mounted structured, the volume is handled the same way as a file-structured device.

Two function-dependent arguments are used with these codes: P1 and P2. These arguments are described in Section 3.3, “Magnetic Tape Function Codes”.

If the read function code includes the reverse function modifier (IO$M_REVERSE), the drive reads the tape in the reverse direction instead of the forward direction. IO$M_REVERSE cannot be specified for the TUK50 and TQK50 devices.

The data check function modifier (IO$M_DATACHECK) can be used with all read functions. If this modifier is specified, a data check operation is performed after the read operation completes. (The drive performs a space reverse or space forward between the read and data check operations.) A data check operation is also performed if the volume that was read, or the volume on which the file resides (virtual read), has the characteristic “data check all reads.” Furthermore, a data check is performed after a virtual read if the file has the attribute “data check on read.” The TS04 and TU80 tape drives do not support the data check function.

For read physical block and read logical block functions, the drive returns the status SS$_NORMAL (not end-of-tape status) if either of the following conditions occurs and no other error condition exists:

The transferred byte count reflects the actual number of bytes read.

If the drive reads a tape mark during a logical or physical read operation in either the forward or reverse direction, any of the following conditions can return an end-of-file (EOF) status:

An EOF status is also returned if the drive attempts a read operation in the reverse direction when the tape is positioned at the beginning-of-tape (BOT) marker. All conditions that cause an EOF status result in a transferred byte count of zero.

If the drive attempts to read a block that is larger than the specified memory buffer during a logical or physical read operation, a data overrun status is returned. The buffer receives only the first part of the block. On a read in the reverse direction (on drives other than the TK50 and TZ30) the buffer receives only the latter part of the block. The transferred byte count is equal to the actual size of the block. Read reverse starts at the top of the buffer. Therefore, the start of the block is at P1 plus P2 minus the length read. The TUK50 and TZ30 cannot actually perform read reverse operations; they must be simulated by the driver. Therefore, the data returned are those that would have been returned had the block been read in the forward direction.

It is not possible to read a block that is less than 14 bytes in length. Records that contain less than 14 bytes are termed “noise blocks” and are completely ignored by the driver.

The write function writes data from a specified buffer to tape in the forward direction starting at the next block position.

The operating system provides the following write function codes:

If a write virtual block function is directed to a volume that is mounted foreign, the function is converted to a write logical block. If a write virtual block function is directed to a volume that is mounted structured, the volume is handled the same way as a file-structured device.

Two function-dependent arguments are used with these codes: P1 and P2. These arguments are described in Section 3.3, “Magnetic Tape Function Codes”“Magnetic Tape Function Codes”.

The IO$M_ERASE function modifier can be used with the IO$_WRITELBLK and IO$_WRITEPBLK function codes to erase a user-selected part of a tape. This modifier propagates an erase pattern of all zeros from the current tape position to 10 feet past the EOT position and then rewinds to the BOT marker.

The data check function modifier (IO$M_DATACHECK) can be used with all write functions. If this modifier is specified, a data check operation is performed after the write operation completes. (The drive performs a space reverse between the write and the data check operations.) The driver forces a data check operation when an error occurs during a write operation. This ensures that the data can be reread. A data check operation is also performed if the volume written, or the volume on which the file resides (virtual write), has the characteristic “data check all writes.” Furthermore, a data check is performed after a virtual write if the file has the attribute “data check on write.” The TS04 and TU80 tape drives do not support the data check function.

If the IO$M_NOWAIT function modifier is specified, write-back caching is enabled on a per-command basis. IO$M_NOWAIT is applicable only to TU81-Plus drives.

If the drive performs a write physical block or a write logical block operation, an EOT status is returned if either of the following conditions occurs and no other error condition exists:

The transferred byte count reflects the size of the block written. It is not possible to write a block less than 14 bytes in length. An attempt to do so results in the return of a bad parameter status for the QIO request.

The rewind function repositions the tape to the beginning-of-tape (BOT) marker.

If the IO$M_NOWAIT function modifier is specified, the I/O operation is completed when the rewind is initiated. Otherwise, I/O completion does not occur until the tape is positioned at the BOT marker.

If the IO$M_RETENSION function modifier is specified and the device supports the retention operation, the rewind function positions the tape to the physical-end-of-tape (EOT) marker and rewinds the tape to the BOT marker. If the tape does not support the IO$M_RETENSION modifier, a SS$_ILLIOFUNC error is returned.

IO$_REWIND has no function-dependent arguments.

The skip file function (IO$_SKIPFILE) skips past a specified number of tape marks in either a forward or reverse direction. A function-dependent argument (P1) is provided to specify the number of tape marks to be skipped, as shown in Figure 3.1, “IO$_SKIPFILE Argument”. If a positive file count is specified, the tape moves forward; if a negative file count is specified, the tape moves in reverse. (The actual number of files skipped is returned as an unsigned number in the I/O status block.)

Only tape marks (when the tape moves in either direction) and the BOT marker (when the tape moves in reverse) are counted during a skip file operation. The BOT marker terminates a skip file function in the reverse direction. The end-of-tape (EOT) marker does not terminate a skip file function in either the forward or reverse direction. A negative skip file function leaves the tape positioned just before a tape mark (at the end of a file) unless the BOT marker is encountered, whereas a positive skip file function leaves the tape positioned just past the tape mark.

A skip file function in the forward direction can also be terminated if two consecutive tape marks are encountered. Section 3.3.5.1, “Logical End-of-Volume (EOV) Detection” describes this feature.

The IO$M_ALLOWFAST modifier can be used with the IO$_SKIPFILE function to provide better performance on SCSI tape drives that support the SCSI space-by-file-marks command and the SCSI read position command.

When the IO$M_ALLOWFAST modifier is specified, a tape operation skips over consecutive tape marks that are not immediately before the end-of-data position on the medium. However, if two consecutive tape marks are detected immediately before the end-of-data position on the tape, the tape is positioned between these two tape marks and the SS$_ENDOFVOLUME status is returned.

The IO$M_ALLOWFAST modifier allows a SCSI tape subsystem to use the optimized IO$_SKIPFILE if it is capable. If a specific tape device does not adequately support the optimized IO$_SKIPFILE that uses the SCSI space-by-file-marks command, the tape subsystem uses the standard space-by-records algorithm.

The skip record function skips past a specified number of physical tape blocks in either a forward or reverse direction. A device- or function-dependent argument (P1) specifies the number of blocks to skip, as shown in Figure 3.2, “IO$_SKIPRECORD Argument”. If a positive block count is specified, the tape moves forward; if a negative block count is specified, the tape moves in reverse. The actual number of blocks skipped is returned as an unsigned number in the I/O status block. If a tape mark is detected, the count is the number of blocks skipped, plus 1 (forward tape motion) or minus 1 (reverse tape motion).

A skip record operation is terminated by the end-of-file (EOF) marker when the tape moves in either direction, by the BOT marker when the tape moves in reverse, and by the EOT marker when the tape moves forward.

A skip record function in the forward direction can also be terminated if the tape was originally positioned between two tape marks. Section 3.3.5.1, “Logical End-of-Volume (EOV) Detection” describes this feature.

The write end-of-file (EOF) function writes an extended interrecord gap (of approximately 3 inches for nonreturn-to-zero-inverted (NRZI) recording and 1.5 inches for phase-encoded (PE) recording) followed by a tape mark. No device- or function-dependent arguments are used with IO$_WRITEOF.

An end-of-tape (EOT) status is returned in the I/O status block if either of the following conditions is present and no other error conditions occur:

The rewind offline function rewinds and unloads the tape on the selected drive.

The I/O operation is completed as soon as the tape movement is initiated. The actual finish of the mechanical rewind or unload operation may occur long after the I/O operation completes.

If the IO$M_RETENSION function modifier is specified and the device supports the retention operation, the rewind offline function positions the tape to the physical end-of-tape (EOT) marker and rewinds the tape to the beginning-of-tape (BOT) marker. If the tape does not support the IO$M_RETENSION modifier, a SS$_ILLIOFUNC error is returned.

No device- or function-dependent arguments are used with IO$_REWINDOFF.

The unload function rewinds and unloads the tape on the selected drive. The unload function is functionally the same as the rewind offline function. If the IO$M_NOWAIT function modifier is specified, the I/O operation is completed as soon as the rewind operation is initiated. No device- or function-dependent arguments are used with IO$_UNLOAD.

The sense tape mode function senses the current device-dependent and extended device characteristics (see Tables Table 3.2, “Device-Dependent Information for Tape Devices” and Table 3.3, “Device-Dependent Information for Tape Devices”).

The operating system provides the following function codes:

Sense mode requires logical I/O privilege. Sense characteristics requires physical I/O privilege. For TMSCP and SCSI drives, the sense mode function returns magnetic tape information in a user-supplied buffer, which is specified by the following function-dependent arguments:

If P1 is not zero, the sense mode buffer returns the tape characteristics. (If P2=8, the second longword of the buffer contains the device-dependent characteristics. If P2=12, the second longword contains the device-dependent characteristics and the third longword contains the tape densities that the drive supports and the extended tape characteristics.) The extended characteristics are identical to the information returned by DVI$_DEVDEPEND2 (see Table 3.3, “Device-Dependent Information for Tape Devices”). Figure 3.3, “Sense Mode P1 Buffer” shows the contents of the P1 buffer.

Set mode operations affect the operation and characteristics of the associated magnetic tape device. The operating system defines two types of set mode functions: set mode and set characteristics.

Set mode requires logical I/O privilege. Set characteristics requires physical I/O privilege. The following function codes are provided:

These functions take the following device- or function-dependent arguments (other arguments are ignored):

Figure 3.4, “Set Mode Characteristics Buffer for IO$_SETMODE” shows the P1 characteristics buffer for IO$_SETMODE. Figure 3.5, “Set Mode Characteristics Buffer for IO$_SETCHAR” shows the same buffer for IO$_SETCHAR.

The first longword of the P1 buffer for the set characteristics function contains information on device class and type, and the buffer size. The device class for tapes is DC$_TAPE.

The $DCDEF macro defines the device type and class names. The buffer size is the default to be used for tape transfers (this default is normally 2048 bytes).

The second longword of the P1 buffer for both the set mode and set characteristics functions contains the tape characteristics. Table 3.5, “Set Mode and Set Characteristics Magnetic Tape Characteristics” lists the tape characteristics and their meanings. The $MTDEF macro defines the symbols listed. If P2=12, the third longword contains the extended tape characteristics for TMSCP and SCSI drives, which are listed in Table 3.6, “Extended Device Characteristics for Tape Devices”. The extended tape characteristics are defined by the $MT2DEF macro and are identical to the information returned by DVI$_DEVDEPEND2.

Application programs that change specific magnetic tape characteristics should perform the following steps, as shown in Section 3.5, “Magnetic Tape Drive Programming Examples”“Magnetic Tape Drive Programming Examples”:

Failure to follow this sequence results in clearing any previously set characteristic.

As of Version 7.2, OpenVMS Alpha permits the selection of any density and any compression supported by a tape drive. You can write to tapes using any density and any compression algorithm supported by the tape drive. Exchanging tapes among tape drives with different default settings for density or compression is much easier with this enhancement.

These enhancements allow IO$_SETMODE and IO$_SENSEMODE to function with most density values and a wider variety of drives. The system management utilities BACKUP and MOUNT take advantage of this added functionality. For more information about multiple tape density support with these utilities, see the VSI OpenVMS System Manager's Manual. For more information about enhancements in INITIALIZE, see the VSI OpenVMS DCL Dictionary.

The data security erase function erases all data from the current position of the volume to 10 feet beyond the EOT reflective strip, and then rewinds the tape to the BOT marker. It is a physical I/O function and requires the access privilege necessary to perform physical I/O functions. The following function code is provided:

If the function is issued when a tape is positioned at the BOT marker, all data on the tape is erased.

IO$_DSE takes no device- or function-dependent arguments.

Specifying the ATR$C_USERLABEL or ATR$C_ENDLBLAST attributes with IO$_MODIFY results in a bad attribute error. If any other attributes are specified, the IO$_MODIFY function is treated as a no-operation; that is, the function returns success, but no action is performed.

The pack acknowledge function sets the volume valid bit for all magnetic tape devices. It is a physical I/O function and requires the access privilege to perform physical I/O. The following function code is provided:

IO$_PACKACK must be the first function issued when a volume is placed in a magnetic tape drive. IO$_PACKACK is issued automatically when the DCL commands INITIALIZE or MOUNT are issued.

The available function clears the volume valid bit for all magnetic tape drives, that is, it reverses the function performed by the pack acknowledge function (see the Section 3.3.14, “Pack Acknowledge”). A rewind of the tape is performed (applicable to all tape drives). No unload function is issued to the drive. The following function code is provided:

This function takes no function-dependent arguments.

The flush function is used to ensure that all previously issued cached commands have fully completed. Normally, hosts use this function to establish or maintain synchronization with write-back cached commands issued to the specified tape unit. The I/O request does not complete until all cached data is written successfully to the media in the exact order that the user specified.

This function code takes no function-dependent arguments.

To create a mailbox and assign a channel and logical name to it, a process uses the Create Mailbox and Assign Channel ($CREMBX) system service. A logical name can optionally be associated with the mailbox. If a logical name is specified for the mailbox, the system enters the logical name in a logical name table and gives it an equivalence name of MBAn, where n is a unique unit number.

$CREMBX also establishes the characteristics of the mailbox. These characteristics include a protection mask, a permanence indicator, maximum message size, buffer quota, and direction in which I/O can be performed (read, write, or read/write). A mailbox is created as either temporary or permanent; both types require privilege to create. Applications and restrictions on how to use temporary and permanent mailboxes are described in the following sections. (See the VSI OpenVMS System Services Reference Manual for additional information on creating mailboxes.)

Other processes can assign additional channels to a mailbox using either the $CREMBX or the Assign I/O Channel ($ASSIGN) system service. The mailbox is identified by its logical name both when it is created and when it is assigned channels by cooperating processes. Channels assigned to the mailbox can specify the direction that I/O can be performed on the channel.

Figure 4.1, “Multiple Mailbox Channels” shows the use of $CREMBX and $ASSIGN.

If sufficient dynamic memory for the mailbox data structure is not available when a mailbox is created, a resource wait occurs if resource wait mode is enabled.

When a mailbox is created, a certain amount of space is specified for buffering messages that have been written to the mailbox but have not yet been read. The bufquo argument to the $CREMBX system service specifies this amount or quota. If that argument is omitted, its value defaults to the system parameter DEFMBXBUFQUO.

A message written to a mailbox, in the absence of an outstanding read request, is queued to the mailbox, and the size of the message (the QIO P2 argument) is subtracted from the available buffering space. After the message is read, it is added back to the available buffering space.

If a process attempts to write to a mailbox that is full or has insufficient buffering space and if the process has resource wait enabled (which is the default case), the process is placed in miscellaneous resource wait mode until sufficient space is available in the mailbox. If resource wait is not enabled, the I/O completes with the status return SS$_MBFULL in the I/O status block (IOSB).

Channels can be assigned to mailboxes as bidirectional (read/write), read only, or write only. This allows for greater synchronization between users of the mailbox. To specify a unidirectional channel to the mailbox, specify the flags argument for the $CREMBX or $ASSIGN system services.

The flags argument is a longword bit mask that enables you to specify that the channel assigned to the mailbox is a read-only or write-only channel. If the flags argument is not specified, the default channel behavior is read/write. A channel assigned to the mailbox as read only is considered a reader. A channel assigned to the mailbox as write only is considered a writer. A channel assigned to the mailbox as read/write is considered both a reader and a writer.

For the $ASSIGN system service, the $AGNDEF macro defines a symbolic name for each flag bit. These flags are as follows:

For the $CREMBX system service, the $CMBDEF macro defines a symbolic name for each flag bit. These flags are as follows:

See the VSI OpenVMS System Services Reference Manual for a syntax description of the $CREMBX and $ASSIGN system services.

The programming examples at the end of this section (Section 4.5, “Mailbox Driver Programming Examples”) show mailbox creation, interprocess communication, and synchronization.

As each process finishes using a mailbox, it deassigns the channel using the Deassign I/O Channel ($DASSGN) system service. Temporary mailboxes or permanent mailboxes that have been marked for deletion are actually deleted when no more channels are assigned to them.

If a mailbox channel is deassigned, any incomplete I/O requests on the mailbox channel for the process deassigning the channel are removed.

Permanent mailboxes that have not been marked for deletion must be explicitly deleted using the Delete Mailbox ($DELMBX) system service. An explicit deletion can occur at any time. As is true for temporary mailboxes, the mailbox is deleted when no processes have channels assigned to it.

When a temporary mailbox is deleted, its message buffer quota is returned to the process that created it. (No quota charge is made for permanent mailboxes.)

Mailboxes (both temporary and permanent) are protected by a code, or mask, that is similar to the code used in protecting volumes. As with volumes, four types of users (defined by UIC) can gain access to a mailbox: SYSTEM, OWNER, GROUP, and WORLD; however, only three types of access—logical I/O, read, and write—are meaningful to users of a mailbox. Therefore, when creating a mailbox, you can specify logical I/O, read, and write access to the mailbox separately for each type of user. Logical I/O access is required for any mailbox operation. The set protection function modifier provides additional control of mailbox access (see Section 4.3.6, “Set Protection”).

For additional information on temporary mailboxes and mailbox protection, see the description of the $CREMBX system service in the VSI OpenVMS System Services Reference Manual.

There is no standardized format for mailbox messages and none is imposed on users.

Read mailbox functions are used to obtain messages written to the mailbox. The operating system provides the following mailbox function codes:

IO$_READVBLK, IO$_READLBLK, and IO$_READPBLK all perform the same operation. To issue a read request, a process can specify any of the read function codes.

The following device- or function-dependent arguments are used with these codes:

The following function modifiers can be specified with a read request:

A READ IO$M_STREAM (without IO$M_NOW specified) on an empty mailbox waits until some data has been written to the mailbox. It terminates with:

If a $QIO READ STREAM is fulfilled by multiple $QIO WRITE requests, the sender PID returned in the IOSB of the $QIO READ STREAM reflects the first write request. A $QIO READ STREAM is charged BUFQUO for the request. This BUFQUO is released when the read request is met. A $QIO READ STREAM request that would cause BUFQUO to be exceeded for the mailbox when the mailbox has no writes pending returns an SS$_EXQUOTA error.

A $QIO READ STREAM issued to a mailbox that would cause BUFQUO to be exceeded because BUFQUO is occupied by write requests still executes. This happens because by allowing the mailbox to temporarily exceed BUFQUO, BUFQUO is freed. Similarly, a $QIO WRITE that is issued to a mailbox that would cause BUFQUO to be exceeded, because the BUFQUO is occupied by read stream requests, still executes.

Reads of 0 bytes are handled differently depending on which functional modifiers are specified. If IO$M_STREAM is specified, then the $QIO returns SS$_NORMAL with 0 bytes read. The contents of the mailbox remain exactly as they were before the $QIO was issued. A $QIO READ STREAM of 0 bytes does not remove a 0 byte record, nor does it remove an end-of-file marker. If IO$M_STREAM is not specified, then $QIO returns one of the following:

For a 0-byte nonstream read, a record is actually removed from the mailbox to meet the $QIO READ request. Note that the use of the word “immediately” does not imply that synchronization of the $QIO request should not be performed.

Figure 4.3, “Read Mailbox” shows the read mailbox functions. In this figure, Process A reads a mailbox message written by Process B. As the figure indicates, a mailbox read request requires a corresponding mailbox write request (except in the case of an error). The requests can be made in any sequence; the read request can either precede or follow the write request.

If Process A issues a read request before Process B issues a write request, one of two events can occur. If Process A did not specify the function modifier IO$M_NOW, Process A's request is queued before Process B issues the write request. When Process B's write request occurs, the data is transferred from Process B, through the system buffers, to Process A to complete the I/O operation.

However, if Process A did specify the IO$M_NOW function modifier, the read operation is completed immediately. That is, no data is transferred from Process B to Process A, and Process A's request is not queued. In this case, the I/O status returned to Process A is SS$_ENDOFFILE.

If Process B sends a message (with no function modifier; see Section 4.3.2, “Write”) before Process A issues a read request (with or without a function modifier), Process A finds a message in the mailbox. The data is transferred and the I/O operation is completed immediately, regardless of whether IO$M_NOW is specified on the read request.

Write mailbox functions are used to transfer data from a process to a mailbox. The operating system provides the following mailbox function codes:

IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK all perform the same operation. To issue a write request, a process can specify any of the write function codes.

These function codes take the following device- or function-dependent arguments:

The following function modifiers can be specified with a write request:

A $QIO WRITE of 0 bytes causes a 0-byte long message to be placed in the mailbox. When this data is read by a $QIO READ without IO$M_STREAM specified, the $QIO READ returns an SS$_NORMAL status and 0 bytes. When this data is read by a $QIO READ STREAM in an attempt to read P2 bytes (P2 being greater than 0), the data is ignored. However, a $QIO READ STREAM of 0 bytes has no effect on the mailbox. A $QIO WRITE READERCHECK of 0 bytes, when no read channel is assigned to the mailbox, returns an SS$_NOREADER error and the 0-byte record is not placed in the mailbox. A message that is 0 bytes long is charged 1 byte of mailbox BUFQUO.

Figure 4.4, “Write Mailbox” shows the write mailbox function. In this figure, Process A writes a message to be read by Process B. As in the read request example, a mailbox write request requires a corresponding mailbox read request (unless an error occurs) and the requests can be made in any sequence.

If Process A issues a write request before Process B issues a read request, one of two events can occur. If Process A did not specify the function modifier IO$M_NOW, Process A's write request is queued before Process B issues a read request. When this request occurs, the data is transferred from Process A to Process B to complete the I/O operation.

However, if Process A did specify the IO$M_NOW function modifier, the write operation is completed immediately. The data is available to Process B and is transferred when Process B issues a read request.

If Process B issues a read request (with no function modifier) before Process A issues a write request (with or without the function modifier), Process A finds a request in the mailbox. The data is transferred and the I/O operation is completed immediately.

Write end-of-file message functions are used to insert a special message in the mailbox. The process that reads the end-of-file message is returned the status code SS$_ENDOFFILE in the I/O status block. The message count of the Get Mailbox Information function reflects this end-of-file message; however, the mailbox byte count of this function does not include end-of-file markers. An end-of-file message is charged 1 byte of mailbox BUFQUO.

This function takes no arguments. The operating system provides the following function code:

The following function modifiers can be specified with a write end-of-file request:

Set attention AST functions specify that an asynchronous system trap (AST) be delivered to the requesting process in the following cases:

If a message exists in the mailbox when a request to enable a write attention AST is issued, the AST routine is activated immediately. If no message exists, the AST is delivered when a write request message arrives; therefore, the requesting process need not repeatedly check the mailbox status. You must have both logical I/O and read access to the mailbox prior to performing a set attention AST function.

The operating system provides the following function codes:

These function codes take the following device- or function-dependent arguments:

These functions are enabled only once; they must be explicitly reenabled after the AST has been delivered if you desire repeat notification. All types of enable functions, and more than one of each type, can be set at the same time. The number of enable functions is limited only by the AST quota for the process.

Figure 4.5, “Write Attention AST (Read Unsolicited Data)” shows the write attention AST function. In this figure, an AST is set to notify Process A when Process B sends an unsolicited message.

Process A uses the IO$_SETMODE!IO$M_WRTATTN function to request an AST. When Process B sends a message to the mailbox, the AST is delivered to Process A. Process A responds to the AST by issuing a read request to the mailbox. The data is then transferred to complete the I/O operation.

If several requesting processes have set ASTs for unsolicited messages at the same mailbox, all ASTs are delivered when the first unsolicited message is placed in the mailbox; however, only the first process to respond to the AST with a read request receives the data. Therefore, when the next process to respond to an AST issues a read request to the mailbox, it might find the mailbox empty. If this request does not include the function modifier IO$M_NOW, it is queued before the next message arrives in the mailbox.

Figure 4.6, “Read Attention AST” shows the read attention AST function. In this figure, an AST is set to notify Process A when Process B issues a read request for which no message is available.

Process A uses the IO$_SETMODE!IO$M_READATTN function to specify an AST. When Process B issues a read request to the mailbox, the AST is delivered to Process A. Process A responds to the AST by sending a message to the mailbox. The data is then transferred to complete the I/O operation.

If several requesting processes set ASTs for read requests for the same mailbox, all ASTs are delivered when the first read request is placed in the mailbox. Only the first process to respond with a write request is able to transfer data to Process B.

The wait for writer/reader mailbox driver function waits until a channel is assigned to the mailbox with the requested access direction. This function returns immediately if a channel is already assigned to the mailbox with the proper access direction. This function always returns immediately if issued on a bidirectional mailbox channel. Any channel assigned bidirectionally to the mailbox satisfies both types of wait requests.

The wait function requires the same synchronization techniques as all other $QIO functions. $QIO Wait should not be issued without any synchronization of its completion. If no synchronization is performed, the program behaves as if no $QIO Wait function had been issued (except for the small delay caused by issuing the $QIO Wait).

The following function codes and modifiers are provided:

These function codes require no function-dependent arguments.

These functions are enabled only once. Once the $QIO operation completes, these functions must be explicitly reenabled.

The set protection functions allow the user to set volume protection on a mailbox (see Section 4.1.3, “Mailbox Protection”). The requester must either be the owner of the mailbox or have BYPASS privilege. The OpenVMS operating system provides the following function code:

This function code takes the following device- or function-dependent argument:

The protection mask specified by P2 is a 16-bit mask with 4 bits for each class of owner: SYSTEM, OWNER, GROUP, and WORLD, as shown in Figure 4.7, “Protection Mask”.

Only logical I/O, read, and write functions have meaning for mailboxes. A clear (0) bit implies that access is allowed. If P2 is 0 or unspecified, the mask is set to allow all read, write, and logical operations.

The I/O status block for the set protection function (see Figure 4.10, “IOSB Contents— Set Protection Function” ) returns SS$_NORMAL in the first word if the request was successful. If the request was not successful, the $QIO system service returns SS$_NOPRIV and both longwords of the I/O status block are returned as zeros.

The get mailbox information function allows the user to find out the number of unread messages and bytes in the mailbox. The following function code is provided:

The following function codes and modifiers are provided:

These function codes require no function-dependent arguments.

The I/O status block for the get information function (see Figure 4.11, “IOSB Contents — Get Mailbox Information Function”).

The terminal driver defines many terminal characteristics and read function modifiers, which provide a wide range of options to an application program. These options allow multiple levels of control over the terminal driver's input process, ranging from the default of command-line editing that provides a highly flexible user interface, to the PASTHRU mode, which inhibits input process interpretation of data.

ESC <int>...<int><fin>(7-bit environment)

CSI <int>...<int><fin>(8-bit environment)

ESC <;> <20-2F>...<30-7E>
ESC <20-2F>...<30-7E>
ESC <O><20-2F>...<40-7E>

ESC [ <par>...<par><int>...<int><fin>(7-bit environment)

CSI  <par>...<par><int>...<int><fin>(8-bit environment)