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.
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.
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:
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.
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 “Defining an Audio Control Block (AUCB)”).
p2
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:
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:
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.
