mrd_startup - Open a medium-changer robot
mrd_shutdown - Close a medium-changer robot
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_startup(
const char *robot_name,
robot_info_t *robot_info,
char *log_info) ;
void mrd_shutdown(
robot_info_t *robot_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 the robot_info_t structure
when mrd_startup is called. 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 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_startup(3mrd) function can be used to obtain information
about a supported Medium-Changer. Because the startup time on
some robots (HSJ connected SCSI robots) can be relatively long,
this routine can also be used to hold open the robot while mrd_
show(3mrd) routines are used to collect information about the
different robot elements.
The mrd_shutdown(3mrd) routine should be used to close a robot
before other MRD routines are called. With the exception of
mrd_show(3mrd) the MRD common routines call mrd_startup(3mrd)
themselves and can't make use of robot_info_t filled in by mrd_
startup(3mrd).
Robot Information
The robot_info_t data structure is defined in the include file
<mrd_common.h>. The fields of this data structure are described
below:
o channel - This is the file descriptor, channel number or other
operating system specific handle assigned to the process for
the robot, when mrd_startup(3mrd) is successful. It should
not be used directly and should only be closed through mrd_
shutdown(3mrd). When mrd_show(3mrd) is provided a robot_info_t
where the channel is not BAD_CHANNEL, it will assume the robot
is open and try to use that handle.
o robot_name - This is set to the address of the robot_name
argument provided to mrd_startup(3mrd).
o robot_type - MRD attempts to identify a robot using the SCSI
inquiry data obtained during the startup. This is a value
to indicate the family or type of medium-changer. Recognized
types are:
DLT_ROBOT TZ857, TZ867, TZ875, TZ877, TZ885, TZ887
RDAT_ROBOT TLZ6L, TLZ7L, TLZ9L
TL820_ROBOT TL820, TL822, TL826
TL810_ROBOT TL810, TL812
TL800_ROBOT TL891
OVERLAND_ROBOT TKZ6x
RW5XX_ROBOT RW500
UNKNOWN_ROBOT A type not recognized
o arch_type - This indicates the I/O architecture used to
communicate with the medium-changer. OpenVMS supports SCSI
(ARCH_SCSI) and DSA (ARCH_DSA) connected medium-changers. HSJ
and HSD connected robots are considered SCSI robots. Digital
UNIX and Windows NT only support SCSI connected robots.
o vision_present - This flag indicates that the robot supports
a vision system that can be used to read volume tags. It is
set in the start-up and should not be changed. Most SCSI
robots will reject commands asking for volume tags when the
medium-changer doesn't support them.
o robot_device_type - This field is only used by the OpenVMS
implementation of MRD to indicate the method the host uses
to communicate with the medium-changer. This value is used
internally by the OpenVMS MRD code to select the appropriate
communcation path.
o ptm_addr and ptm_type The TL820 family supports a pass-through
mechanism (PTM) for moving cartridges from the inport to
the bar-code reader station or from there to the outport. In
multi-tower configurations the pass-through moves cartridges
from one tower to another. The MRD uses the PTM to perform
bar-code verification. Early versions of the TL820 family
firmware present the PTM as a Import/Export element, while
later versions may present it as a Transport. These fields are
used to indicate the address and type.
o maxecnt - The OpenVMS drivers used to communicate with medium-
changers support a limited I/O size that restricts the amount
of data that can be transferred by a Read Element Status
command. This field is used by the OpenVMS implementation
of MRD to know where large transfers must be broken up by the
software.
o element_desc - In addition to knowing the maximum number of
elements that may be read in a single Read Element Status
command, the element descriptor size is also needed to
correctly break-up command. This field stores the element
descriptor size on all implementations of the MRD.
The following fields are filled in from Element Address
Assignment Page obtained via the SCSI Mode Sense command. When
the robot is not a SCSI connect device, a suitable lie is filled
by the operating system specific code supporting that type of
robot.
o slot_count - This is the number of storage elements (slots) in
the medium-changer. Some robots (TLZ7L) will change the number
of slots presented depending on the type of magazine used. To
detect changes in the size of the carrier, mrd_startup(3mrd)
must be called and field checked for a change of value. When
no magazine is in the drive, it may report 0 slots.
o slot_start - This is the element address of the first storage
element. It is used by MRD to convert zero-relative element
addresses to the actual element address used by the medium-
changer.
o device_count - This is the number of data transfer elements
(drives) in the medium-changer. Like storage elements it may
be subject to change after a robot has been started.
o device_start - This is the element address of the first data
transfer element. It is used by MRD to convert zero-relative
element addresses to the actual element address used by the
medium-changer.
o port_count - This is the number of import/export elements
(ports) in the medium-changer. Like storage elements it may be
subject to change after a robot has been started.
o port_start - This is the element address of the first import
/export element. It is used by MRD to convert zero-relative
element addresses to the actual element address used by the
medium-changer.
o transport_count - This is the number of medium transport
elements (transports) in the medium-changer. Like storage
elements it may be subject to change after a robot has been
started.
o transport_start - This is the element address of the first
medium transport element. it is used by MRD to convert zero-
relative element addresses to the actual element address used
by the medium-changer.
o inport_count and outport_count - MRD V1.2 and earlier attempts
to identify ports according to whether they are used for
import-only, export-only or both. This is an artifact from
the time that the TL820 was the only supported medium- changer
with ports. Even though the TL810 has four ports these fields
will report it having four inports and four outports.
o inport_start and outport_start - MRD V1.2 and earlier assumes
that the arrangement of ports in the address space of the
medium-changer has all the inports together and all the
outports together. However, the two groups may be separated.
No guarantee is made whether the addressees of the inports
come before or after the outports. When the starting address
of both types of ports the same value, it can be safely
assumed that all the ports within the particular port count
are both inport and outport elements.
The following fields are obtained as the result of a SCSI Inquiry
Command. When the robot isn't a SCSI connected device, a suitable
lie is filled in by the operating system specific code supporting
that type of robot.
o scsi_info - These are the first eight (8) bytes of the SCSI
Inquiry data for the robot. MRD doesn't make use of this
information, but it is available if the calling application
wants to use it. These bytes will be zero on non-SCSI devices.
o inquiry - This is the VendorID, ProductID and
ProductRevisionLevel fields of the SCSI Inquiry data. They
are collected as a single NULL terminated string. The data is
edited to replace any non-printable character with a space.
These fields are not currently used:
o bus
o target
o lun
o devcap
o transport_geometry
3 – Example
/*
* Example of using mrd_startup(3mrd) and mrd_shutdown(3mrd). This
* just opens the robot and prints the element counts and Inquiry
* string. The command usage is:
*
* mrd_startup robot
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_startup.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 ; /* Place to put robot data */
int status ; /* status from mrd_startup(3mrd) */
char *robot ; /* robot name */
char log_info[MRD_MAX_LOG_STRING+1] ; /* error text */
/*
* Only one required argument; 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 is called, otherwise it will assume the
* robot is already open and not try to open it again.
*/
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") ;
else {
printf("Inquiry: %s\n", robot_info.inquiry) ;
printf(" Transports: %d\n", robot_info.transport_count) ;
printf(" Slots: %d\n", robot_info.slot_count) ;
printf(" Ports: %d\n", robot_info.port_count) ;
printf(" Drives: %d\n", robot_info.device_count) ;
}
(void)mrd_shutdown(&robot_info) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_startup(3mrd) and mrd_
shutdown(3mrd) functions return the value MRD_STATUS_SUCCESS.
If the mrd_startup(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, or robot_info
arguments are NULL pointers.
4.2 – MRD_STATUS_SCSI_CHECK
The SCSI Check Condition error should never occur, since it
indicates that it safe to use a Request Sense command and you are
likely to get a different error.
4.3 – MRD_STATUS_SCSI_CONDMET
The SCSI Condition Met status indicates a SCSI command completed
with the status "Condition Met".
4.4 – MRD_STATUS_SCSI_BUSY
The SCSI Device is Busy status code indicates a SCSI command
completed with the status "Busy". Some TZ87x media changers are
known to cause this condition.
4.5 – MRD_STATUS_SCSI_INTER
The SCSI Intermediate Command Completed status code indicates a
SCSI command completed with the status "Intermediate".
4.6 – MRD_STATUS_SCSI_INTER_CONDMET
The SCSI Intermediate-Condition Met status code indicates a SCSI
command completed.
4.7 – MRD_STATUS_SCSI_RESCON
The SCSI Reservation Conflict status code indicates a SCSI
command completed with the status "Reservation Conflict".
4.8 – MRD_STATUS_SCSI_TERM
The SCSI Command Terminated status code indicates a SCSI command
completed with the status "Terminated".
4.9 – MRD_STATUS_SCSI_QUEUE
The SCSI Queue Full status code indicates a SCSI command
completed with the status "Queue Full".
4.10 – MRD_STATUS_SCSI_RESERVED
The SCSI Status Code Reserved return indicates a SCSI command
completed with a status that wasn't listed in Chapter 7 of the
SCSI-2 specification and is "Reserved".
4.11 – 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.12 – 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.13 – MRD_STATUS_NO_SUCH_DEVICE
This error is returned when a regular file or robot was specified
without the ":BnTnLn" string.
4.14 – MRD_STATUS_PAGE_CODE
This error occurs in mrd_startup(3mrd) when a SCSI Mode Sense
command fails to return the expected data. It uses the SCSI
Element Address Assignment mode page to fill in the element count
and base address fields of the robot_info_t structure. If the
data returned by the medium changer does not have the expected
page code, this error is returned. This error has been seen when
medium changers are connected to HS family array controllers
running V2.7 firmware.
4.15 – MRD_STATUS_INIT_REQUIRED
LUN not ready, Initializing command required.
This is for the ASC/ASC code of 4/2. It occurs
when commands are sent to a TL810 family library that has
auto-inventory on power-up turned off.
4.16 – MRD_STATUS_DIAG_FAILED
Diagnostic failure, component in ASCQ. This is the
entire class of error codes with the ASC value set to 0x40.
4.17 – MRD_STATUS_IDE
Initiator detected error message received. This error
code occurs when the ASC/ASCQ code is 0x48/0.
4.18 – MRD_STATUS_OPERATOR
Operator request. This error code occurs when the ASC
code is 0x5A and the ASCQ code is 0 or 1.
4.19 – MRD_STATUS_LOG_ERROR
Device log error. This error code occurs when the ASC
code is 0x5B and the ASCQ code is 0, 1, 2 or 3.
4.20 – MRD_STATUS_ELOG_OVERFLOW
Error log overflow. This error code occurs when the ASC
code is 0xA and the ASCQ code is 0.
4.21 – MRD_STATUS_SYNC_XFER_ERROR
Synchronous data transfer error. This error code occurs
when the ASC code is 0x1B and the ASCQ code is 0.
5 – Related Functions
Functions:
o mrd_move(3mrd)
o mrd_load(3mrd)
o mrd_unload(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)
o mrd_show(3mrd)
o mrd_ready(3mrd)
o mrd_position(3mrd)
o mrd_initialize(3mrd)
o mrd_home(3mrd)
o mrd_find_cartridge(3mrd)
o mrd_error_decode(3mrd)
o mrd_strstatus(3mrd)
o mrd_map_element(3mrd)
o mrd_lock(3mrd)
o mrd_unlock(3mrd)