| Previous | Contents |
mrd_scsi_decode, mrd_map_os_error -
Various MRD utility functions
25.1 Media Robot Driver Library
The following table shows the names of the MRD library modules for each operating system.
| Windows NT | mrd.dll |
| UNIX | /usr/lib/libmrd.a |
| OpenVMS | MRD$RTL.EXE |
#include <mrd_common.h> #include <mrd_message.h> int mrd_scsi_decode(dev_status_t *dev_status); int mrd_map_os_error(int os_status, char *log_info); |
The routine mrd_scsi_decode(3mrd) is used by the low level MRD routines to map SCSI device errors to MRD_STATUS codes. It uses the Additional Sense Code (asc) and Additional Sense Code Qualifier (ascq) of the status structure to find an appropriate MRD_STATUS code. If both the asc and ascq are zero (0), the Sense Key (key) will be used to determine the code. The resulting MRD_STATUS code will be copied to the code field and returned.
The routine mrd_map_os_error(3mrd) is used to map operating system specific failures to MRD_STATUS codes. If the os_status isn't recognized, the routine will return MRD_STATUS_OS_ERROR. If the log_info argument is a valid pointer, a copy of the operating system text for the message will also copied to the space provided.
This routine uses the dev_status_t structure for handing errors. The dev_status_t structure includes the code, os_status, and SCSI error fields. The following describes how to decode errors with the dev_status_t structure.
SCSI Errors SCSI errors are indicated when the value of the valid field of the SCSI error is not equal to 0. The key, asc, and ascq fields provide additional information to help determine the cause of the error. The code usually maps the Additional Sense Code and Additional Sense Code Qualifier (ASC/ASCQ) values to an MRD error. The asc and ascq values are copied from the request sense data returned by the target. The Additional Sense Code (asc) indicates further information related to the error or exception condition reported in the sense key field. The Additional Sense Code Qualifier (ascq) indicates detailed information related to the additional sense code. For more information, consult the SCSI-2 Specification. Operating System Errors Operating system errors are indicated when the value of the valid field of the SCSI error is equal to 0 and the value of the os_status field is not equal to 0. This result is most likely caused by an operating system error, and probably has a mapped error in MRD. MRD Errors MRD errors are indicated when the value of the os_status field is 0, and the value of the valid field of the SCSI error is 0. This result is most likely caused when MRD encounters its own failure.
25.3.1 Example
/*
* This shows how the utility routines are used. For
* mrd_scsi_decode(3mrd), a selected SCSI-2 error will
* be filled into the key, asc and ascq fields of a
* dev_status_t structure and the resulting MRD status
* message printed. For mrd_map_os_error(3mrd) the
* will be done for a selected operating system error.
*
* Usage:
*
* mrd_utility
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_utility.c 1.2 3/5/97" ;
#endif
#include <stdlib.h>
#include <errno.h>
#include <stdio.h>
#include <math.h>
#include <time.h>
#include <mrd_common.h>
#include <mrd_message.h>
#ifdef vms
#include <ssdef.h>
#endif
main(int argc, char *argv[])
{
dev_status_t dev_status ; /* Device status */
int status ;
char log_info[MRD_MAX_LOG_STRING+1] ;
/*
* Clear this for later.
*/
log_info[0] = '\0' ;
/*
* First, try mrd_scsi_decode(3mrd). SCSI-2 happens to
* have ASC/ASCQ codes for a cleaning cartridge being
* installed somewhere, presumably a drive. We'll
* see what MRD does with it.
*/
dev_status.valid = SCSI_REQ_SENSE_VALID ;
dev_status.key = 1 ; /* Recovered Error */
dev_status.asc = 0x30 ;
dev_status.ascq = 3 ;
status = mrd_scsi_decode(&dev_status) ;
/*
* Now print the result. As it happens we map this
* code to MRD_STATUS_AUTOCLEAN, which is nearly
* right.
*/
printf("Cleaning Cartridge Installed: (%d,%x,%x): %s\n",
dev_status.key, dev_status.asc,
dev_status.ascq, mrd_strstatus(status)) ;
/*
* Now do one of completely random values. Seed the
* random number generator just so most get a different
* answer. Most of these are likely to end up as
* Vendor Unique errors.
*/
srand(time(NULL)) ;
dev_status.key = rand() % 16 ; /* 0 - 15 */
dev_status.asc = rand() % 256 ; /* 0 - 255 */
dev_status.ascq = rand() % 256 ; /* 0 - 255 */
status = mrd_scsi_decode(&dev_status) ;
/*
* Now print the result.
*/
printf("Random SCSI Decode: (%d,%x,%x): %s\n",
dev_status.key, dev_status.asc,
dev_status.ascq, mrd_strstatus(status)) ;
/*
* Now an OS error. If #ifdef is handle the two example
* operating systems.
*/
dev_status.valid = 0 ;
#if defined(VMS)
dev_status.os_status = SS$_UNASEFC ;
#elif defined(unix)
dev_status.os_status = EINTR ;
#else
dev_status.os_status = rand() % 100 ;
#endif
status = mrd_map_os_error(dev_status.os_status, log_info) ;
if( log_info[0] )
printf("Map OS Error: %d: %s: %s\n", dev_status.os_status,
mrd_strstatus(status), log_info) ;
else
printf("Map OS Error: %d: %s\n", dev_status.os_status,
mrd_strstatus(status)) ;
return 0 ;
}
|
The status returned is always a valid MRD_STATUS code corresponding to
the error given by the status or os_status. The
errors and their mappings are:
25.3.2.1 Common Codes
25.3.2.1.1 MRD_STATUS_PARAM
This error is returned if the dev_status argument is a NULL
pointer.
25.3.2.1.2 MRD_STATUS_NO_SENSE
This error is returned by mrd_scsi_decode(3mrd) when the asc, ascq and key values are all zero (0). It is also returned when the key value is less than zero or greater than 15.
25.3.2.1.3 MRD_STATUS_RECOVERED_ERROR
This error occurs when a SCSI device returns only a sense key of 1h. This indicates that although a command successfully completed, the target device had performed some internal error recovery.
25.3.2.1.4 MRD_STATUS_MEDIUM_ERROR
This error occurs when ASC and ASCQ are zero, but the sense key is 3h. This occurs when the target encounters a nonrecoverable error due to a flaw in the medium.
25.3.2.1.5 MRD_STATUS_ROBOT_HW_ERROR
This error occurs when ASC and ASCQ are zero, but the sense key is 4h. This occurs when the target encounters a nonrecoverable hardware error.
25.3.2.1.6 MRD_STATUS_ROBOT_ILLEGAL_REQUEST
This error occurs for a variety of reasons. It is used when a sanity check fails in the code that attempts to move a cartridge to the Pass-Through Mechanism, when the robot type isn't a TL82n. It is used in the mrd_lock(3mrd) code when the value is not one of ALLOW_REMOVAL or PREVENT_REMOVAL. It is used when the medium changer does not support the Prevent/Allow Medium Removal command or the lock value is not one or zero. The specific cause can be determined by examining the ASC/ASCQ values in the status data. It is used when a call to mrd_initialize_element(3mrd) is issued against a medium changer that does not support the Initialize Element Status command. It is used when the medium changer does not support the Position To Element command. The seven and five slot DLT loaders do not support the command, though the TL820 and TL810 family libraries do. Some models of TLZ6L and TLZ7L do not support the command and may take a long time to fail. It is used when the medium changer does not support the Ready Inport command. The TL820 family of DLT libraries support this command. The TL810 family of DLT libraries allows this command to succeed, but it doesn't perform any function. It is also used for a SCSI command failure, when the ASC is set to one of:
This error occurs when a SCSI command fails with the ASC set to one of 0x29, 0x2A or 0x2F. The log_info contains the ASCQ. The SCSI translations for these error codes are:
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is seven (7).
25.3.2.1.9 MRD_STATUS_BLANK_CHECK
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is eight (8).
25.3.2.1.10 MRD_STATUS_VENDOR_UNIQUE_ERROR
This error occurs when the internal routine used to decode SCSI-2 errors encounters an error that it has not been written to antipicate. This error is also returned when the ASC is zero and the ASCQ is not one of zero or six, and when ASC/ASCQ are both zero and the key is 9h.
25.3.2.1.11 MRD_STATUS_COPY_ABORTED
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is ten (10).
25.3.2.1.12 MRD_STATUS_SENSE_EQUAL
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Ch (12).
25.3.2.1.13 MRD_STATUS_VOLUME_OVERFLOW
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Dh (13).
25.3.2.1.14 MRD_STATUS_MISCOMPARE
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Eh (14).
25.3.2.1.15 MRD_STATUS_SENSE_RESERVED
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Fh (15).
25.3.2.1.16 MRD_STATUS_ROBOT_COMM_ERROR
This error also occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error occurs when a SCSI command fails with the ASC set to 0x30 and the ASCQ set to 0x3. On TL8nn libraries supporting Auto-clean, it indicates that a command was attempted while an auto-clean was in progress.
25.3.2.1.19 MRD_STATUS_CART_DAMAGED
This error occurs when a SCSI command fails with the ASC set to 0x30, but the ASCQ is NOT a value of 0x3. The log_info will contain the ASCQ.
25.3.2.1.20 MRD_STATUS_ELEMENT_INVALID
This error occurs when a SCSI command fails with the ASC set to 0x21. The log_info will contain the ASCQ. This indicates that an invalid element address reached the medium-changer. For example, specifying the 13th slot when only 12 slots are present.
25.3.2.1.21 MRD_STATUS_CART_NOT_AVAIL
This error can occur on the TL81n and TL82n family of DLT libraries when the source of a move is a drive and the cartridge in the drive is still on-line. These robots do not allow moving the cartridge until the drive is taken offline.
25.3.2.1.22 MRD_STATUS_DESTINATION_FULL
On routines that perform a SCSI Move Medium command, this error indicates that the destination element already has a cartridge in it.
25.3.2.1.23 MRD_STATUS_SOURCE_EMPTY
On routines that perform a SCSI Move Medium command, this error indicates that the source element is empty.
25.3.2.1.24 MRD_STATUS_ROBOT_DOOR_OPENED
This occurs when a SCSI command fails with the ASC set to 0x80 and the ASCQ set to 0x0. On TL8nn libraries this typically indicates that the cabinet door was opened during a command operation.
25.3.2.2 Windows NT Codes
The codes in this section apply only to the Windows NT operating system variant of the Media Robot Driver.
25.3.2.2.1 MRD_STATUS_IVCHAN
This error code is returned when the handle in NT parlance has been closed or is otherwise an invalid handle.
25.3.2.2.2 MRD_STATUS_ROBOT_NOT_READY
Under Microsoft Windows NT, this error code is returned when the specified robot exists but is not responding.
25.3.2.2.3 MRD_STATUS_ROBOT_CMD_ABORTED
This error is returned by mrd_scsi_decode(3mrd) when the asc is zero and the ascq is six, or when the asc and ascq are zero and the key is eleven (11).
25.3.2.3 Digital UNIX Codes
The following error codes can occur when a open(2) or ioctl(2) system call fails. Open(2) is used by mrd_startup(3mrd) to open the medium-changer. The ioctl(2) system call is used to perform all other SCSI medium-changer commands.
25.3.2.3.1 MRD_STATUS_EBADF
This error occurs when the medium changer has not been opened by mrd_startup(3mrd) or has been closed by mrd_shutdown(3mrd).
25.3.2.3.2 MRD_STATUS_EINVAL
This error is returned by mrd_map_os_error(3mrd) when the os_status is EINVAL. This typically occurs during mrd_startup(3mrd) when the special file is not a SCSI device: for example, /dev/tty.
25.3.2.3.3 MRD_STATUS_STARTUP_ERROR
This error is returned by mrd_map_os_error(3mrd) when the os_status is ENODEV. This typically occurs during mrd_startup(3mrd) when the special file is not a SCSI device; /dev/null.
25.3.2.3.4 MRD_STATUS_NO_SUCH_DEVICE
This error occurs when a UNIX system call returns ENXIO, to indicate that the device corresponding to the special device does not exist.
25.3.2.3.5 MRD_STATUS_EBUSY
This error occurs when a UNIX system call returns EBUSY, to indicate that some other process is using that medium-changer device.
25.3.2.3.6 MRD_STATUS_EINTR
This error occurs when a UNIX system call returns EINTR. This error corresponds to an interrupted system call, but also occurs when the SCSI CAM Layered Components Medium-Changer driver is not configured into the running system.
25.3.2.3.7 MRD_STATUS_EIO
This error occurs when a UNIX system call returns EIO to indicate that there was an I/O error. In most cases an I/O error on a SCSI medium-changer indicates a SCSI error which be translated to another MRD error.
25.3.2.3.8 MRD_STATUS_ENOENT
This error occurs when a UNIX system call returns ENOENT to indicate that a special device file doesn't exist.
25.3.2.3.9 MRD_STATUS_EACCES
This error occurs when a UNIX system call returns EACCES to indicate that the caller does not have sufficient permission to open the special device file corresponding to the medium-changer. MRD expects to have read permission on the special device file.
25.3.2.3.10 MRD_STATUS_OS_ERROR
This error occurs when a UNIX system call returns an error that is not among those previously mentioned. The routine strerror(3) will be used to translate the error code into a standard text message which will be copied to log_info.
25.3.2.3.11 MRD_STATUS_ROBOT_NOT_READY
Under OpenVMS and Digital UNIX, this error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error is returned by mrd_scsi_decode(3mrd) when the asc is zero and the ascq is six, or when the asc and ascq are zero and the key is eleven (11).
25.3.2.4 OpenVMS Codes
The codes in this section apply only to the OpenVMS operating system variant of the Media Robot Driver.
25.3.2.4.1 MRD_STATUS_DEVICE_INVALID
This error is returned when the element address for a drive is less than zero or greater than the number of drives. This error code is used when an OpenVMS system service fails with the status SS$_NOSUCHDEV or SS$_IVDEVNAM. This will typically occur in mrd_startup(3mrd) when the caller tries to open a device which doesn't exist or uses an invalid device name. This error also occurs when the routine is called on behalf of a device controlled by the JU driver. The Media Robot Utility no longer uses the JU driver.
25.3.2.4.2 MRD_STATUS_ROBOT_NOT_READY
Under OpenVMS and Digital UNIX, this error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error code is used when an OpenVMS system service fails with the status SS$_ABORT.
25.3.3 Related Information
Functions:
| Previous | Contents | Contents |