mrd_position - Position a transport to an element.
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_position(
const char *robot_name,
const char *transport,
const char *element,
const int element_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 transport - The transport is the numeric value of the
transport which will be moved.
o element A NULL terminated character string that is the zero
relative address of the element to which the transport is to
be moved.
o element_type The address of space where the type of the
destination will be copied if the move is successful. If the
element_type address is NULL, the type will not be returned.
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_position(3mrd) routine provides access to the SCSI
Position to Element command. For the robot specified by the
robot_name, the routine will attempt to position the specified
transport to the specified element. The transport and 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 transport should be inverted to invert a
cartridge.
The robot will be opened and the arguments to the function
verified that they are appropriate. The element address and
type 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 transport, are checked to verify they
are not NULL pointers.
Many robot subsystems support an absolute transport address of
zero for the Position to Element command so that the robot can
select the appropriate transport if multiple are available. This
routines allows the default transport address to be specified by
using a NULL pointer for the transport string.
3 – Example
/*
* Example to do slot to slot moves. The command usage is:
*
* mrd_position robot_name type address [ transport ]
*
* 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_position.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 ;
int side = 1 ;
char *robot ;
char *cart = NULL ;
char *element ;
char *transport ;
int type ;
char log_info[MRD_MAX_LOG_STRING+1] ;
if( argc < 4 ) {
printf("usage: %s robot type address [ transport ]\n",
argv[0]) ;
exit(1) ;
}
robot = argv[1] ;
type = convert_type(argv[2]) ;
element = argv[3] ;
if( argc > 4 ) {
transport = argv[4] ;
/*
* If "default" or a suitable abbreviation is used
* use NULL for the transport name, to indicate that
* the SCSI default transport should be used.
*/
#ifdef vms
if( strncmp("default", transport, strlen(transport)) == 0 )
#else
if( strncasecmp("default", transport, strlen(transport)) == 0 )
#endif
transport = NULL ;
}
else
transport = "0" ;
status = mrd_position(robot, transport, element, type,
side, log_info) ;
if( status != MRD_STATUS_SUCCESS )
printf("Position failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
else if ( transport == NULL )
printf("Positioned default Transport to %s #%s\n",
mrd_strelement(type), element) ;
else
printf("Positioned Transport #%s to %s #%s\n",
mrd_strelement(type), element) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_position(3mrd) function
returns the value MRD_STATUS_SUCCESS. If the mrd_position(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, or element
arguments are NULL pointers.
4.2 – MRD_STATUS_ROBOT_ILLEGAL_REQUEST
It is used when the medium changer does not support the Position
To Element command. The seven and five slot DLT loaders do not
support the command, though the TL820 and TL810 family libraries
do. Some models of TLZ6L and TLZ7L do not support the command and
may take a long time to fail.
It is also used for a SCSI command failure, when the ASC is set
to one of:
o 0x1A - Parameter list length error
o 0x20 - Invalid command operation code
o 0x22 - Unsupported command
o 0x24 - Illegal field in CDB
o 0x25 - Logical unit not supported
o 0x26 - Threshold parameters not supported
o 0x28 - Import or Export element accessed
o 0x2C - Command sequence error
o 0x39 - Saving parameters not supported
o 0x3D - Invalid bits in Identify message
o 0x53 - Medium removal prevented
This status is also returned when the ASC and ASCQ are zero, but
the key is five (5).
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_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.5 – 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.6 – 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.7 – 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.8 – 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.9 – 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:
mrd_position_to_element(3mrd)