mrd_load - Move a piece of media from slot to drive.
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_load(
const char *robot_name,
const char *volume_tag,
const char *slot,
const short cartridge_side,
const char *drive,
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 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 cartridge_side - The cartridge_side indicates whether the
media should be inverted as it is being to moved to the
destination element. If the value 1 is used, the media will
not be inverted. If the value 2 is used the media will be
inverted.
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 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_load(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 slot to the specified drive. Element
addresses are zero based. On subsystems that support inverting a
cartridge during a move, the cartridge_side argument can be used
to indicate that the cartridge should be inverted.
The robot will be opened and the arguments to the function will
be verified to make sure they are safe and appropriate. The slot
and drive 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_
load(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.
3 – Example
/*
* 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 ;
}
4 – Return Values
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.
4.1 – MRD_STATUS_PARAM
This error is returned if the robot_name, log_info, slot, or
drive arguments are NULL pointers.
4.2 – 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.3 – MRD_STATUS_CART_SIDE_INVALID
For routines that use the cartridge_side argument, this error
indicates that the value is neither one (1) nor two (2).
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_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.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_unload(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)