mrd_move - Move media from one location to another
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_move(
const char *robot_name,
const char *volume_tag,
const char *source,
const int source_type,
const char *destination,
const int destination_type,
const int cartridge_side,
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 source - The source is a character string which is the zero
based element address that is to be used as the source of the
move.
o source_type - The source_type is an integer value to indicate
the type of the source_name address. The <mrd_common.h>
include file defines constants for different element types;
SLOT, DRIVE, PORT and TRANSPORT.
o destination - The destination is a character string which
is the zero based element address that is to be used as the
destination of the move.
o destination_type - The destination_type is an integer value
to indicate the element type of the destination address. The
<mrd_common.h> include file defines constants for different
element types; SLOT, DRIVE, PORT and TRANSPORT.
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 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_move(3mrd) function is an interface to the SCSI Move
Medium command. For the robot specified by robot_name, the
routine will attempt to move the cartridge in the element
specified by the source address and type to that specified by
the destination address and type.
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
verified that they are appropriate. Element addresses and types
will be checked that they are within the valid range of elements
on the robot. The cartridge_side argument will be verified that
it is either the value one (1) or two (2). All pointer arguments,
except cartridge_name, are checked to verify they are not NULL
pointers.
The cartridge_name argument can be used to perform cartridge
volume tag verification before the move. If the cartridge volume
tag at the source doesn't match that specified by this argument,
then mrd_move(3mrd) will fail with the status MRD_STATUS_CART_
INVALID. If the 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.
On the TL820 family of libraries, the tape will be moved to the
pass-through read station if the source is a Port. If this move
fails the status will be appropriate to that of a failed Move
Medium. Likely error codes are documented in the Return Values
section.
After the volume tag check, the destination address is checked
in the same way the source was. The same error codes are returned
if the destination address is out of range. With the range checks
completed the Move Medium command is issued. If successful MRD_
STATUS_SUCCESS is returned. If the command failed, the SCSI error
will be mapped to the appropriate MRD_STATUS message.
The DLT libraries (TL820 and TL810 families) require the host
issue a SCSI Unload command before a cartridge may be removed
from the drive. The function mrd_move(3mrd), does not offer
this feature. Thus, the calling program must do this itself. On
Digital UNIX this may done with the MTOFFL opcode of the MTIOCTOP
I/O control.
3 – Example
/*
* Example to do slot to slot moves, using mrd_move(3mrd). The
* reason for only doing slot to slot, is that it simplifies
* having to figure out element types. The mrd_position(3mrd)
* example shows how part of this may be done.
*
* The command usage is:
*
* mrd_move source-slot destination-slot [ volume-tag ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_move.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_move(3mrd) */
int side = 1 ; /* Only support side one */
char *robot ; /* Name of the robot to use */
char *volume_tag = NULL ; /* Volume tag to check */
char *source ; /* Source slot */
char *destination ; /* Destination slot */
char log_info[MRD_MAX_LOG_STRING+1] ; /* error string */
/*
* Three required arguments; robot name, source slot and
* destination slot.
*/
if( argc < 4 ) {
printf("usage: %s robot src dest [ volume-tag ]\n", argv[0]) ;
exit(1) ;
}
robot = argv[1] ;
source = argv[2] ;
destination = argv[3] ;
/*
* Volume tag is optional.
*/
if( argc > 4 )
volume_tag = argv[4] ;
/*
* Do the operation.
*/
status = mrd_move(robot, volume_tag, source, SLOT, destination,
SLOT, side, log_info) ;
if( status != MRD_STATUS_SUCCESS )
printf("Move failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
else
printf("Moved media from Slot #%s to Slot #%s\n",
source, destination) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_move(3mrd) function returns
the value MRD_STATUS_SUCCESS. If mrd_move(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, source, destination, or
log_info arguments are NULL pointers.
4.2 – 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.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_TRANSPORT_INVALID
This error is returned when the element address for a transport
is less than zero or greater than the number of transports.
4.5 – MRD_STATUS_INVALID_TYPE
For routines that allow the specification of an element type
argument, this error indicates that specified type was not one of
SLOT, DRIVE, PORT or TRANSPORT.
4.6 – 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.7 – MRD_STATUS_SOURCE_EMPTY
On routines that perform a SCSI Move Medium command, this error
indicates that the source element is empty.
4.8 – 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.9 – 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.10 – 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.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_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.
4.13 – 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.
On OpenVMS this can be done with $DISMOU system service.
5 – Related Functions
Functions:
o mrd_load(3mrd)
o mrd_unload(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)
o mrd_ready(3mrd)