mrd_unload - Move a cartridge from drive to slot
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_unload(
const char *robot_name,
const char *volume_tag,
const char *drive,
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 drive - A NULL terminated character string that is the zero
relative address of the drive 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_unload(3mrd) function is a specialized interface to the
SCSI Move Medium command (or DSA equivalent). For the robot
specified by robot_name, the routine will attempt to move the
cartridge in the specified drive 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 drive
and slot address will be verified they are within the valid range
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_
unload(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 DLT libraries (TL82X and TL81X families) require the host
issue a SCSI Unload command before a cartridge may be removed
from the drive. The function mrd_unload(3mrd), does not offer
this feature. Thus, the calling program must do this itself. The
example below shows how this can be done on Digital UNIX.
3 – Example
This example applies to the OpenVMS operating system.
/*
* Example of mrd_unload(3mrd). The command usage is:
*
* mrd_unload robot_name drive slot [ volume_tag ]
*
* This version is VMS specific since it excludes the example
* for taking a tape drive offline. That is moderately complicated
* but something that should be in the VMS documentation.
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_unload.c 1.2A (mrd-example) 3/5/97" ;
#endif
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>
main(int argc, char *argv[])
{
int status ; /* Status from mrd_load(3mrd) */
char *robot ; /* The name of the robot */
char *cart = 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 and tape drive name are 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 there is an extra argument present, assume it is
* a cartridge name. The habit of the DECC runtime
* start-up mapping all characters to lower case,
* might require special handling of the cartridge
* name.
*/
if( argc > 4 )
cart = argv[4] ;
/*
* Call the function.
*/
status = mrd_unload(robot, cart, slot, drive, log_info) ;
/*
* 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
* NUL 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("Load failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
else
printf("Unloaded media from Drive #%s to Slot #%s.\n",
drive, slot) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_unload(3mrd) function returns
the value MRD_STATUS_SUCCESS. If the mrd_unload(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, drive, slot, or log_
info arguments are NULL pointers.
4.2 – MRD_STATUS_ROBOT_COMM_ERROR
This error occurs as the result of a failure to open the
specified medium-changer. This may occur directly by calling
mrd_startup(3mrd) or by a routine that calls mrd_startup(3mrd)
internally. 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.3 – 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.4 – 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.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_NOT_AVAIL
This error can occur on the TL81n and TL82n family of DLT
libraries when the source of a move is a drive and the cartridge
in the drive is still on-line. These robots do not allow moving
the cartridge until the drive is taken offline.
4.8 – 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.
5 – Related Functions
Functions:
o mrd_move(3mrd)
o mrd_load(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)