VMS Help
MRD Library, mrd_utility

 *Conan The Librarian

    mrd_scsi_decode, mrd_map_os_error - Various MRD utility functions

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

  1 - Parameters

    o  dev_status The dev_status is the address of a dev_status_t
       structure. The fields in this structure are examined to map a
       SCSI error to an MRD_STATUS code.

    o  os_status The os_status is an operating system specific
       failure code that is used to find the matching MRD_STATUS
       code.

    o  log_info The log_info is a character array that should be at
       least MRD_MAX_LOG_STRING in length. On returning, it contains
       the operating system status.

  2 - Description

    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.

  3 - 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 ;
    }

  4 - Return Values

    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:

 4.1 - MRD_STATUS_PARAM

    This error is returned if the dev_status argument is a NULL
    pointer.

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

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

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

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

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

    o  0x1A - Parameter list length error

    o  0x20 - Invalid command operation code

    o  0x22 - Unsupported command

    o  0x24 - Illegal field in CDB

    o  0x25 - Logical unit not supported

    o  0x26 - Threshold parameters not supported

    o  0x28 - Import or Export element accessed

    o  0x2C - Command sequence error

    o  0x39 - Saving parameters not supported

    o  0x3D - Invalid bits in Identify message

    o  0x53 - Medium removal prevented

    This status is also returned when the ASC and ASCQ are zero, but
    the key is five (5).

 4.7 - MRD_STATUS_ROBOT_ATTENTION

    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:

    o  0x29 - Power-on, Reset or Bus device reset occurred

    o  0x2A - Mode Parameters Changed

    o  0x2F - Command cleared by another initiator

    This error also occurs when the ASC and ASCQ are zero, but the
    SCSI sense key is 6h.

 4.8 - MRD_STATUS_DATA_PROTECT

    This error is returned by mrd_scsi_decode(3mrd) when the asc and
    ascq are zero, but the key value is seven (7).

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

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

 4.11 - MRD_STATUS_COPY_ABORTED

    This error is returned by mrd_scsi_decode(3mrd) when the asc and
    ascq are zero,

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

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

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

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

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

    o  0x08 - Logical unit communcation errors.

    o  0x43 - Message error

    o  0x45 - Select or Reselect failure

    o  0x47 - SCSI parity error

    o  0x48 - Initiator detected error message received

    o  0x49 - Invalid message error

    o  0x4A - Command phase error

    o  0x4B - Data phase error

    o  0x4E - Overlapped commands attempted

    o  0x54 - SCSI to host system interface failure

 4.17 - MRD_STATUS_ROBOT_MECH_ERROR

    This error occurs as the result of a SCSI command failure, when
    the ASC is set to one of:

    o  0x15 - Positioning error.

    o  0x8B - Vendor unique; Pass-through mechanism errors on the
       TL82n

 4.18 - MRD_STATUS_AUTOCLEAN

    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.

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

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

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

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

 4.23 - MRD_STATUS_SOURCE_EMPTY

    On routines that perform a SCSI Move Medium command, this error
    indicates that the source element is empty.

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

 4.25 - MRD_STATUS_DEVICE_INVALID

    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.

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

    o  0x80 - When the ASCQ is not zero (0).

    o  0x81 - Vendor unique; gripper errors on the TL82X and TL81X

    o  0x04 - Logical unit not ready

    o  0x3E - Logical unit has not been self configured

    o  0x40 - Diagnostic failure; ASCQ indicates component

    o  0x42 - Power-on self test failure

    o  0x44 - Internal target failure

    o  0x46 - Unsuccessful soft reset

    o  0x4C - Logical unit failed self-configuration

    This status is also returned when the ASC and ASCQ are zero, but
    the key is two (2).

 4.27 - MRD_STATUS_ROBOT_CMD_ABORTED

    This error code is used when an OpenVMS system service fails with
    the status SS$_ABORT.

  5 - Related Functions

    Functions:

    o  mrd_move_medium(3mrd)

    o  mrd_read_element_status(3mrd)

    o  mrd_startup(3mrd)

    o  mrd_position_to_element(3mrd)

    o  mrd_initialize_element(3mrd)

    o  mrd_ready(3mrd)

    o  mrd_prevent_allow(3mrd)
  Close     Help