HP OpenVMS Systems Documentation
Content starts here

OpenVMS I/O User's Reference Manual

Previous Contents Index

2.2.12 VAXstation 2000 and MicroVAX 2000 Disk Driver

The VAXstation 2000 and MicroVAX 2000 disk driver supports some DSAdisk operation. In particular, the driver supports block revectoringand bad block replacement. This provides the system with a logicallyperfect disk medium.

Like other DSA disks, if a serious error occurs during a replacementoperation, the disk is write-locked to prevent further changes. This isdone to preserve data integrity and minimize damage that could becaused by failing hardware. Unlike other DSA disks, there is no visibleindication on the drive itself that the disk is write-locked. However,the following indicators help you determine that the disk has becomewrite-protected:

  • ERRFMT messages show that the disk is write-locked.
  • The disk enters mount verification and hangs.
  • DCL command SHOW DEVICE output shows that the disk is write-locked.
  • Error messages occur from programs and utilities attempting to write to the disk.

If the disk becomes write-locked, you should use the followingprocedure:

  1. Shut down the system.
  2. Use standalone BACKUP to create a full backup of the disk.
  3. Format the disk with the disk formatter.
  4. Restore the disk from the backup using standalone BACKUP. Note that any files with sectors flagged with a forced error may be corrupted and may need to be restored from a previous backup.

If errors occurring during replacement operations persist, call CompaqCustomer Services.

2.2.13 SCSI Disk Class Driver

The VAXstation 3100, 3520, and 3540 contain a SCSI bus that providesaccess to as many as seven SCSI disks. The SCSI disk class drivercontrols SCSI disks on all of the above systems. Although, SCSI disksdo not conform to DSA, they do support the following error recoveryfeatures:

  • Static and dynamic bad block replacement (BBR)
  • Error correction code (ECC)
  • Reexecution of read or write operations within the SCSI drive
  • Reexecution of read or write operations by the SCSI disk class driver

All SCSI disks supplied by Compaq implement the REASSIGN BLOCKScommand, which relocates data for a specific logical block to adifferent physical location on the disk. The SCSI disk class driverreassigns the block in the following instances: (1) when the retrythreshold is exceeded during an attempt to read or write a block ofdata on the disk or (2) when an irrecoverable error occurs during awrite operation.

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

2.2.14 Audio Extensions to the SCSI Disk Class Driver

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

Table 2-1 lists the SCSI audio commands supported by the SCSI diskclass driver.

Table 2-1 SCSI Disk Class Driver Audio Commands
Command Audio Function Code1 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.
1Symbolic values for the function codes of SCSI audiocommands are defined in SYS$EXAMPLES:CDVERIFY.C. Numeric values appearwithin parentheses in this table column.

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

To employ the audio functions of the RRD42 CD-ROM reader, theapplication program issues a call to the $QIO system service using thefollowing 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 todevice interrupt actions. For an explanation of these arguments, referto 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 toprocess SCSI audio commands.

p1

Address of an audio control block (AUCB). The $QIO system servicepasses a SCSI audio command and command-specific control information tothe SCSI disk class driver in the AUCB structure (see Section 2.2.14.2).

p2

Size of the AUCB.

2.2.14.2 Defining an Audio Control Block (AUCB)

An application program that issues a call to the $QIO system servicethat specifies the IO$_AUDIO function code in the funcargument must supply the address of an AUCB structure in thep1 argument and its size in the p2argument.

An AUCB defines a specific SCSI audio command and provides the SCSIdisk class driver with command-specific arguments and controlinformation. Table 2-2 defines the fields that appear in an AUCB;these fields are shown in Figure 2-3. See SYS$EXAMPLES:CDROM_AUDIO.Cfor a code example that shows how an AUCB is defined in the Cprogramming 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. Refer to 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. Refer to 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. Refer to 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.
1For any function code not listed in this table, this fieldcontains a zero.

The output channel selection and volume settings for CD-ROM ports asused by the SET_VOLUME function appear as shown in Figure 2-4.

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

2.2.14.3 Error Handling in Applications Using SCSI Audio Functions

As indicated in Table 2-2, the AUCB provides for three levels oferror 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 volumehas been mounted) and a unit attention is detected, then mountverification will be initiated by the driver. However, if the CD-ROM isnot software-enabled, the event will simply be returned to theapplication 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 applicationprogram requires detailed knowledge of the particular CD being played.The application program must know which tracks include data and whichtracks include audio so it can use commands appropriate to thedifferent track types. Issuing an audio command on a data track resultsin the command failing with a status of SS$_DRVERR.

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

2.2.14.5 Programming Audio Applications

The following list contains information useful in avoiding problemswhen 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.

Previous Next Contents Index