Document revision date: 19 July 1999

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 OpenVMS System Services Reference Manual.

func

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

p1

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

p2

Size of the 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-2 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-2 Contents of AUCB

Field	Use
Audio Function Code	Numeric or symbolic code representing the audio function desired by the application program. (See Table 2-1.) 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 Code1 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 Code1 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-3 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.

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

As indicated in Table 2-2, 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-3 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 will be initiated by the driver. However, if the CD-ROM is not software-enabled, the event will simply be returned to the application issuing the Audio $QIO function.

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

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.2.14.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.2.14.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. Because VAX byte ordering is little-endian, you must switch the LBA data bytes to get a logical block address that is valid on a VAX computer. 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.

The file SYS$EXAMPLES:CDROM_AUDIO.C contains an example of an application program that performs the following tasks:

• Defines standard symbolic names for the audio function codes representing SCSI audio commands.
• Defines representative AUCBs for each audio function code supported by the SCSI disk class driver.
• Issues a series of $QIO system service requests, each specifying the IO$_AUDIO function, that exercise the SCSI disk class driver to test its support for CD-ROM drives with audio capabilities.
• Converts LBA data returned by a GET_STATUS command in big-endian byte-ordering form to VAX little-ending byte-ordering form.

You can obtain information on all disk device characteristics by using the Get Device/Volume Information ($GETDVI) system service (see the OpenVMS System Services Reference Manual).

$GETDVI returns disk characteristics when you specify the item codes DVI$_DEVCHAR and DVI$_DEVCHAR2. Table 2-4 lists the possible characteristics for disk devices.

Table 2-4 Disk Device Characteristics

Characteristic1	Meaning
Dynamic Bits (Conditionally Set)
DEV$M_AVL	Device is on line and available.
DEV$M_CDP 2,3	Dual-path device with two unit control blocks (UCBs).
DEV$M_CLU 2	Device is available clusterwide.
DEV$M_2P 2	Device is dual-pathed.
DEV$M_FOR	Device is foreign.
DEV$M_MNT	Volume is mounted.
DEV$M_RCK	Perform data check on all reads.
DEV$M_WCK	Perform data check on all writes.
DEV$M_MSCP 2	Device is accessed using the mass storage control protocol.
DEV$M_RCT	Disk contains replacement and caching table.
DEV$M_SRV 2	For a cluster, device is served by the MSCP server.
Static Bits (Always Set)
DEV$M_FOD	Device is file-oriented.
DEV$M_IDV	Device is capable of input.
DEV$M_ODV	Device is capable of output.
DEV$M_RND	Device is capable of random access.
DEV$M_SHR	Device is shareable.

DVI$_DEVBUFSIZ returns the buffer size. The buffer size is the default to be used for disk transfers (this default is normally 512 bytes). DVI$_DEVTYPE and DVI$_DEVCLASS return the device type and class names, which are defined by the $DCDEF macro. The disk model determines the device type. For example, the device type for the RA81 is DT$_RA81. (Foreign device types take the form DT$_FD1 through DT$_FD8.) The device class for disks is DC$_DISK.

DVI$_CYLINDERS returns the number of cylinders per volume (that is, per disk), DVI$_TRACKS returns the number of tracks per cylinder, and DVI$_SECTORS returns the number of sectors per track. Values are returned as 4-byte decimal numbers.

DVI$_MAXBLOCK returns the maximum number of blocks (1 block = 512 bytes) that can be contained on the volume (that is, on the disk). Values are returned as 4-byte decimal numbers. This information can be used, for example, to determine the density of an RX02 diskette (single density = 494 blocks, double density = 988 blocks).

2.4 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 disk class driver (DUDRIVER) do not accept physical QIO data transfers or seek operations.

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.

Non-DSA disk devices can read or write up to 65,535 bytes in a single request. DSA devices connected to an HSC50 can transfer up to 4 billion bytes in a single request. In all cases, the maximum size of the transfer is limited by the number of pages that can be faulted into the process's working set, and then locked into physical memory. (The disk driver is responsible for any memory management functions of this type.) The size of the transfer does not affect the applicable quotas (direct I/O count, buffered I/O count, and asynchronous system trap (AST) count limit). These quotas refer to the number of outstanding I/O operations of each type, not the size of the I/O operation being performed.

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-5 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-5 Disk I/O Functions

Function Code	Arguments	Type1	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$_READLBLK 6	P1,P2,P3	L	IO$M_DATACHECK 2 IO$M_INHRETRY	Read logical block.
IO$_READPBLK 6	P1,P2,P3	P	IO$M_DATACHECK 2 IO$M_INHRETRY IO$M_INHSEEK 3	Read physical block. 5
IO$_READVBLK 6	P1,P2,P3	V	IO$M_DATACHECK 2 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 6	P1,P2,P3	P		Verify data written to disk by a previous write QIO. 2
IO$_WRITELBLK 6	P1,P2,P3	L	IO$M_DATACHECK 2 IO$M_ERASE IO$M_INHRETRY	Write logical block.
IO$_WRITEPBLK 6	P1,P2,P3	P	IO$M_DATACHECK 2 IO$M_ERASE IO$M_INHRETRY IO$M_INHSEEK 3 IO$M_DELDATA 4	Write physical block. 5
IO$_WRITEVBLK 6	P1,P2,P3	V	IO$M_DATACHECK 2 IO$M_ERASE IO$M_INHRETRY	Write virtual block.

	privacy and legal statement
6136PRO_007.HTML