The first OpenVMS implementation of MRD supported the TF and TA family DLT media-changers. It used Mass Storage Control Protocol Display commands to indicate what cartridge should be moved. The MSCP uses cartridge address names instead of numbers as SCSI does. When SCSI support was added to the MRD, the convention of using strings for the address was kept and thus it has been since.

In the common interface example programs, the character strings for the addresses are taken directly from the command line arguments and no special formatting is necessary. But, in practice, a program will probably keep SCSI addresses in numeric form and will have to convert those to strings. In the MRU command line interface and graphic user interface we use sprintf(3) for this:

int element_number ;
char element[MRD_NAME_SIZE+1] ;

element_number = 5 ;

sprintf(element, "%d", element_number) ;

The following list identifies the common routines.

The common routines will open a robot to perform their operations. All these routines will close the robot when successfully completed, except for mrd_ show(3mrd). The mrd_show(3mrd) routine closes the robot only when it encounters an error.

The routine mrd_startup(3mrd) is used to open a medium-changer. It will fill in a robot_info_t data structure that contains the number of elements of each type, their addresses and the medium-changer SCSI Inquiry data. Thus, it is unnecessary (and often not desirable) to keep the robot open while it is being used. The routine mrd_shutdown(3mrd) can be used to close the robot. Aside from closing the file and setting the channel field to BAD_CHANNEL, it has no effect on the other data in the robot_info_t data structure.

Use the mrd_show(3mrd) routine to obtain information about the contents and state of the slots, drive, ports and transports of the medium-changer. The mrd_ show(3mrd) routine will open a robot, but it will also work if the robot is already open when the routine is called. For each element requested, an element_info_t data structure will be set if the element exists. The mrd_show(3mrd) function will accept the address of a robot_info_t data structure. If the robot has already been opened by mrd_startup(3mrd), this open robot will be used by the routine. If the robot isn't open (indicated by the channel field set to BAD_CHANNEL), the medium-changer indicated by the robot_name will be opened. If the routine completes successfully, the medium-changer will remain open. On an error, the medium-changer will be closed and the channel field reset to BAD_CHANNEL. By keeping the medium-changer open, multiple calls can be made to mrd_ show(3mrd) without incurring the time to call mrd_startup(3mrd) each time.

The routine mrd_move(3mrd) is a general interface to the SCSI Move Medium command. It allows the specification of source and destination elements for the move, whether the medium should be inverted and an optional volume tag. On medium-changers which have a vision system to read bar-codes, the volume tag can be used to verify that the medium in the source slot is the one desired.

The routines mrd_load(3mrd), mrd_unload(3mrd), mrd_inject(3mrd) and mrd_eject(3mrd) are specialized interfaces to the SCSI Move Medium command. Load will move a medium from a slot to a drive. Unload will move a medium from a drive to a slot. Inject moves a medium from a port to a slot and Eject from a slot to a port. On the TL82x family of libraries, mrd_eject(3mrd) can also be used to clear a medium from the Pass-Through Mechanism.

The routine mrd_lock(3mrd) enables sending a SCSI Prevent/Allow Media Removal command. Whether this command is supported, and its effect, depends on the robot.

The routine mrd_initialize(3mrd) sends a SCSI Initialize Element Status command. The effect of this command varies among robots, but it typically causes complete reinventory of the medium-changer.

The routine mrd_position(3mrd) sends a SCSI Position to Element command.

The routine mrd_ready_inport(3mrd) sends a vendor unique, Ready Inport command. On the TL82n family of libraries, this command enables the button which opens the Inport/Outport Device inport door. Other libraries and loaders may silently ignore this command or treat it as an illegal command.

On medium-changers which keep track of a medium's previous element location, the routine mrd_home(3mrd) returns a medium to that location.

On medium-changers with vision systems to read bar-code labels, the routine mrd_find_cartridge(3mrd) will search for a specified volume tag. The routine will search the entire library, or just a subset of elements according to the arguments used.

The routine mrd_map_element(3mrd) accepts an element's absolute address and returns the element type and zero relative address.

The routine mrd_strstatus(3mrd) accepts an MRD error status code and returns the corresponding message text. The routine mrd_strelement(3mrd) accepts an MRD_ELEMENT code for various words which apply to SCSI-2 medium-changer elements and returns the corresponding string. The routine mrd_strexcept(3mrd) accepts the Additional Sense Code and Additional Sense Code Qualifier for an element with an exception and returns the corresponding message text.

The following list identifies the operating system specific routines.

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.

Compiling a Tru64 UNIX Application with MRD

The files <mrd_common.h> and <mrd_message.h> must be included by any source module wishing to use the MRD interface. The library was compiled with the - migrate and default optimization options available with the DEC OSF/1 V1.3 C compiler.

If the calling program is not compiled with the -migrate option, it will be necessary to link with the OTS library, </usr/lib/libots.a>. If not, the following symbols will be unresolved:

% make mrd_move
cc -O -c mrd_move.c
cc -O mrd_move.o -lmrd -o mrd_move
ld:U
nresolved:
_OtsDivide64Unsigned
_OtsMove
_OtsDivide32
*** Exit 1
Stop.

The subset containing the <libots.a> object library has changed over the versions. In DEC OSF/1 V1.3 it is part of the OTABASE. subset. By DEC OSF/1 V3.0 it had moved to OSFCMPLRS300, where it has remained through Tru64 UNIX V4.0.

Upon successful completion, the Media Robot Driver library routines that access a medium-changer return the value MRD_STATUS_SUCCESS. On a failure, one of the following errors may be returned. The Media Robot Driver library will attempt to map SCSI failures to one of a small group of error codes, but not all errors have been anticipated.

Many of the MRD routines accept a log_info argument that is a character array. When a SCSI error occurs, the the Sense Key, additional Sense Code and Additional Sense Code Qualifier are formatted into the space provided. If the error is an operating system specific error, then the text corresponding to the error will be copied into the space provided.

Functions:

/*
 * Example mrd_eject(3mrd).
 *
 * This example is slightly different from the others since it
 * also demonstrates the Eject Port feature of mrd_eject(3mrd).
 * This feature can be used on the TL820 family to move a tape
 * from the Pass-through mechanism (PTM) to the outport.
 *
 * The command usage is:
 *
 * mrd_eject robot [ slot port [ volume_tag ] ]
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_eject.c   1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int    status ; /* Status from mrd_eject(3mrd) */
   char    *robot ; /* Name of the robot to use */
   char    *volume_tag = NULL ; /* Volume tag to check */
   char    *slot ; /* Source slot */
   char    *port ; /* Destination port */
   char    log_info[MRD_MAX_LOG_STRING+1] ; /* Error text */

   /*
    *    Allow the command to only have the robot name specified.
    */
   if( argc < 2 ) {
      printf("usage: %s robot [ slot port [ volume_tag ] ]\n",
         argv[0]) ;

      exit(1) ;
   }
   else
      robot = argv[1] ;
/*
 * If the slot and port aren’t specified assume that
 * the target robot is a TL820 and fill in default
 * values for an Eject Port. Otherwise take the
 * desired values directly from the command line.
 */
if( argc >= 4 ) {
   slot = argv[2] ;
   port = argv[3] ;

   /*
    * Collect the volume_tag name if the user wants it.
    */
   if( argc > 4 )
      volume_tag = argv[4] ;
}
/*
 * We also observe that this case catches the command:
 *
 * mrd_eject robot_name address
 *
 * It can’t hurt to let the user specify the outport,
 * since an invalid one simply won’t work. In this case
 * the 3rd argument is the port name instead of the slot
 * name.
 *
 * The user could get the same affect by using a quoted
 * empty string for the slot argument on the command line:
 *
 * robot /dev/mc54 "" 1
*/
else {
   if( argc == 3 )
      port = argv[2] ;
   else
      port = "1" ;

   slot = "" ;
}

/*
 * Do the operation.
 */
status = mrd_eject(robot, volume_tag, slot, port, log_info) ;

if( status == MRD_STATUS_SUCCESS )
   printf("Ejected the media in slot #%d to port #%d.\n",
      slot, port) ;
else
   printf("Eject failed: %s: %s.\n", mrd_strstatus(status),
      log_info[0] ? log_info : "none") ;

   return 0 ;
}

Upon successful completion, the mrd_eject(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_eject(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

The element_info_t data structure is defined in the include file <mrd_ common.h>. The fields of this data structure are described below:

ELELMENT_EMPTY, or ELEMENT_EXCEPT.

IN_OUT_PORT, INPORT, OUTPORT.

MRD_STATUS_SLOT_INVALID, MRD_STATUS_DEVICE_INVALID, MRD_STATUS_TRANSPORT_INVALID, MRD_STATUS_PORT_INVALID, or

MRD_STATUS_SUCCESS.

/*
 * Example of mrd_find_cartridge(3mrd). The command usage is:
 *
 * mrd_find robot_name volume_tag
 */
#ifndef lint
static char SccsId[] = "@(#)mrd_find.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   element_info_t element ;    /* Element data result */
   int   status ;     /* status from mrd_find_cartridge(3mrd) */
   char   *robot ;     /* Medium changer to search */
   char   *volume_tag ;     /* Volume tag for which to search */
   int   type ;     /* Element type result */
   char   *content ;     /* element content */
   char   *format ;     /* format to print element data */
   char   address[MRD_NAME_SIZE+1] ;   /* Element name result */
   char   log_info[MRD_MAX_LOG_STRING+1] ;     /* error text */
   char   exception[BUFSIZ+1] ;     /* exception buffer */

   /*
    * There are two required arguments; robot name and volume tag.
    */
   if( argc < 3 ) {
      printf("usage: %s robot volume-tag\n", argv[0]) ;
      exit(1) ;
   }

   robot = argv[1] ;
   volume_tag = argv[2] ;

   /*
    * Search all of the elements at the same time. With the
    * type set to zero, the values of element_address ("")
    * and element_count (0), don’t matter.
    */
   status = mrd_find_cartridge(robot, volume_tag, 0, "", 0, &element,
         address, &type, log_info) ;

   if( status != MRD_STATUS_SUCCESS )
     printf("Can’t find volume %s: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;

   /*
    * Need to print out the results of the find. This is
    * similar to that used by mrd_show, but is a bit more
    * extensive to show more features.
    */
   format = "%s\t%s\t%s\n" ; /* default format */

   if( element.name[0] )
      content = element.name ;
   else if( element.state & ELEMENT_FULL )
      content = "Full" ;
   else if( element.state & ELEMENT_EXCEPT ) {
      format = "%s\t%s\t%s\t%s\n" ;
      content = "Exception" ;

      (void)mrd_strexcept(element.data.asc, element.data.ascq,
         exception, BUFSIZ) ;
   }
   else
      content = "Empty" ;

   if( element.state & ELEMENT_EXCEPT )
      printf(format, mrd_strelement(type), address, content,
         exception) ;
   else
      printf(format, mrd_strelement(type), address, content) ;

   return 0 ;
}

Upon successful completion, the mrd_find_cartridge(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_find_cartridge(3mrd) fails the returned status value may be set to one of the following values. This routine may also return any of the errors descibed in the mrd_show(3mrd) manual page.

Other values that correspond to specific SCSI errors may also be possible, but the ones below are most likely.

The SCSI-2 specification includes two commands which allow a medium-changer to perform most of the work that this routine does by brute force. Unfortunately, a reliable implementation of these commands was unavailable at the time MRD V1.2 was written. A future version of the API may be able to make use of these routines to speed up a search.

Unlike mrd_show(3mrd) this routine will open and close the robot at each iteration.

Functions:

/*
 *  Example to do slot to slot moves. The command usage is:
 *
 *    mrd_home robot_name type address [ volume-tag ]
 *
 *  Type can be one of:
 *
 *    slot, port, drive or transport
 *
 *  The optional transport argument can be a transport address
 *  number, the word "default" or an empty string.
 */
#ifndef lint
static char SccsId[] = "@(#)mrd_home.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mrd_common.h>
#include <mrd_message.h>

/*
 * Given a string, resembling one of the element types,
 * return the SCSI type code for it.
 */

struct {
   int   code ;
   char   *string ;
} etypes[] = {
   TRANSPORT,   "transport",
   SLOT,   "slot",
   DRIVE,   "drive",
   PORT,   "port",
} ;

convert_type(char *etype)
{
   register i ;

   /*
    * For each entry in the array.
    */

   for(i = 0; i < sizeof(etypes)/sizeof(etypes[0]); i++)
      /*
       * Do a case insensitive comparison, allowing
       * abbreviations. Return as soon as a match is
       * found. Return -1 if one isn’t found.
       */
#ifdef vms
      if( strncmp(etypes[i].string, etype, strlen(etype)) == 0)
#else
      if( strncasecmp(etypes[i].string,etype,strlen(etype)) == 0)
#endif
         return etypes[i].code ;
   return -1 ;
}

main(int argc, char *argv[])
{

   int   status ;   /* Status from mrd_home(3mrd) */
   char   *robot ;   /* Robot to use */
   char   *element ;   /* Element address */
   char   *volume_tag = NULL ;   /* Optional volume tag */
   int   type ;   /* Element type */
   char   home[MRD_NAME_SIZE+1] ;   /* space for return address */
   int   home_type ;   /* return element type */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error string */

   /*
    * Three required arguments; robot, element type and address.
    */
   if( argc < 4 ) {
      printf("usage: %s robot type address [ volume_tag ]\n",
         argv[0]) ;

      exit(1) ;
   }
   robot   = argv[1] ;
   type    = convert_type(argv[2]) ;
   element = argv[3] ;
   /*
    * Optional volume tag.
    */
   if( argc > 4 )
      volume_tag = argv[4] ;
   /*
    * Do the operation.
    */
   status = mrd_home(robot, volume_tag, element, type,
         home, &home_type, log_info) ;

   if( status != MRD_STATUS_SUCCESS )
      printf("Home failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   else
      printf("The cartridge in %s %s was returned to %s %s.\n",
         mrd_strelement(type), element,
         mrd_strelement(home_type), home) ;
   return 0 ;
}

Upon successful completion, the mrd_home(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_home(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

/*
 *   Example of mrd_initialize(3mrd). The command usage is:
 *
 *   mrd_init robot_name
 *
 *   It has been observed on an empty TL820 with all the
 *   bin-packs in place that this command takes just under
 *   23 minutes.
 */
#ifndef   lint
static   char SccsId[] = "@(#)mrd_init.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>

#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   status ;   /* Status from mrd_inject(3mrd) */
   char   *robot ;   /* The name of the robot */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error string */
   /*
    *  Accept one required argument; robot name
    */
   if( argc < 2 ) {
      printf("usage: %s robot\n", argv[0]) ;
      exit(1) ;
   }

   /*
    *   Just use this directly from the command line.
    */
   robot = argv[1] ;

   /*
    *   Because this routine can take a long time we’ll
    *   provide some positive feed-back that is doing
    *   something.
    */
   printf("Reinventory library %s...", robot); fflush(stdout) ;
   /*
    *   Call the function. Because this routine can take a
    */
   status = mrd_initialize(robot, log_info) ;
   /*
    *   Done.
    */
   putchar(’\n’) ;
   /*
    *   Print an error message if there is a failure. The
    *   routine mrd_strstatus(3mrd) will accept an MRD
    *   error status and return the corresponding string.
    *   If the log_info data has something other than a
    *   NULL as the first character print it as well. It
    *   typically be the SCSI sense data or a operating
    *   system specific message for the error.
    */
   if( status != MRD_STATUS_SUCCESS )
      printf("Initialize failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   return 0 ;
}

Upon successful completion, the mrd_initialize(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_initialize(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

/*
 *   Example of mrd_initialize_element(3mrd). The command usage is:
 *
 *   Usage:
 *
 *      mrd_initialize_element robot [ robot... ]
 *      robot_name
 *
 *   It has been observed on an empty TL820 with all the bin-packs
 *   in place that this command takes just under 23 minutes.
 */
#ifndef lint
static char SccsId[] = "@(#)mrd_initialize_element.c 1.3) 6/20/97";
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int     rc ;
   int     status ; /* return status */
   char     *robot ; /* Robot to open */
   robot_info_t   robot_info ; /* Robot data */
   dev_status_t   dev_status ; /* Device status */
   char     log_info[MRD_MAX_LOG_STRING+1] ;

   /*
    *   Check that there are enough arguments.
    */
   if( argc < 4 ) {
      printf("usage: %s robot [ robot... ]\n", argv[0]) ;
      exit(1) ;
   }

   /*
    *   Initialize the channel field of the robot_info, so
    *   mrd_startup(3mrd) will actually open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   for(rc = 1; rc < argc; rc++) {
      /*
       *   Save the current robot name.
       */
       robot = argv[rc] ;

       status = mrd_startup(robot, &robot_info, log_info) ;

       if( status != MRD_STATUS_SUCCESS ) {
          printf("Startup failed: %s: %s.\n",
             mrd_strstatus(status),
             log_info[0] ? log_info : "none") ;

          continue ;
       }

       printf("Initialize Element Status on %s...", robot) ;
       fflush(stdout) ;

       status = mrd_initialize_element(&robot_info, &dev_status) ;

       if( status != MRD_STATUS_SUCCESS )
          printf("Failed: %s.\n", mrd_strstatus(status)) ;
       else
          printf("Success.\n") ;

       (void)mrd_shutdown(&robot_info) ;
   }

   return 0 ;
}

Upon successful completion mrd_initialize_element(3mrd) will return MRD_ STATUS_SUCCESS. On a failure, an MRD_STATUS value corresponding to the error will be returned. Common errors are:

Functions:

mrd_initialize(3mrd)

/*
* Example of mrd_inject(3mrd). The command usage is:
*
* mrd_inject robot_name port slot [ volume_tag ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_inject.c 1.2 3/5/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>
main(int argc, char *argv[])
{
   int   status ;   /* Status from mrd_inject(3mrd) */
   char   *robot ;   /* The name of the robot */
   char   *volume_tag = NULL ; /* Optional volume tag to check */
   char   *port ;   /* Source port */
   char   *slot ;   /* Destination slot */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error string */
   /*
    * Accept three required argument; robot, port and slot. The
    * volume tag is optional.
    */
   if( argc < 4 ) {
      printf("usage: %s robot port slot [ volume-tag ]\n", argv[0]);
      exit(1) ;
   }

   /*
    * Just use these directly from the command line.
    */
   robot = argv[1] ;
   port  = argv[2] ;
   slot  = argv[3] ;

   /*
    * If the volume tag is present use it.
    */
   if( argc > 4 )
      volume_tag = argv[4] ;

   /*
    * Call the function.
    */
   status = mrd_inject(robot, volume_tag, port, slot, log_info) ;

   /*
    *   Print an error message if there is a failure.
    */
   if( status != MRD_STATUS_SUCCESS )
      printf("Inject failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   else
      printf("Injected media from Port #%s to Slot #%s.\n",
         port, slot) ;

   return 0 ;
}

Upon successful completion, the mrd_inject(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_inject(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

/*
 * Example of mrd_load(3mrd). The command usage is:
 *
 *   mrd_load robot_name slot drive [ volume_tag ]
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_load.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   status ;   /* Status from mrd_load(3mrd) */
   short   side = 1 ;   /* Only support single sided media */
   char   *robot ;   /* The name of the robot */
   char   *volume_tag = NULL ; /* Optional volume tag to check */
   char   *slot ;   /* Source slot */
   char   *drive ;   /* Destination drive */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error string */

   /*
    *   Accept three required argument; robot, port and slot. The
    *   volume tag is optional.
    */
   if( argc < 4 ) {
      printf("usage: %s robot slot drive [ volume-tag ]\n", argv[0]);
      exit(1) ;
   }

   /*
    * Just use these directly from the command line.
    */
   robot = argv[1] ;
   slot  = argv[2] ;
   drive = argv[3] ;

   /*
    *   If the volume tag is present use it.
    */
   if( argc > 4 )
      volume_tag = argv[4] ;

   /*
    *   Call the function.
    */
   status = mrd_load(robot, volume_tag, slot, side, drive, log_info);

   /*
    *   Print an error message if there is a failure.
    */
   if( status != MRD_STATUS_SUCCESS )
      printf("Load failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   else
      printf("Loaded media in Slot #%s to Drive #%s\n",
         slot, drive) ;

   return 0 ;
}

Upon successful completion, the mrd_load(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_load(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

Upon successful completion, the mrd_lock(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_lock(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

mrd_prevent_allow(3mrd)

/*
 *   For the specified robot, walk through the remainder of
 *   argument list and have mrd_map_element(3mrd) convert
 *   each address to a relative element address and type.
 *
 *     mrd_map_element robot address [ address... ]
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_map_element.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   char   *robot ;   /* Robot for command */
   int   status ;   /* status from mrd_startup(3mrd) */
   int   address ;   /* Input argument */
   int   type ;   /* element type */
   int   i ;   /* index counter */
   robot_info_t robot_info ;   /* Set by mrd_startup(3mrd) */
   char   result[MRD_NAME_SIZE+1] ;   /* relative address */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error text */

   /*
    *   Two required arguments, many optional ones.
    */
   if( argc < 3 ) {
      printf("usage: %s robot address [ address... ]\n", argv[0]) ;
      exit(1) ;
   }
   else
      robot = argv[1] ;

   /*
    *   Open the robot. Must set channel to BAD_CHANNEL so
    *   it will really open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   status = mrd_startup(robot, &robot_info, log_info) ;

   if( status != MRD_STATUS_SUCCESS ) {
      printf("Can’t open robot %s: %s: %s.\n", robot,
         mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;

      exit(1) ;
   }

   /*
    *   We don’t need to keep the robot for the remainder of
    *   the example.
    */
   (void)mrd_shutdown(&robot_info) ;
   /*
    *   For each address in the list, call mrd_map_element(3mrd).
    */
   for(i = 2; i < argc; i++) {
      address = atoi(argv[i]) ;

      type = mrd_map_element(&robot_info, address, result) ;

      if( type == 0 )
         printf("Can’t map %d on robot %s.\n", address, robot) ;
      else
         printf("Element %d -> %s %s\n", address,
            mrd_strelement(type), result) ;
   }

   return 0 ;
}

Upon successful completion, the mrd_map_element(3mrd) function returns the element type, which is one of SLOT, PORT, DRIVE or TRANSPORT. On an error it returns zero (0). The two possible errors are the robot_info address being NULL and the address not one used by this medium-changer.

Functions:

The following MRD_ELEMENT codes are those currently supported by mrd_ strelement(3mrd), with their corresponding default strings.

Most of the codes listed below are self-explanatory:

/*
 *   Illustrate the different mrd_str*(3mrd) functions. For each
 *   case a code from one the mrd_message.h is selected and the
 *   resulting string printed. The command doesn’t require
 *   any arguments.
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_string.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   /*
    *   This happens to be an obscure VMS system service error code.
    */
   int status = MRD_STATUS_UNASEFC ;
   /*
    *   The code for the TL820 Pass-through mechanism.
    */
   int word = MRD_ELEMENT_PASS ;
   /*
    *   The codes for when a TL820 doesn’t a have a bin-pack
    *   installed for a certain range of slots.
    */
   char   asc  = 0x80 ;
   char   ascq = 0x2 ;
   /*
    * Buffer for the message.
    */
   char buffer[BUFSIZ] ;

   printf("Status:    %s\n", mrd_strstatus(status)) ;
   printf("Word:      %s\n", mrd_strelement(word)) ;
   printf("Exception: %s\n", mrd_strexcept(asc,ascq,buffer,BUFSIZ));

   return 0 ;
}

These routines try very hard to return the corresponding error text, even to the point of formatting the integer value into the provided string, into a static buffer or returning a default string. These routines should never return NULL, but they rely on catgets(3) to do the underlying work of looking the error code in the message catalogs.

Functions:

File:

These additional files support programming in the Tru64 UNIX environment.

</usr/lib/nls/msg/en_LOCALE/mrd.cat>

</usr/include/mrd_message.h>

/*
 *   Example to do slot to slot moves, using mrd_move(3mrd). The
 *   reason for only doing slot to slot, is that it simplifies
 *   having to figure out element types. The mrd_position(3mrd)
 *   example shows how part of this may be done.
 *
 *   The command usage is:
 *
 *      mrd_move source-slot destination-slot [ volume-tag ]
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_move.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   status ;   /* Status from mrd_move(3mrd) */
   int   side = 1 ;   /* Only support side one */
   char   *robot ;   /* Name of the robot to use */
   char   *volume_tag = NULL ;   /* Volume tag to check */
   char   *source ;   /* Source slot */
   char   *destination ;   /* Destination slot */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error string */

   /*
    * Three required arguments; robot name, source slot and
    * destination slot.
    */
   if( argc < 4 ) {
   printf("usage: %s robot src dest [ volume-tag ]\n", argv[0]) ;
   exit(1) ;
   }

   robot       = argv[1] ;
   source      = argv[2] ;
   destination = argv[3] ;

   /*
    * Volume tag is optional.
    */
   if( argc > 4 )
      volume_tag = argv[4] ;

   /*
    * Do the operation.
    */
   status = mrd_move(robot, volume_tag, source, SLOT, destination,
         SLOT, side, log_info) ;

   if( status != MRD_STATUS_SUCCESS )
      printf("Move failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   else
      printf("Moved media from Slot #%s to Slot #%s\n",
         source, destination) ;

   return 0 ;
}

Upon successful completion, the mrd_move(3mrd) function returns the value MRD_STATUS_SUCCESS. If mrd_move(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

The operating system interface routines use absolute SCSI element addresses, instead of zero relative address as used by the higher level functions. A zero based element address can be converted to an absolute address by adding the element base address from the robot_info_t structure.

int slot ;
robot_info_t robot_info ;

/*
 * An relative starting address.
 */
slot = 3 ;

/*
 * Becoming an absolute address.
 */
slot += robot_info.slot_start ;

/*
 *   This is an example of using mrd_move_medium(3mrd) directly to
 *   move a cartridge from one slot to another. To simplify the
 *   example, it only supports slot to slot moves, but it shows
 *   how the absolute element addresses are calcuated. For each
 *   additional destination address given, the previous (successful)
 *   destination address is used as the source.
 *
 *   Usage:
 *
 *   mrd_move_medium robot source dest [ dest... ]
 */
#ifndef   lint
static   char SccsId[] = "@(#)mrd_move_medium.c 1.4 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   i ; /* counter */
   int   source ; /* Source address */
   int   dest ; /* Destination address */
   int   invert = 0 ; /* Assume it can’t invert */
   int   transport ; /* Transport address */
   int   status ; /* return status */
   char   *robot ; /* Robot to open */
   robot_info_t   robot_info ; /* Robot data */
   dev_status_t   dev_status ; /* Device status */
   char   log_info[MRD_MAX_LOG_STRING+1] ;
/*
 *   Check that there are enough arguments.
 */
if( argc < 4 ) {
   printf("usage: %s robot source dest [ dest... ]\n", argv[0]) ;
   exit(1) ;
}
else {
   robot = argv[1] ;
   source = atoi(argv[2]) ;
}

/*
 *   Initialize the channel field of the robot_info, so
 *   mrd_startup(3mrd) will actually open the robot.
 */
robot_info.channel = BAD_CHANNEL ;

status = mrd_startup(robot, &robot_info, log_info) ;

if( status != MRD_STATUS_SUCCESS ) {
   printf("Startup failed: %s: %s.\n", mrd_strstatus(status),
      log_info[0] ? log_info : "none") ;

   exit(1) ;
}

/*
 *   Set the transport address. If there is only one
 *   transport use the correct address. If there is
 *   more than one assume that the medium changer
 *   supports zero as the default.
 */
if( robot_info.transport_count == 1 )
   transport = robot_info.transport_start ;
else
   transport = 0 ;

/*
 *   Turn the relative slot address into an absolute slot
 *   address by adding the slot start address.
 */
source += robot_info.slot_start ;
/*
 *   For each destination address on the command line,
 *   move the the cartridge in the source to the
 *   destination. After each (successful) move, replace
 *   the previous source with this destination.
 */
for(i = 3; i < argc; i++) {
   /*
    * Calculate the absolute address.
    */
   dest = atoi(argv[i]) + robot_info.slot_start ;

   /*
    *   Print an audit as we go. Since we know these
    *   are slots, convert back to relative addresses
    *   for the audit.
    */
   printf("Move the medium in slot %d to slot %d\n",
      source - robot_info.slot_start,
      dest - robot_info.slot_start) ;

   status = mrd_move_medium(&robot_info, transport, source,
         dest, invert, &dev_status) ;
   if( status != MRD_STATUS_SUCCESS ) {
      printf("Move failed on %s: %s\n", robot,
         mrd_strstatus(status)) ;

        /*
         * Since the cartridge didn’t move, don’t
         * reset the source, by skipping the remainder
         * of the loop.
         */
        continue ;
     }
    /*
     * Make the next source, this destination.
     */
    source = dest ;
  }
  (void)mrd_shutdown(&robot_info) ;

  return 0 ;
}

Upon successful completion, mrd_move_medium(3mrd) will return MRD_ STATUS_SUCCESS. On a failure, an MRD_STATUS value corresponding to the error will be returned. Common errors are:

Functions:

/*
 *   Example to do slot to slot moves. The command usage is:
 *
 *     mrd_position robot_name type address [ transport ]
 *
 *   Type can be one of:
 *
 *     slot, port, drive or transport
 *
 *   The optional transport argument can be a transport address
 *   number, the word "default" or an empty string.
 */
#ifndef lint
static   char   SccsId[] = "@(#)mrd_position.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <mrd_common.h>
#include <mrd_message.h>

/*
 * Given a string, resembling one of the element types,
 * return the SCSI type code for it.
 */
struct {
   int code ;
   char *string ;
} etypes[] = {
   TRANSPORT, "transport",
   SLOT, "slot",
   DRIVE, "drive",
   PORT, "port",
} ;

convert_type(char *etype)
{
   register i ;
   /*
    * For each entry in the array.
    */
   for(i = 0; i < sizeof(etypes)/sizeof(etypes[0]); i++)
      /*
       * Do a case insensitive comparison, allowing
       * abbreviations. Return as soon as a match is
       * found. Return -1 if one isn’t found.
       */
#ifdef vms
      if( strncmp(etypes[i].string, etype, strlen(etype)) == 0 )
#else
      if( strncasecmp(etypes[i].string, etype, strlen(etype)) == 0 )
#endif
         return etypes[i].code ;

return -1 ;
}

main(int argc, char *argv[])
{
   int   status ;
   int   side = 1 ;
   char   *robot ;
   char   *cart = NULL ;
   char   *element ;
   char   *transport ;
   int   type ;
   char   log_info[MRD_MAX_LOG_STRING+1] ;

   if( argc < 4 ) {
      printf("usage: %s robot type address [ transport ]\n",
         argv[0]) ;

      exit(1) ;
   }

   robot   = argv[1] ;
   type    = convert_type(argv[2]) ;
   element = argv[3] ;

   if( argc > 4 ) {
      transport = argv[4] ;

      /*
       * If "default" or a suitable abbreviation is used
       * use NULL for the transport name, to indicate that
       * the SCSI default transport should be used.
       */
#ifdef   vms
      if( strncmp("default", transport, strlen(transport)) == 0 )
#else
      if( strncasecmp("default", transport, strlen(transport)) == 0 )
#endif
         transport = NULL ;
   }
   else
      transport = "0" ;

   status = mrd_position(robot, transport, element, type,
                         side, log_info) ;
   if( status != MRD_STATUS_SUCCESS )
      printf("Position failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;
   else if ( transport == NULL )
      printf("Positioned default Transport to %s #%s\n",
         mrd_strelement(type), element) ;
   else
      printf("Positioned Transport #%s to %s #%s\n",
         mrd_strelement(type), element) ;

   return 0 ;
}

Upon successful completion, the mrd_position(3mrd) function returns the value MRD_STATUS_SUCCESS. If the mrd_position(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

mrd_position_to_element(3mrd)

The operating system interface routines use absolute SCSI element addresses, instead of zero relative address as used by the higher level functions. A zero based element address can be converted to an absolute address by adding the element base address from the robot_info_t structure.

int slot ;
robot_info_t robot_info ;

/*
 * An relative starting address.
 */
slot = 3 ;

/*
 * Becoming an absolute address.
 */
slot += robot_info.slot_start ;

/*
 *   This is an example of using mrd_position_to_element(3mrd)
 *   to perform multiple Position To Element commands. For
 *   each pair of arguments after the robot and transport
 *   address, it will position the transport to that location.
 *
 *     mrd_position_to_element robot transport type address
 *
 *   Type can be one of:
 *
 *     slot, port, drive or transport
 *
 *   The optional transport argument can be a transport address
 *   number, the word "default" or an empty string. To keep the
 *   example as simple as possible, it doesn’t try to invert the
 *   transport.
 */
#ifndef   lint
static char SccsId[] = "@(#)mrd_position_to_element.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#include <mrd_common.h>
#include <mrd_message.h>

/*
 *   Given a string, resembling one of the element types,
 *   return the SCSI type code for it.
 */
struct {
   int   code ;
   char   *string ;
} etypes[] = {
   TRANSPORT, "transport",
   SLOT, "slot",
   DRIVE, "drive",
   PORT, "port",
} ;

convert_type(char *etype)
{
   register i ;
   /*
    *   For each entry in the array.
    */
   for(i = 0; i < sizeof(etypes)/sizeof(etypes[0]); i++)
      /*
       *   Do a case insensitive comparison, allowing
       *   abbreviations. Return as soon as a match is
       *   found. Return -1 if one isn’t found.
       */
#ifdef vms
      if( strncmp(etypes[i].string, etype, strlen(etype)) == 0 )
#else
      if( strncasecmp(etypes[i].string, etype, strlen(etype)) == 0 )
#endif
        return etypes[i].code ;

   return -1 ;
}

main(int argc, char *argv[])
{
   int   el ; /* Counter */
   int   status ; /* Status from MRD calls */
   int   invert = 0 ; /* Don’t invert */
   char   *robot ; /* Robot name */
   int   type ; /* Element type */
   int   element ; /* Relative element addr */
   int   address ; /* Absolute element addr */
   int   transport ; /* Transport address */
   char   *transport_name ; /* Tranport name */
   robot_info_t   robot_info ;
   dev_status_t   dev_status ;
   char     log_info[MRD_MAX_LOG_STRING+1] ;

   if( argc < 5 ) {
     printf("usage: %s robot transport type address ...\n", argv[0]);
     exit(1) ;
   }

   /*
    *   Get the medium changer name.
    */
   robot = argv[1] ;

   /*
    *   Get the transport number. We’ll keep it as a name
    *   so we can detect the default transport. Once we
    *   know the element addresses, we can add the base
    *   base address if appropriate.
    */
   if( strcmp(argv[2], "default") == 0 )
      transport_name = NULL ;
   else
      transport_name = argv[2] ;
   /*
    *   Make sure there are pairs of arguments left. There
    *   should be an odd number.
    */
   if((argc % 2) == 0 ) {
      printf("Pairs of arguments are required.\n") ;
      exit(1) ;
   }

   /*
    *   Open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   status = mrd_startup(robot, &robot_info, log_info) ;

   if( status != MRD_STATUS_SUCCESS ) {
      fprintf(stderr, "Can’t start %s: %s\n", robot,
         mrd_strstatus(status)) ;

      exit(1) ;
   }

   if( transport_name == NULL )
      transport = 0 ;
   else
      transport = atoi(transport_name) + robot_info.transport_start;

   /*
    * Look at the element addresses in pairs.
    */
   for(el = 3; el < argc; el += 2) {
      type = convert_type(argv[el]) ;
      element = atoi(argv[el + 1]) ;

      switch( type ) {
      case SLOT:
         address = element + robot_info.slot_start ;
         break ;
      case DRIVE:
         address = element + robot_info.device_start ;
         break ;
      case TRANSPORT:
         address = element + robot_info.transport_start ;
         break ;
      case PORT:
         address = element + robot_info.port_start ;
         break ;
      default:
         printf("Unknown element type: %s %s\n", argv[el],
            argv[el + 1]) ;
         continue ;
      }

      /*
       * Audit the command.
       */
      printf("Position transport to %s #%d.\n", mrd_strelement(type),
         element) ;

      /*
       * Do the command.
       */
      status = mrd_position_to_element(&robot_info, transport,
                address, invert, &dev_status) ;
      if( status != MRD_STATUS_SUCCESS )
         printf("Position to Element failed: %s: %s.\n", robot,
            mrd_strstatus(status)) ;
   }

   (void)mrd_shutdown(&robot_info) ;

   return 0 ;
}

Upon successful completion, mrd_position_to_element(3mrd) will return MRD_STATUS_SUCCESS. On a failure, an MRD_STATUS value corresponding to the error will be returned.

Functions:

mrd_position(3mrd)

/*
 *   This is an example of using mrd_prevent_allow(3mrd) to
 *   prevent or allow media removal, where allowed. For
 *   robot name on the command line, the desired version
 *   of the command will be used according lock value.
 *   name.
 *
 *   Usage:
 *
 *   mrd_prevent_allow lock-value robot [ robot... ]
 */
#ifndef   lint
static   char   SccsId[] = "@(#)mrd_prevent_allow.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int     rc ;   /* Counter */
   int     lock ;   /* Lock value */
   int     status ;   /* return status */
   char     *robot ;   /* Robot to open */
   robot_info_t   robot_info ;   /* Robot data */
   dev_status_t   dev_status ;   /* Device status */
   char     log_info[MRD_MAX_LOG_STRING+1] ;
   /*
    *   Check that there are enough arguments.
    */
   if( argc < 3 ) {
      printf("usage: %s lock-value robot [ robot... ]\n", argv[0]) ;
      exit(1) ;
   }
   else
      lock = atoi(argv[1]) ;

   /*
    *   Initialize the channel field of the robot_info, so
    *   mrd_startup(3mrd) will actually open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   for(rc = 2; rc < argc; rc++) {
   /*
    *   The robot for this command.
    */
      robot = argv[rc] ;

      status = mrd_startup(robot, &robot_info, log_info) ;

      if( status != MRD_STATUS_SUCCESS ) {
         printf("Startup failed on %s: %s.\n", robot,
            mrd_strstatus(status)) ;

         continue ;
      }

      printf("Lock value %d on %s.\n", lock, robot) ;

      status = mrd_prevent_allow(&robot_info, lock, &dev_status) ;

      if( status != MRD_STATUS_SUCCESS )
         printf("Prevent/Allow failed on %s: %s.\n", robot,
            mrd_strstatus(status)) ;

      (void)mrd_shutdown(&robot_info) ;
   }

   return 0 ;
}

Upon successful completion, mrd_prevent_allow(3mrd) will return MRD_STATUS_SUCCESS. On a failure, one of the following status values will be returned.

Functions:

mrd_lock(3mrd)

/*
 *   This is an example of using mrd_move_medium directly to move
 *   a cartridge from one slot to another. To simplify the
 *   example, it only supports slot to slot moves, but it shows
 *   how the absolute element addresses are calcuated. For each
 *   additional destination address given, the previous (successful)
 *   destination address is used as the source.
 *
 *   Usage:
 *
 *     mrd_ready robot port [ port... ]
 */
#ifndef lint
static char SccsId[] = "@(#)mrd_ready.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   pc ;   /* counter */
   int   port ;   /* Port number */
   int   address ;   /* Port address */
   int   status ;   /* return status */
   char   *robot ;   /* Robot to open */
   robot_info_t   robot_info ;   /* Robot data */
   dev_status_t   dev_status ;   /* Device status */
   char   log_info[MRD_MAX_LOG_STRING+1] ;

   /*
    *   Check that there are enough arguments.
    */
   if( argc < 3 ) {
      printf("usage: %s robot port [ port... ]\n", argv[0]) ;
      exit(1) ;
   }
   else
      robot = argv[1] ;

   /*
    *   Initialize the channel field of the robot_info, so
    *   mrd_startup(3mrd) will actually open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   status = mrd_startup(robot, &robot_info, log_info) ;

   if( status != MRD_STATUS_SUCCESS ) {
      printf("Startup failed on %s: %s.\n", robot,
         mrd_strstatus(status)) ;

      exit(1) ;
   }

   /*
    *   For each destination address on the command line,
    *   move the the cartridge in the source to the
    *   destination. After each (successful) move, replace
    *   the previous source with this destination.
    */
   for(pc = 2; pc < argc; pc++) {
      /*
       *   Get the port number.
       */
      port = atoi(argv[pc]) ;

   /*
    *   Now the absolute address.
    */
   address = port + robot_info.port_start ;
   /*
    *   Print an audit as we go. Since we know these
    *   are slots, convert back to relative addresses
    *   for the audit.
    */
   printf("Ready Inport #%d of %s\n", port, robot) ;

   status = mrd_ready(&robot_info, address, &dev_status) ;

   if( status != MRD_STATUS_SUCCESS ) {
      printf("Ready Inport failed on %s: %s.\n", robot,
         mrd_strstatus(status)) ;
      /*
       *   Since the cartridge didn’t move, don’t
       *   reset the source, by skipping the remainder
       *   of the loop.
       */
      continue ;
     }
   }
   (void)mrd_shutdown(&robot_info) ;

   return 0 ;
}

Functions:

mrd_ready_inport(3mrd)

/*
 *   Send a Ready Inport command to the robot. This is specific
 *   the TL82X family and causes the Inport door to be enabled
 *   for one minute (the period the light is on). A future
 *   version of firmware may allow enableing the button to be
 *   on all the time, making this command obsolete. The command
 *   usage is:
 *
 *     mrd_ready_inport robot
 */

#ifndef   lint
static   char   SccsId[] = "@(#)mrd_ready_inport.c 1.2 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>

main(int argc, char *argv[])
{
   int   status ;   /* status from mrd_ready_inport(3mrd) */
   char   *robot ;   /* Robot for command */
   char   log_info[MRD_MAX_LOG_STRING+1] ;   /* error text */

   /*
    * Only one argument; the robot name.
    */
   if( argc == 1 ) {
      printf("usage: %s robot\n", argv[0]) ;
      exit(1) ;
   }
   else
      robot = argv[1] ;

   /*
    *   While the interface of Ready Inport allows the specification
    *   of any port address, the Inport of the TL820 is always "0",
    *   and this command is very robot specific.
    */
   status = mrd_ready_inport(robot, "0", log_info) ;

   if( status != MRD_STATUS_SUCCESS )
      printf("Ready Inport failed: %s: %s.\n", mrd_strstatus(status),
         log_info[0] ? log_info : "none") ;

   return 0 ;
}

Upon successful completion, the mrd_ready_inport(3mrd) function returns the value MRD_STATUS_SUCCESS. If mrd_ready_inport(3mrd) fails the returned status value may be set to one of the following values. Other values that correspond to specific SCSI errors may also be possible, but these are the most likely.

Functions:

The operating system interface routines use absolute SCSI element addresses, instead of zero relative address as used by the higher level functions. A zero based element address can be converted to an absolute address by adding the element base address from the robot_info_t structure.

int slot ;
robot_info_t robot_info ;

/*
 * An relative starting address.
 */
slot = 3 ;

/*
 * Becoming an absolute address.
 */
slot += robot_info.slot_start ;

/*
 * This is an example of using mrd_read_element_status(3mrd).
 *
 * Due to the complexity of the SCSI Read Element Status data
 * all this example will do is format the headers found in the
 * data. It won’t try to format the element data. It also
 * calls mrd_read_element_status(3mrd) twice, once to determine
 * the needed data size for the remaining data and again to get
 * the actual data.
 *
 *   Usage:
 *
 * mrd_read_element_status robot type start count
 *
 * If an unrecognized element type is used, the routine will use
 * a type of zero, which is allowed by the SCSI-2 specification.
 */

#ifndef lint
static char SccsId[] = "@(#)mrd_read_element_status.c 1.3
                        (mrd-example) 3/5/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>

#include <mrd_common.h>
#include <mrd_message.h>

/*
 * The SCSI specification says that a request size of 8
 * bytes will have the underlying device only return a
 * header indicating the number of bytes needed for the
 * command.
 */
#define SCSI_RES_MIN (8)

/*
 * Given a string, resembling one of the element types,
 * return the SCSI type code for it.
 */
struct {
 int code ;
 char *string ;
} etypes[] = {
TRANSPORT,   "transport",
 SLOT,   "slot",
 DRIVE,   "drive",
 PORT,   "port",
} ;

convert_type(char *etype)
{
 register i ;

 /*
  * For each entry in the array.
  */
 for(i = 0; i < sizeof(etypes)/sizeof(etypes[0]); i++)
  /*
   * Do a case insensitive comparison, allowing
   * abbreviations. Return as soon as a match is
   * found. Return -1 if one isn’t found.
   */
#ifdef vms
  if( strncmp(etypes[i].string, etype, strlen(etype)) == 0 )
#else
  if( strncasecmp(etypes[i].string, etype, strlen(etype)) == 0 )
#endif
   return etypes[i].code ;
 return 0 ;
}

/*
 * When an 8 byte Read Element Status command is handed
 * to a compliant medium changer, it is supposed to fill
 * enough of the header section to say how much data is
 * needed for the full command. We that here, if we get
 * a reasonable value, allocate sufficient space for the
 * real command and return the pointer to it. If there
 * is an error or command returns a zero byte report
 * return NULL.
 */
unsigned char *
res_size(robot_info_t *robot_info, int type, int start, int count, size_t *bytes)
{
 unsigned char data[SCSI_RES_MIN] ; /* minimum data */
 int status ; /* command status */
 dev_status_t dev_status ; /* In case of error */
 unsigned char *report ; /* Data space */

 /*
  * Read Element Status commands rarely fail, they just
  * succeed, but return no data. Clear all the fields
  * so we’ll have an easier time seeing if any data was
  * returned.
  */
 memset((void *)data, 0, SCSI_RES_MIN) ;

 status = mrd_read_element_status(robot_info, type, start, count,
   data, SCSI_RES_MIN, &dev_status) ;
 /*
  * But sometimes they do fail.
  */
 if( status != MRD_STATUS_SUCCESS ) {
  printf("Size Read Element Status failed on %s: %s.\n",
   robot_info->robot_name, mrd_strstatus(status)) ;

 return NULL ;
 }

 /*
  * Calculate the report size.
  */
 *bytes = (data[RES_REPORT_MSB] << 16) | (data[RES_REPORT_ISB] << 8) |
   data[RES_REPORT_LSB] ;
 /*
  * The report size doesn’t include the 8 bytes needed for
  * the first headers.
  */
 *bytes += RES_DATA_HEADER ;

 if( *bytes == 0 ) {
  printf("The report size is zero on %s.\n",
   robot_info->robot_name) ;

 return NULL ;
 }

 if((report = (unsigned char *)malloc(*bytes)) == NULL )
  printf("Can’t allocate %ld bytes for %s: %s.\n", *bytes,
   robot_info->robot_name, strerror(errno)) ;

 return report ;
}
/*
 * Print out the Read Element Status data headers. There
 * is an 8 byte data header, that describes the remaining
 * data, which is zero or more Status Pages, one for each
 * element type.
 *
 * Each Element Status Page consists of an 8 byte header
 * for the element type described by that page and then
 * element descriptors.
 */
print_res_data(robot_info_t *robot_info, unsigned char *dp)
{
 int first ; /* First element reported */
 int elements ; /* Number of elements reported */
 int report ; /* Bytes in the total report */
 int descriptor ; /* Each element descriptor size */
 int bytes ; /* The per-element report size */

 /*
  * The first two bytes of the overall header is the
  * first element reported.
  */
 first = (dp[RES_FIRST_MSB] << 8) | dp[RES_FIRST_LSB] ;

 /*
  * The next two bytes are the number of elements in
  * the report.
  */
elements = (dp[RES_COUNT_MSB] << 8) | dp[RES_COUNT_LSB] ;
/*
 * Three of the remaining bytes are the total report size.
 */
report = (dp[RES_REPORT_MSB] << 16) | (dp[RES_REPORT_ISB] << 8) |
   dp[RES_REPORT_LSB] ;

printf("RES Data Header:\n") ;
printf("   First Element Address:  %d\n",  first) ;
printf("   Number of Elements:     %d\n",  elements) ;
printf("   Byte Count of Report:   %d\n",  report) ;

/*
 * As long as bytes of report remaining, print each
 * element type header.
 *
* Here we play a curious pointer game. The RES_
* constants defined in mrd_common.h for the element
* header assume a single element type with offsets
* from the beginning of the data. But real Read
* Element Status Data can have multiple element
* types in it. For successive element type we’ll
* add the per-element report size to the address
* of the base data. This should put the per-element
* header at the right relative place.
*/
report -= RES_DATA_HEADER ;

while( report > 0 ) {
 /*
  * Calculate the descriptor size.
  */
 descriptor = (dp[RES_DESC_MSB] << 8) | dp[RES_DESC_LSB] ;

 /*
  * And the per element report.
  */
 bytes = (dp[RES_BYTES_MSB] << 16) | (dp[RES_BYTES_ISB] << 8) |
   dp[RES_BYTES_LSB] ;

 printf("   Descriptor Header:\n") ;
 printf("     Element Type: %s\n",
  mrd_strelement(dp[RES_TYPE])) ;

 printf("     Primary Volume Tag: %x\n",
  dp[RES_TAGS] & ELEMENT_PVOLTAG) ;

 printf("     Alternate Volume Tag: %x\n",
  dp[RES_TAGS] & ELEMENT_AVOLTAG) ;

 printf("     Descriptor Length: %d\n", descriptor) ;
 printf("     Descriptor Report: %d", bytes) ;

 /*
  * Include the number of elements of this type.
  */
 if( descriptor )
  printf(" (%d)\n", bytes / descriptor) ;
 else
  putchar(’\n’) ;

 /*
  * Protection against the odd insane loader.
  */
 if( bytes == 0 )
  break ;
  /*
   * Go to the next header. Formatting the element
   * data is left as an exercise to the reader.
   */
  dp += (bytes + RES_DATA_PAGE) ;

  /*
   * Lose some bytes...
   */
  report -= (bytes + RES_DATA_PAGE) ;
 }

}

main(int argc, char *argv[])
{
 int  status ;  /* return status */
 int  type ;  /* Element type */
 int  start ;  /* First element */
 int  count ;  /* Number of elements */
 size_t  bytes ;  /* Bytes of data */
 char  *robot ;  /* Robot to open */
 unsigned char *data ;  /* Element Status data */
 robot_info_t robot_info ;  /* Robot data */
 dev_status_t dev_status ; /* Device status */
 char log_info[MRD_MAX_LOG_STRING+1] ;

 /*
  * Check that there are enough arguments.
  */
 if( argc < 5 ) {
  printf("usage: %s robot type start count\n", argv[0]) ;
  exit(1) ;
 }
 else {
  robot = argv[1] ;
  type = convert_type(argv[2]) ;
  start = atoi(argv[3]) ;
  count = atoi(argv[4]) ;
 }

 /*
  * Initialize the channel field of the robot_info, so
  * mrd_startup(3mrd) will actually open the robot.
  */
 robot_info.channel = BAD_CHANNEL ;

 status = mrd_startup(robot, &robot_info, log_info) ;

 if( status != MRD_STATUS_SUCCESS ) {
  printf("Startup failed: %s: %s.\n", mrd_strstatus(status),
   log_info[0] ? log_info : "none") ;

  exit(1) ;
 }

 if( type == 0 )
  printf("Data size needed for all elements %d - %d...",
   start, start + count) ;
 else
  printf("Data size needed for %s %d - %d...",
   mrd_strelement(type),
   start, start + count) ;

 fflush(stdout) ;
 switch( type ) {
 case SLOT:
  start += robot_info.slot_start ;
  break ;
 case PORT:
  start += robot_info.port_start ;
  break ;
 case TRANSPORT:
  start += robot_info.transport_start ;
  break ;
 case DRIVE:
  start += robot_info.device_start ;
  break ;
 }

 /*
  * Allocate sufficient space for the command. This
  * function prints its own error messages, so we can
  * just exit.
  */
 data = res_size(&robot_info, type, start, count, &bytes) ;

 if( data == NULL )
  exit(1) ;

 printf("%d bytes.\n", bytes) ;

 /*
  * Now do the full Read Element Status command.
  */
 status = mrd_read_element_status(&robot_info, type, start, count,
   data, bytes, &dev_status) ;

 if( status != MRD_STATUS_SUCCESS ) {
  printf("Read Element Status failed on %s: %s.\n", robot,
   mrd_strstatus(status)) ;

  free(data) ;

  exit(1) ;
 }

 /*
  * We appear to have valid Read Element Status data. Print
  * out the results.
  */
 print_res_data(&robot_info, data) ;

 (void)mrd_shutdown(&robot_info) ;

 return 0 ;
}

Upon successful completion, mrd_read_element_status(3mrd) will return MRD_STATUS_SUCCESS. On a failure, one of the following status values will be returned.

Experience has shown that Read Element Status rarely fails on the supported SCSI-2 medium changers. When the command is unable to obtain the requested data it simply arranges for the element and byte counts of the report to contain no data.

Functions:

mrd_show(3mrd)

/*
 *   This is an example of using mrd_request_sense(3mrd)
 *   to see what state a medium changer is in. The MRD
 *   implementation of Request Sense only collects the
 *   Sense Key, Additional Sense Code and Additional Sense
 *   Code Qualifier.
 *
 *   Usage:
 *
 *      mrd_request_sense robot [ more-robots... ]
 */

#ifndef   lint
static   char SccsId[] = "@(#)mrd_request_sense.c 1.1 4/16/97" ;
#endif

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <mrd_common.h>
#include <mrd_message.h>

char  *device_sense = "Sense data for %s: %s (%d,0x%x,0x%x).\n" ;
char  *sense_failed = "Request Sense failed on %s: %s.\n" ;

main(int argc, char *argv[])
{
   int     rc ;    /* counter */
   int     status ;    /* return status */
   char     *robot ;    /* Robot to open */
   robot_info_t robot_info ;   /* Robot data */
   dev_status_t dev_status ;   /* Device status */
   char log_info[MRD_MAX_LOG_STRING+1] ;

   /*
    * Check that there are enough arguments.
    */
   if( argc < 2 ) {
      printf("usage: %s robot [ robot... ]\n", argv[0]) ;
      exit(1) ;
   }

   /*
    *   Initialize the channel field of the robot_info, so
    *   mrd_startup(3mrd) will actually open the robot.
    */
   robot_info.channel = BAD_CHANNEL ;

   for(rc = 1; rc < argc; rc++) {
      /*
       * The robot for this command.
       */
      robot = argv[rc] ;

      status = mrd_startup(robot, &robot_info, log_info) ;

      if( status != MRD_STATUS_SUCCESS ) {
         printf("Startup failed on %s: %s.\n", robot,
            mrd_strstatus(status)) ;
         continue ;
      }

      memset((void *)&dev_status, 0, sizeof(dev_status)) ;

      /*
       * mrd_request_sense(3mrd) will never return
       * MRD_STATUS_SUCCESS. If no Request Sense data
       * is available, it will return MRD_STATUS_NO_SENSE.
       */
      status = mrd_request_sense(&robot_info, &dev_status,
            MRD_CHECK_SENSE) ;

      /*
       * Print the Key/ASC/ASCQ data for device errors.
       */
      if( dev_status.valid )
         printf(device_sense, robot, mrd_strstatus(status),
            dev_status.key, dev_status.asc,
            dev_status.ascq) ;
      /*
       * Just print the MRD error.
       */
      else
         printf(sense_failed, robot, mrd_strstatus(status)) ;

      (void)mrd_shutdown(&robot_info) ;
   }

   return 0 ;
}

The routine mrd_request_sense(3mrd) never returns MRD_STATUS_SUCCESS. If the os_status isn't the operating system specific code that forces a Reqeust Sense command or MRD_CHECK_SENSE, mrd_map_os_error(3mrd), is used to map the os_status to an MRD status code. Otherwise, a Request Sense (or equivalent) is performed and the result mapped to an MRD status code with mrd_scsi_decode(3mrd).