mrd_home - Return a cartridge whence it came.
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_home(
const char *robot_name,
const char *volume_tag,
const char *source_name,
const int source_type,
char *destination_name,
int *destination_type,
char *log_info) ;
Restriction
Strict interpretation of the SCSI-2 specification by devices will
require that the device only report the address of the last SLOT a
medium was in.
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_name - A NULL terminated character string that is the
zero relative address of the element which 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_name - The address of space where the name of the
destination address will be written if the move is successful.
An character array of MRD_NAME_SIZE bytes should be used. If
the destination_name address is NULL, the address will not be
returned.
o destination_type - The address of space where the type of
the destination will be copied if the move is successful. If
the destination_type address is NULL, the type will not be
returned.
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 SCSI-2 specification for medium-changer devices allows an
element to remember the source element of the current piece
of media. For example, if a mrd_load(3mrd) is performed from
slot 17 to drive 2, the element information for drive 2 will
remember that the media came from slot 17. Where this feature
is implemented, it allows an application to query an element to
learn the original source of the media in it and return it.
The mrd_home(3mrd) function does this. Given a robot name and
element address it will see if the source address is valid
and when it is return that media to its original location.
If the source address is invalid or the element unavailable
an error will be returned. The routine will also check to see
if the media was inverted when placed in the current element
and restore it to its original orientation. When the move is
complete, the resulting address and element type will be copied
into destination_name and destination_type.
If the volume_tag argument is used, the routine will verify that
a cartridge with the volume tag is present in the element before
performing the move.
3 – Example
/*
* Example to do slot to slot moves. The command usage is:
*
* mrd_home robot_name type address [ volume-tag ]
*
* Type can be one of:
*
* slot, port, drive or transport
*
* The optional transport argument can be a transport address
* number, the word "default" or an empty string.
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_home.c 1.2 3/5/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mrd_common.h>
#include <mrd_message.h>
/*
* Given a string, resembling one of the element types,
* return the SCSI type code for it.
*/
struct {
int code ;
char *string ;
} etypes[] = {
TRANSPORT, "transport",
SLOT, "slot",
DRIVE, "drive",
PORT, "port",
} ;
convert_type(char *etype)
{
register i ;
/*
* For each entry in the array.
*/
for(i = 0; i < sizeof(etypes)/sizeof(etypes[0]); i++)
/*
* Do a case insensitive comparison, allowing
* abbreviations. Return as soon as a match is
* found. Return -1 if one isn't found.
*/
#ifdef vms
if( strncmp(etypes[i].string, etype, strlen(etype)) == 0)
#else
if( strncasecmp(etypes[i].string,etype,strlen(etype)) == 0)
#endif
return etypes[i].code ;
return -1 ;
}
main(int argc, char *argv[])
{
int status ; /* Status from mrd_home(3mrd) */
char *robot ; /* Robot to use */
char *element ; /* Element address */
char *volume_tag = NULL ; /* Optional volume tag */
int type ; /* Element type */
char home[MRD_NAME_SIZE+1] ; /* space for return address */
int home_type ; /* return element type */
char log_info[MRD_MAX_LOG_STRING+1] ; /* error string */
/*
* Three required arguments; robot, element type and address.
*/
if( argc < 4 ) {
printf("usage: %s robot type address [ volume_tag ]\n",
argv[0]) ;
exit(1) ;
}
robot = argv[1] ;
type = convert_type(argv[2]) ;
element = argv[3] ;
/*
* Optional volume tag.
*/
if( argc > 4 )
volume_tag = argv[4] ;
/*
* Do the operation.
*/
status = mrd_home(robot, volume_tag, element, type,
home, &home_type, log_info) ;
if( status != MRD_STATUS_SUCCESS )
printf("Home failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
else
printf("The cartridge in %s %s was returned to %s %s.\n",
mrd_strelement(type), element,
mrd_strelement(home_type), home) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_home(3mrd) function returns
the value MRD_STATUS_SUCCESS. If the mrd_home(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_info, source_name, or log_
info 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_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_RES_INVALID
This error occurs in mrd_home(3mrd) when the element data
returned from mrd_show(3mrd) is not valid.
4.7 – MRD_STATUS_SOURCE_INVALID
This error occurs in mrd_home(3mrd) when the return address in
the element data isn't valid.
4.8 – 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.9 – 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.10 – 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_show(3mrd)
o mrd_find_cartridge(3mrd)
o mrd_map_element(3mrd)