mrd_show - Obtain information from a media robot
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_show(
const char *robot_name,
robot_info_t *robot_info,
int element_type,
const char *element_name,
int element_count,
element_info_t *element_info,
char *log_info) ;
1 – Parameters
o robot_name - The name of the robot device to be opened. On
Digital UNIX, if the leading character of the name is not a
slash (/), /dev/ will be prepended to the name.
o robot_info - This is the address of a robot_info_t structure
initialized using mrd_startup(3mrd) or mrd_show(3mrd). This
data structure contains the element starting address and
counts for each type of element, which are needed to map an
absolute element to the correct zero relative address and
type.
o element_type - The type of robot element on which the
operation takes place. If an element type of zero (0) is used,
all elements will be searched starting at element 0 of each
type and searching all the elements of that type on the robot.
The order of this search is Slot, Drive, Transport and finally
Ports.
o element_name - A string used to specify the name of the first
element about which to obtain information. While SCSI devices
use integer numbers for element addresses, DSA robots use
character strings. This allows the same interface to be used
for both types, where supported.
o element_count - A volume tag search in a large library
can take a long time. Some applications (a graphic user
interface for example) may want to break up a large search
into smaller, quicker sub-searches. When a specific element_
type is specified only a range specified by the element_name
and element_count will be searched. This argument is ignored
when the element_type is zero (0).
o element_info - The array of element_info_t structures that is
filled in with information on the type and number of elements
requested with element_type and element_count. The information
includes volume tag (if available), state, port type (if PORT
information is requested), status, and when available a copy
of the Read Element Status data for the element.
o log_info - This is a character array that should be at least
MRD_MAX_LOG_STRING in length. If this function fails as the
result of a SCSI error, this will be filled with the formatted
request sense data. If this function fails as the result
of an operating system error, the operating system message
particular to the error will be copied into the array.
2 – Description
The mrd_show(3mrd) function can be used to obtain information
about specific element types of a supported Medium-Changer.
Medium-Changer element types that mrd_show(3mrd) can retrieve
information about include PORT, DRIVE, SLOT and TRANSPORT. If
a element_type of ROBOT is specified, the mrd_show(3mrd) is
equivalent to calling mrd_startup(3mrd) - that is, robot_info
is filled in.
The robot_info_t data structure is described in mrd_
startup(3mrd).
The element_name parameter specifies the first element of the
type element_type about which to obtain information. The element_
count parameter specifies the number of elements of type element_
type about which information is to be obtained.
2.1 – Element Info
The element_info_t data structure is defined in the include file
<mrd_common.h>. The fields of this data structure are described
below:
o name - The name field holds the volume tag of the media if
applicable.
o state - The state field can have one of the following values:
ELEMENT_FULL,
ELELMENT_EMPTY, or
ELEMENT_EXCEPT.
o port_type - If the element_type parameter specifies PORT, the
port_type field will have one of the following values:
IN_OUT_PORT,
INPORT,
OUTPORT.
o status - The status field can have one of the following
values:
MRD_STATUS_SLOT_INVALID,
MRD_STATUS_DEVICE_INVALID,
MRD_STATUS_TRANSPORT_INVALID,
MRD_STATUS_PORT_INVALID, or
MRD_STATUS_SUCCESS.
o flags - Use the ELEMENT_VALID mask on the flags field to
indicate whether or not the full Read Element Status data
is valid. The ELEMENT_PVOLTAG and ELEMENT_AVOLTAG indicate
whether the primary or alternate volume tags of the Read
Element Status data are valid.
o element_addr - This is the address of the element, unadjusted
for the starting address. The routine mrd_map_element(3mrd)
can be used to convert an absolute element address to a
relative address and type. This field will be set to -1 when
the information is not valid.
o source_addr - On most SCSI-2 medium-changers, this is the
address where a cartridge resided before being moved to its
current location. The routine mrd_map_element(3mrd) can be
used to convert an absolute element address to a relative
address and type. This field will be set to -1 when the
information is not valid. On some SCSI-2 medium-changers (the
DLT family loaders) this will be the element address of the
slot itself.
o data - This a copy of the SCSI-2 Read Element Status data
when the ELEMENT_VALID bit is set in the flags field. A byte-
order neutral declaration of this data structure is included
in the <mrd_common.h> include file as the mrd_reades_t data
structure.
3 – Example
/*
* Example to do mrd_show(3mrd) on the first element of each type.
* The usage of this command is:
*
* mrd_show robot
*
* This examples show keeping the robot open across multiple
* calls to mrd_show(3mrd). In one happens to close it, the
* channel will be reset the BAD_CHANNEL and the next one will
* open it again. On some robot subsystems, opening the robot
* is fairly time consuming and if multiple "shows" are needed
* the time savings can be signficiant.
*
* The subsystems where this is most noticable are HSJ and HSD
* connected robots, which aren't supported on Digital UNIX.
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_show.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[])
{
robot_info_t robot_info ; /* keep the robot open */
element_info_t element ; /* place to put element data */
int el ; /* type index */
int status ; /* status from mrd_show(3mrd) */
char *robot ; /* Robot to use */
char *content ; /* pointer to a content string */
char log_info[MRD_MAX_LOG_STRING+1] ; /* error text */
/*
* Only one argument is used; the robot name.
*/
if( argc == 1 ) {
printf("usage: %s robot\n", argv[0]) ;
exit(1) ;
}
else
robot = argv[1] ;
/*
* The channel number must be set to BAD_CHANNEL before
* mrd_startup or mrd_show is called, otherwise it will
* assume the robot is already open and not try to open
* it again.
*/
robot_info.channel = BAD_CHANNEL ;
/*
* In this case we want to open the robot once, and then
* call mrd_show(3mrd) in turn for each type of element.
* If there is an error and it happens to close the robot,
* the channel will be reset and the robot opened again on
* the next call.
*/
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) ;
}
/*
* We rely on the fact that the element numbers are
* are 1 through 4.
*/
for(el = 1; el <= 4; el++) {
log_info[0] = '\0' ;
status = mrd_show(robot, &robot_info, el, "0", 1,
&element, log_info) ;
if( status != MRD_STATUS_SUCCESS ) {
printf("Can't show %s 0: %s (%s)\n",
mrd_strelement(el), mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
continue ;
}
if( element.status != MRD_STATUS_SUCCESS ) {
printf("Can't show %s 0: %s\n", mrd_strelement(el),
mrd_strstatus(element.status)) ;
continue ;
}
if( element.name[0] )
content = element.name ;
else if( element.state & ELEMENT_FULL )
content = "Full" ;
else if( element.state & ELEMENT_EXCEPT )
content = "Exception" ;
else
content = "Empty" ;
printf("%-9s 0: %s\n", mrd_strelement(el), content) ;
}
/*
* Close it when done.
*/
(void)mrd_shutdown(&robot_info) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_show(3mrd) function returns
the value MRD_STATUS_SUCCESS. If mrd_show(3mrd) fails, the
returned status value will 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.
4.1 – MRD_STATUS_PARAM
This error is returned if the robot_name, log_info, element_name,
element_info, or robot_info arguments are NULL pointers.
4.2 – MRD_STATUS_RES_FAILED
The SCSI command Read Element Status failed.
4.3 – MRD_STATUS_ROBOT_ILLEGAL_REQUEST
This is error is returned when the element_type is not one of
SLOT, PORT, DRIVE or TRANSPORT. This last case should return MRD_
STATUS_INVALID_TYPE instead. 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.4 – MRD_STATUS_SLOT_INVALID
This error is returned when the element address for a slot is
less than zero or greater than the number of slots.
4.5 – MRD_STATUS_TRANSPORT_INVALID
This error is returned when the element address for a transport
is less than zero or greater than the number of transports.
4.6 – MRD_STATUS_NO_ELEMENTS
This error occurs in mrd_show(3mrd), mrd_find_cartridge(3mrd) and
mrd_home(3mrd) when the medium-changer has no elements within the
range and type specified by the arguments.
4.7 – MRD_STATUS_PORT_INVALID
This error is returned when the element address for a port is
less than zero or greater than the number of ports.
4.8 – MRD_STATUS_ROBOT_COMM_ERROR
This error code is used when an OpenVMS system service, such as
$ASSIGN or $QIO, fails with a status of SS$_DRVERR. Generally
SS$_DRVERR indicates a failure in the underlying device and the
MRD can get the detailed device failure and return the correct
MRD status code instead.
This error is also returned when a SCSI Test Unit Ready command
fails. The cause of the error can be determined by called mrd_
request_sense(3mrd). 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.9 – 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.10 – 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.11 – MRD_STATUS_INSFMEM
The mrd_show(3mrd) and mrd_find_cartridge(3mrd) functions
allocate virtual memory using malloc(3) to store temporary
element data. If the attempt to allocate the memory fails, these
routines will return this error.
5 – Related Functions
Functions:
o mrd_shutdown(3mrd)
o mrd_startup(3mrd)
o mrd_map_element(3mrd)