2.3 Disk Function Codes

Disk drivers can perform logical, virtual, and physical I/O functions. Foreign-mounted devices do not require privilege to perform logical and virtual I/O requests.

Logical and physical I/O functions allow access to volume storage and require only that the issuing process have access to the volume; however, DSA disks and the Shadow disk class driver (DUDRIVER) do not accept physical QIO data transfers or seek operations.




	NOTE: The results of logical and physical I/O operations are unpredictable if an ancillary control process (ACP) or extended QIO processing (XQP) is present.

Virtual I/O functions require an ACP for Files-11 On-Disk Structure Level 1 files or an XQP for Files-11 On-Disk Structure Level 2 files. Virtual I/O functions must be executed in a prescribed order. First, you create and access a file, then you write information to that file, and lastly you deaccess the file. Subsequently, when you access the file, you read the information and then deaccess the file. Delete the file when the information is no longer useful.

The volume to which a logical or virtual function is directed must be mounted for the function actually to be executed. If it is not mounted, either a “device not mounted” or “invalid volume” status is returned in the I/O status block.

Table 2-1 lists the logical, virtual, and physical disk I/O functions and their function codes. Chapter 1 describes the QIO level interface to the disk device ACP.

Table 2-1 Disk I/O Functions

Function Code	Arguments	Type^[1]	Function Modifiers	Function
IO$_ACCESS	P1, [P2],[P3], [P4], [P5]	V	IO$M_CREATE IO$M_ACCESS	Search a directory for a specified file and access the file if found.
IO$_ACPCONTROL	P1,[P2],[P3], [P4],[P5]	V	IO$M_DMOUNT	Perform miscellaneous control functions.
IO$_AVAILABLE		P		Clear volume valid; make DSA units available.
IO$_CREATE	P1,[P2],[P3], [P4],[P5]	V	IO$M_CREATE IO$M_ACCESS IO$M_DELETE	Create a directory entry or a file.
IO$_DEACCESS	P1,[P2],[P3], [P4],[P5]	V		Deaccess a file and, if specified, write final attributes in the file header.
IO$_DELETE	P1,[P2],[P3],[ P4],[P5]	V	IO$M_DELETE	Remove a directory entry or file header, or both.
IO$_FORMAT	P1	P		Set density (RX02 only).
IO$_MODIFY	P1,[P2],[P3], [P4],[P5]	V		Modify the file attributes or allocation, or both.
IO$_PACKACK		P		Update UCB fields if RX02; initialize volume valid on other devices. Bring DSA units on line.
IO$_READLBL^[2]	P1,P2,P3	L	IO$M_DATACHECK^[3] IO$M_INHRETRY	Read logical block.
IO$_READPBLK^[2]	P1,P2,P3	P	IO$M_DATACHECK^[3] IO$M_INHRETRY IO$M_INHSEEK^[4]	Read physical block.^[5]
IO$_READVBLK^[2]	P1,P2,P3	V	IO$M_DATACHECK^[3] IO$M_INHRETRY	Read virtual block.
IO$_SEARCH	P1	P		Search for specified block or sector (only for TU58).
IO$_SEEK	P1	P		Seek to specified cylinder.^[5]
IO$_SENSECHAR		P		Sense the device-dependent characteristics and return them in the I/O status block.
IO$_SENSEMODE		L		Sense the device-dependent characteristics and return them in the I/O status block.
IO$_SETPRFPATH	P1	P	IO$M_FORCEPTH	Specifies a preferred path for DSA disks.
IO$_UNLOAD		P		Clear volume valid; make DSA units available and spin down the volume.
IO$_WRITECHECK ^[2]	P1,P2,P3	P		Verify data written to disk by a previous write QIO.^[3]
IO$_WRITELBLK^[2]	P1,P2,P3	L	IO$M_DATACHECK^[3] IO$M_ERASE IO$M_INHRETRY	Write logical block.
IO$_WRITEPBLK^[2]	P1,P2,P3	P	IO$M_DATACHECK^[3] IO$M_ERASE IO$M_INHRETRY IO$M_INHSEEK ^[4] IO$M_DELDATA ^[6]	Write physical block.^[5]
IO$_WRITEVBLK^[2]	P1,P2,P3	V	IO$M_DATACHECK^[3] IO$M_ERASE IO$M_INHRETRY	Write virtual block.
^[1]V = virtual; L = logical; P = physical. ^[2]On OpenVMS Alpha, P1 supports a 64-bit address. ^[3]Not for RX01 and RX02 disks. ^[4]Not for TU58, TX01, RX02, RB02 and RL02 drives. ^[5]Not for DSA and SCSI disks. ^[6]RX02 only.

The function-dependent arguments for IO$_CREATE, IO$_ACCESS, IO$_DEACCESS, IO$_MODIFY, and IO$_DELETE are as follows:

P1—The address of the file information block (FIB) descriptor.
P2—The address of the file name string descriptor (optional). If specified, the name is entered in the directory specified by the FIB.
P3—The address of the word that is to receive the length of the resulting file name string (optional).
P4—The address of a descriptor for a buffer that is to receive the resulting file name string (optional).
P5—The address of a list of attribute descriptors (optional). If specified, the indicated attributes are read (IO$_ACCESS) or written (IO$_CREATE, IO$_DEACCESS, and IO$_MODIFY).

See Chapter 1 for more information on these functions.

The function-dependent arguments for IO$_READVBLK, IO$_READLBLK, IO$_WRITEVBLK, and IO$_WRITELBLK are as follows:

P1—The starting virtual address of the buffer that is to receive the data from a read operation; or, in the case of a write operation, the virtual address of the buffer that is to be written on the disk. On OpenVMS Alpha, P1 can be a 64-bit address.
P2—The number of bytes that are to be read from the disk, or written from memory to the disk. An even number must be specified if the controller is an RK611, RL11, RX211, or UDA50.
P3—The starting virtual/logical disk address of the data to be transferred in a read operation; or, in a write operation, the disk address of the area that is to receive the data.
In a virtual read or write operation, the address is expressed as a block number within the file, that is, block 1 of the file is virtual block 1. (Virtual block numbers are converted to logical block numbers using mapping windows that are set up by the file system ACP process.)
In a logical read or write operation, the address is expressed as a block number relative to the start of the disk. For example, the first sector on the disk contains block 0 (or at least the beginning of block 0).

The function-dependent arguments for IO$_WRITEVBLK, IO$_WRITELBLK, and IO$_WRITEPBLK functions that include the IO$M_ERASE function modifier are as follows:

P1——The starting virtual address of the buffer that contains a 4-byte, user-specified erase pattern. If the P1 address is 0, a longword of 0 is used for the erase pattern. If the P1 address is nonzero, the contents of the 4 bytes starting at that address is used as the erase pattern. HP recommends that the user specify a P1 address of 0 to lower system overhead. On OpenVMS Alpha, P1 can be a 64-bit address.




	NOTE: DSA disk controllers provide controlled, assisted erasing for the IO$M_ERASE modifier (with virtual and logical write functions) only when the erase pattern is all zeros. If a nonzero erase pattern is used, there is a significant performance degradation with these disks. DSA disks do not accept physical QIO transfers.

P2—The number of bytes of erase pattern to write to the disk. The number specified is rounded up to the next highest block boundary (512 bytes).
P3—The starting virtual, logical, or physical disk address of the data to be erased.

The function-dependent arguments for IO$_WRITECHECK, IO$_READPBLK, and IO$_WRITEPBLK are as follows:

P1—The starting virtual address of the buffer that is to receive the data in a read operation; or, in a write operation, the starting virtual address of the buffer that is to be written on the disk. Passed by reference. On OpenVMS Alpha and OpenVMS Integrity server, P1 can be a 64-bit address.
P2—The number of bytes that are to be read from the disk, or written from memory to the disk. Passed by value. An even number must be specified if the controller is an RK611, RL11, or UDA50.
P3—The starting physical disk address of the data to be read in a read operation; or, in a write operation, the starting physical address of the disk area that is to receive the data. Passed by value. The address is expressed as sector, track, and cylinder in the format shown in Figure 2-1. (On the RX01 and RX02, the high word specifies the track number rather than the cylinder number.) Check the UCB of a currently mounted device to determine the maximum physical address value for that type of device.
NOTE: On the RB80 and RM80, do not address cylinders 560 and 561. These two cylinders are used for diagnostic testing only.

The function-dependent argument for IO$_SEARCH is as follows:

P1—The physical disk address where the tape is positioned. The address is expressed as sector, track, and cylinder in the format shown in Figure 2-1.

Figure 2-1 Starting Physical Address

The function-dependent argument for IO$_SEEK is as follows:

P1—The physical cylinder number where the disk heads are positioned. The address is expressed in the format shown in Figure 2-2.

Figure 2-2 Physical Cylinder Number Format

The function-dependent argument for IO$_FORMAT is as follows:

P1—The density at which an RX02 diskette is reformatted (see “Set Density”).

2.3.1 Read

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:

IO$_READVBLK—Read virtual block
IO$_READLBLK—Read logical block
IO$_READPBLK—Read physical block

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

SS$_CTRLERR	SS$_DRVERR	SS$_MEDOFL
SS$_NONEXDRV	SS$_NORMAL

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.

2.3.2 Write

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:

IO$_WRITEVBLK—Write virtual block
IO$_WRITELBLK—Write logical block
IO$_WRITEPBLK—Write physical block

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 “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. “Disk Function Codes” describes the write function arguments to be used with IO$M_ERASE.

2.3.3 Sense Mode

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). The operating system provides the following function codes:

IO$_SENSEMODE—Sense characteristics
IO$_SENSECHAR—Sense characteristics

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.

2.3.4 Set Density

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

IO$_FORMAT takes the following function-dependent argument:

P1—The density at which the diskette is reformatted:
- 0 = single density (default)
- 1 = single density
- 2 = double density

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.

2.3.5 Search

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:

IO$_SEARCH

This function code takes the following function-dependent argument:

P1—Specifies the block where the read/write head is positioned. The low byte contains the sector number in the range 0 to 127; the high byte contains the track number in the range 0 to 3.

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

2.3.6 Pack Acknowledge

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:

IO$_PACKACK

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.

2.3.7 Unload

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 “Pack Acknowledge”). The following function code is provided:

IO$_UNLOAD

This function takes no function-dependent arguments.

2.3.8 Available

The available function clears the volume valid bit for all disk drives; that is, it reverses the function performed by pack acknowledge (see “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:

IO$_AVAILABLE

This function takes no function-dependent arguments.

2.3.9 Seek

The seek function directs the read/write heads to move to the cylinder specified in the P1 argument (see “Disk Function Codes” and Figure 2-2).

2.3.10 Write Check

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

IO$_WRITECHECK

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

2.3.11 Audio Extensions

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 lists the SCSI audio commands supported by the SCSI disk class driver.

Table 2-2 SCSI Disk Class Driver Audio Commands

Command	Audio Function Code^[1]	Description
Play Audio MSF	AUDIO_PLAY_AUDIO_MSF (5)	Requests the CD-ROM to begin an audio playback operation. The two required command arguments specify absolute starting and ending addresses of the playback in terms of minutes, seconds, and frame (MSF).
Play Audio Track	AUDIO_PLAY_AUDIO_TRACK (6)	Requests the CD-ROM to begin an audio playback operation. The two required command arguments specify the starting and ending tracks of the playback in terms of track number and index.
Play Audio	AUDIO_PLAY_AUDIO (4)	Requests the CD-ROM to begin an audio playback operation. The two required command arguments specify the starting logical block address (LBA) and the transfer count, in blocks, of the playback.
Pause	AUDIO_PAUSE (0)	Requests the CD-ROM to suspend any active audio operations. In response, the CD-ROM enters the hold-track state, muting the audio output after playing the current block.
Resume	AUDIO_RESUME (1)	Requests the CD-ROM to resume any active audio operations. In response, the CD-ROM exits the hold-track state and resumes playback at the block following the last block played.
Get Status	AUDIO_GET_STATUS (9)	Requests from the CD-ROM the status of the currently active playback operation, as well as the state of the current block. The Get Status command corresponds to the SCSI II Read Sub-channel command (READ SUBQ).
Set Volume	AUDIO_SET_VOLUME (11)	Requests the CD-ROM to adjust the output channel selection and volume settings for ports 0 through 3. The Set Volume command corresponds to the SCSI II Mode Select command for the CD-ROM Audio Control Parameters page.
Get Volume	AUDIO_GET_VOLUME (12)	Requests from the CD-ROM the output channel selection and volume settings for ports 0 through 3. The Get Volume command corresponds to the SCSI II Mode Sense command for the CD-ROM Audio Control Parameters page.
Prevent Removal	AUDIO_PREVENT_REMOVAL (2)	Prevents the removal of the CD caddy from the CD-ROM drive.
Allow Removal	AUDIO_ALLOW_REMOVAL (3)	Allows the removal of the CD caddy from the CD-ROM drive.
Get TOC	AUDIO_GET_TOC (10)	Requests from the CD-ROM a list of each track on the disk, including information about the audio or data contents of each track. Applications that require a detailed knowledge of the organization of a CD-ROM can use this function to obtain that information. The Get TOC command corresponds to the SCSI II Read TOC command.
^[1]Symbolic values for the function codes of SCSI audio commands are defined in SYS$EXAMPLES:CDVERIFY.C. Numeric values appear within parentheses in this table column.

2.3.11.1 $QIO Interface to Audio Functionality of the SCSI Disk Class Driver

To employ the audio functions of the RRD42 CD-ROM reader, the application program issues a call to the $QIO system service using the following format:

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

Arguments

[efn]

[chan]

[iosb]

[astadr]

[astprm]

These arguments apply to the $QIO system service completion, not to device interrupt actions. For an explanation of these arguments, see the description of the $QIO system service in the HP OpenVMS System Services Reference Manual.

func

The IO$_AUDIO function code allows the SCSI disk class driver to process SCSI audio commands.

Address of an audio control block (AUCB). The $QIO system service passes a SCSI audio command and command-specific control information to the SCSI disk class driver in the AUCB structure (see “Defining an Audio Control Block (AUCB)”).

Size of the AUCB.

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 defines the fields that appear in an AUCB; these fields are shown in Figure 2-3. See SYS$EXAMPLES:CDROM_AUDIO.C for a code example that shows how an AUCB is defined in the C programming language.

Figure 2-3 Audio Control Block (AUCB)

Table 2-3 Contents of AUCB

Field	Use
Audio Function Code	Numeric or symbolic code representing the audio function desired by the application program. (See Table 2-2.) 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^[1]	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 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 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^[1]	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 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.
^[1]For any function code not listed in this table, this field contains a 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.

2.3.11.3 Error Handling in Applications Using SCSI Audio Functions

As indicated in Table 2-3, 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 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.

Figure 2-4 Output Channel Selection and Volume Settings for CD-ROM Ports as Used by the SET_VOLUME Function

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.

Table 2-4 Status Codes Returned to the IOSB and AUCB by the SCSI Disk Class Driver

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.

2.3.11.4 Using CD-ROM to Store Both Data and Audio Information

To make effective use of mixed data and audio CDs, an application program requires detailed knowledge of the particular CD being played. The application program must know which tracks include data and which tracks include audio so it can use commands appropriate to the different track types. Issuing an audio command on a data track results in the command failing with a status of SS$_DRVERR.

By default, the SCSI disk class driver transfers all requests issued to a CD-ROM in blocks of 512 bytes. This byte amount is referred to as the default block size. Before attempting to issue READ operations to the CD-ROM, you must ensure that the CD-ROM has been mounted as foreign or as a Files-11 volume. The application program can then determine, by issuing a GET_TOC function, which tracks (and, therefore, which logical blocks) contain data and which contain audio information.

2.3.11.5 Programming Audio Applications

The following list contains information useful in avoiding problems when writing code using the SCSI audio interfaces:

If you do not know the type of file system on the CD-ROM, you should mount the CD-ROM as foreign and issue a $QIO request with the logical block I/O read function (IO$_READLBLK) to read individual data blocks. The default block size for all CD-ROMs is 512 bytes.
When using the GET_TOC command to obtain CD-ROM address information in LBA format, be advised that the byte ordering of the returned data is in big-endian form. SYS$EXAMPLES:CDROM_AUDIO.C contains an example of how to perform this exchange.
Before attempting to issue a $QIO request with the virtual block I/O read function (IO$_READVBLK) to the CD-ROM, ensure that the CD-ROM has been mounted. Typically, you have to foreign mount non-Files-11 disks. If an IO$_READVBLK $QIO request is issued to an unmounted CD, the request fails with a status of SS$_NOPRIV.