OpenVMS_Routines

   The following list identifies the operating system specific
   routines.


   o  mrd_initialize_element(3mrd)

   o  mrd_move_medium(3mrd)

   o  mrd_position_to_element(3mrd)

   o  mrd_prevent_allow(3mrd)

   o  mrd_read_element_status(3mrd)

   o  mrd_ready(3mrd)

   o  mrd_request_sense(3mrd)

   o  mrd_test_unit_ready(3mrd)

   The operating system interface routines can be called directly
   and share three common traits.

   Trait 1

   Instead of a medium changer name, they accept a robot_info_t
   data structure that has been opened by mrd_startup(3mrd). This
   allows them to be called without the repeated start-up time of
   mrd_startup(3mrd) and allows keeping the medium changer open by a
   single application.

   Trait 2

   Instead of zero-relative element addresses, these routines all
   use absolute element addresses. These address can be calculated
   by adding the zero-relative address of a specific element to the
   element start address from the robot_info_t structure.

   For example:



    /*
     * Given an robot_info_t initialized with mrd_startup(3mrd)
     * or mrd_show(3mrd), an element type and a relative element
     * address, convert it to an absolute address.
     */
    convert_relative(robot_info_t *robot_info, int type, int element)
    {
     switch( type )
     case SLOT:
      return element + robot_info->slot_start ;
     case TRANSPORT:
      return element + robot_info->transport_start ;
     case DRIVE:
      return element + robot_info->device_start ;
     case PORT:
      return element + robot_info->port_start ;
     default:
      return -1 ;
     }
    }

   The routine mrd_move_medium(3mrd) is used by mrd_move(3mrd),
   mrd_load(3mrd), mrd_unload(3mrd), mrd_eject(3mrd) and mrd_
   inject(3mrd). These routines accepts the absolute transport,
   source and destination element addresses for a Move Medium
   command, as well as a value to indicate whether the medium should
   be inverted when moved.

   The routine mrd_read_element_status(3mrd) is used by mrd_
   show(3mrd) and a variety of internal utility functions. It offers
   direct access to the SCSI Read Element Status command. However,
   the data returned is also uninterpreted Read Element Status data,
   so the application using it must interpret the data for itself.
   Since mrd_show(3mrd) allows keeping the medium changer open as
   well, it is usually easier to use, except for simple requests.

   The routine mrd_position_to_element(3mrd) is used by mrd_
   position(3mrd). It offers direct access to the SCSI Position
   to Element command, accepting absolute element addresses for
   the transport and destination elements. It can also invert the
   transport where this is supported.

   The routine mrd_initialize_element(3mrd) is used by mrd_
   initialize(3mrd). It offers direct access to the SCSI Initialize
   Element Status command.

   The routine mrd_ready(3mrd) is used by mrd_ready_inport(3mrd).
   It offers direct access to the SCSI Position to Element command,
   accepting the absolute addresse of the port to be readied.

   The routine mrd_prevent_allow(3mrd) is used by mrd_lock(3mrd).
   It offers direct access to the SCSI Prevent Allow Media Removal
   command, accepting a value to indicate which is desired.

   The mrd_test_unit_ready(3mrd) routine performs a SCSI Test Unit
   Ready command, or equivalent if some other I/O architecture is
   supported. It is used by the mrd_startup(3mrd) and the OpenVMS
   implementation of mrd_ready(3mrd).

   The mrd_request_sense(3mrd) routine performs a SCSI Request
   Sense command, or equivalent if some other I/O architecture is
   supported. It is used by all MRD API routines to determine the
   cause of a command failure.



   Trait 3

   Finally, these routines accept the address of a dev_status_t
   structure for holding error status, instead of a the log_info
   string used by the other routines. This allows custom formatting
   of 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.