mrd_inject - Move a cartridge from an inport to a slot
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
include <mrd_common.h>
include <mrd_message.h>
int mrd_inject(
const char *robot_name,
const char *volume_tag,
const char *port,
const char *slot,
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 volume_tag - A NULL terminated character string that is the
expected volume tag on the cartridge to be moved. On robots
with vision support this string will be compared with the
volume tag of the cartridge in the source slot and if it
doesn't match the call will fail. This feature will not be
used if the volume_tag is NULL or the empty string.
o port - A NULL terminated character string that is the zero
relative address of the port which is to be used as the
destination of the move.
o slot - A NULL terminated character string that is the zero
relative address of the slot which is to be used as the source
of the move.
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_inject(3mrd) function is a specialized interface to the
SCSI Move Medium command. For the robot specified by robot_name,
the routine will attempt to move the cartridge in the specified
port to the specified slot. Element addresses are zero based.
The robot will be opened and the arguments to the function will
be verified to make sure they are safe and appropriate. The port
and slot address will be verified they are within the valid of
those elements on the robot.
The volume_tag argument can be used to perform cartridge volume
tag verification before the move. If the cartridge volume tag at
the port doesn't match that specified by this argument, then mrd_
inject(3mrd) will fail with the status MRD_STATUS_CART_INVALID.
If volume_tag argument is a NULL pointer, an empty string or
used on a robot without vision support this argument is silently
ignored and the volume tag check will not be made.
The TL820 family requires special handling within the mrd_
inject(3mrd) routine, because of the way the Input/Output Device
(IOD) works. This routine will explicitly check the specified
inport to see if it is full. If empty and the robot is a TL820,
the Pass-through mechanism will then be checked. If the PTM is
full the source address will be reset to the PTM. If both are
empty, the routine will send a Ready Inport command to enable the
IOD. A one minute polling loop will be performed waiting for the
inport to become full, five seconds between polls. If this first
loop fails, the Ready Inport will be sent again and the loop
repeated. This allows the user two minutes to put a tape into the
inport.
If volume tag verification is desired on the TL820, the cartridge
will be moved to the PTM so the volume tag can be read. If the
check fails, the cartridge will left on the PTM. If the mrd_
inject(3mrd) is repeated with the correct volume tag or without
one, the cartridge will be found on the PTM and the Move Medium
command will proceed from there.
3 – Example
/*
* 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 ;
}
4 – Return Values
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.
4.1 – MRD_STATUS_PARAM
This error is returned if the robot_name, log_info, slot, or port
arguments are NULL pointers.
4.2 – MRD_STATUS_ROBOT_ILLEGAL_REQUEST
It is used when a sanity check fails in the code that attempts
to move a cartridge to the Pass-Through Mechanism, when the robot
type isn't a TL82n.
It is 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.3 – 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.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_SOURCE_EMPTY
On routines that perform a SCSI Move Medium command, this error
indicates that the source element is empty.
4.6 – MRD_STATUS_DESTINATION_FULL
On routines that perform a SCSI Move Medium command, this error
indicates that the destination element already has a cartridge in
it.
4.7 – MRD_STATUS_CART_INVALID
For routines that accept a volume_tag argument to perform volume
tag verification, this error indicates that the volume tag of the
media doesn't match that passed to the function.
4.8 – MRD_STATUS_ROBOT_MECH_ERROR
This error occurs as the result of a SCSI command failure, when
the ASC is set to one of:
o 0x15 - Positioning error.
o 0x8B - Vendor unique; Pass-through mechanism errors on the
TL82n
4.9 – MRD_STATUS_VENDOR_UNIQUE_ERROR
This error occurs when the internal routine used to decode SCSI-
2 errors encounters an error that it has not been written to
antipicate.
This error also returned when the ASC is zero and the ASCQ is not
one of zero or six, and when ASC/ASCQ are both zero and the key
is 9h.
4.10 – 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
5 – Related Functions
Functions:
o mrd_move(3mrd)
o mrd_load(3mrd)
o mrd_unload(3mrd)
o mrd_eject(3mrd)
o mrd_ready_inport(3mrd)