mrd_eject - Move a cartridge from a slot to a port
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_eject(
const char *robot_name,
const char *volume_tag,
const char *slot,
const char *port,
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 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 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_eject(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
slot to the specified port. 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 slot
and port address will be verified they are within the valid range
of those elements on the robot.
The cartridge_name argument can be used to perform cartridge
volume tag verification before the move. If the cartridge volume
tag at the slot doesn't match that specified by this argument,
then mrd_eject(3mrd) will fail with the status MRD_STATUS_CART_
INVALID. If cartridge_name 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.
If the slot string is an empty string and the library is a TL820
family member, this routine will attempt to move a cartrige on
the PTM to the port specified by the port argument. This is the
equivalent of the Eject Port command of the CLI.
3 – Example
/*
* Example mrd_eject(3mrd).
*
* This example is slightly different from the others since it
* also demonstrates the Eject Port feature of mrd_eject(3mrd).
* This feature can be used on the TL820 family to move a tape
* from the Pass-through mechanism (PTM) to the outport.
*
* The command usage is:
*
* mrd_eject robot [ slot port [ volume_tag ] ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_eject.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_eject(3mrd) */
char *robot ; /* Name of the robot to use */
char *volume_tag = NULL ; /* Volume tag to check */
char *slot ; /* Source slot */
char *port ; /* Destination port */
char log_info[MRD_MAX_LOG_STRING+1] ; /* Error text */
/*
* Allow the command to only have the robot name specified.
*/
if( argc < 2 ) {
printf("usage: %s robot [ slot port [ volume_tag ] ]\n",
argv[0]) ;
exit(1) ;
}
else
robot = argv[1] ;
/*
* If the slot and port aren't specified assume that
* the target robot is a TL820 and fill in default
* values for an Eject Port. Otherwise take the
* desired values directly from the command line.
*/
if( argc >= 4 ) {
slot = argv[2] ;
port = argv[3] ;
/*
* Collect the volume_tag name if the user wants it.
*/
if( argc > 4 )
volume_tag = argv[4] ;
}
/*
* We also observe that this case catches the command:
*
* mrd_eject robot_name address
*
* It can't hurt to let the user specify the outport,
* since an invalid one simply won't work. In this case
* the 3rd argument is the port name instead of the slot
* name.
*
* The user could get the same affect by using a quoted
* empty string for the slot argument on the command line:
*
* robot /dev/mc54 "" 1
*/
else {
if( argc == 3 )
port = argv[2] ;
else
port = "1" ;
slot = "" ;
}
/*
* Do the operation.
*/
status = mrd_eject(robot, volume_tag, slot, port, log_info) ;
if( status == MRD_STATUS_SUCCESS )
printf("Ejected the media in slot #%d to port #%d.\n",
slot, port) ;
else
printf("Eject failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_eject(3mrd) function returns
the value MRD_STATUS_SUCCESS. If the mrd_eject(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, slot, port, or log_info
are NULL pointers.
4.2 – 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.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_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_inject(3mrd)