mrd_move_medium - 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_medium(
robot_info_t *robot_info,
int transport,
int source,
int destination,
int invert,
dev_status_t *dev_status) ;
1 – Parameters
o robot_info - This is the address of a robot_info_t structure
initialized using mrd_startup(3mrd) or mrd_show(3mrd). This
data structure contains the element starting address and
counts for each type of element, which are needed to map an
absolute element to the correct zero relative address and
type.
o transport - The transport is the numeric value of the
transport which will be moved.
o source - The source is an absolute element address.
o destination- The destination is an absolute element address.
o invert - The invert is a numeric value used to indicate if the
medium should be inverted when it is moved. A value of one (1)
is used to indicate that the medium should be inverted.
o dev_status - The dev_status is the address of a dev_status_
t structure, which is used to pass back detailed error
information in the event of a command failure.
2 – Description
This routine performs a SCSI Move Medium command, or equivalent
if some other I/O architecture is supported. It is used by mrd_
move(3mrd), mrd_load(3mrd), mrd_unload(3mrd), mrd_inject(3mrd)
and mrd_eject(3mrd). Since it accepts a robot_info_t structure
associated with an open medium changer it can be used to perform
multiple move commands, without having to re-open the medium
changer as the other functions that use it do.
The robot_info argument is the address of a robot_info_t that
has been opened by mrd_startup(3mrd). If the medium changer isn't
opened, the Move Medium command will fail with the operating
system error for trying to use an unopened device. On SCSI medium
changers, it maps directly to the SCSI Move Medium command.
The transport address is the absolute address of the transport
element to be used for the command. Many medium changers allow
the use of address zero (0) as the default transport, but some
may require a transport address that is valid for the medium
changer. For single transport medium changers, the transport
base address in the robot_info_t structure, transport_start is a
suitable address.
The source and destination addresses are absolute addresses to
be used as the source and destination for the move. The absolute
address can be calculated from a zero relative address by adding
it to the base address for the element type. The routine makes
no checks for the validity of the address, relying on the medium
changer to do this.
A invert value of one (1) can be used on medium changers that
support inverting the media, when this is desired; an optical
drive with two sided media. Otherwise a value of zero should be
used.
This routine uses the dev_status_t structure for handing errors.
The dev_status_t structure includes the code, os_status, and SCSI
error fields. The following describes how to decode errors with
the dev_status_t structure.
SCSI Errors
SCSI errors are indicated when the value of the valid field of
the SCSI error is not equal to 0. The key, asc, and ascq fields
provide additional information to help determine the cause of the
error.
The code usually maps the Additional Sense Code and Additional
Sense Code Qualifier (ASC/ASCQ) values to an MRD error. The asc
and ascq values are copied from the request sense data returned
by the target.
The Additional Sense Code (asc) indicates further information
related to the error or exception condition reported in the sense
key field. The Additional Sense Code Qualifier (ascq) indicates
detailed information related to the additional sense code. For
more information, consult the SCSI-2 Specification.
Operating System Errors
Operating system errors are indicated when the value of the valid
field of the SCSI error is equal to 0 and the value of the os_
status field is not equal to 0. This result is most likely caused
by an operating system error, and probably has a mapped error in
MRD.
MRD Errors
MRD errors are indicated when the value of the os_status field is
0, and the value of the valid field of the SCSI error is 0. This
result is most likely caused when MRD encounters its own failure.
3 – Absolute Addresses
The operating system interface routines use absolute SCSI element
addresses, instead of zero relative address as used by the higher
level functions. A zero based element address can be converted to
an absolute address by adding the element base address from the
robot_info_t structure. For example, the absolute slot address
can be found by adding slot_start to the relative slot address:
4 – Example
/*
* This is an example of using mrd_move_medium(3mrd) directly to
* move a cartridge from one slot to another. To simplify the
* example, it only supports slot to slot moves, but it shows
* how the absolute element addresses are calcuated. For each
* additional destination address given, the previous (successful)
* destination address is used as the source.
*
* Usage:
*
* mrd_move_medium robot source dest [ dest... ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_move_medium.c 1.4 3/5/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>
main(int argc, char *argv[])
{
int i ; /* counter */
int source ; /* Source address */
int dest ; /* Destination address */
int invert = 0 ; /* Assume it can't invert */
int transport ; /* Transport address */
int status ; /* return status */
char *robot ; /* Robot to open */
robot_info_t robot_info ; /* Robot data */
dev_status_t dev_status ; /* Device status */
char log_info[MRD_MAX_LOG_STRING+1] ;
/*
* Check that there are enough arguments.
*/
if( argc < 4 ) {
printf("usage: %s robot source dest [ dest... ]\n", argv[0]) ;
exit(1) ;
}
else {
robot = argv[1] ;
source = atoi(argv[2]) ;
}
/*
* Initialize the channel field of the robot_info, so
* mrd_startup(3mrd) will actually open the robot.
*/
robot_info.channel = BAD_CHANNEL ;
status = mrd_startup(robot, &robot_info, log_info) ;
if( status != MRD_STATUS_SUCCESS ) {
printf("Startup failed: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
exit(1) ;
}
/*
* Set the transport address. If there is only one
* transport use the correct address. If there is
* more than one assume that the medium changer
* supports zero as the default.
*/
if( robot_info.transport_count == 1 )
transport = robot_info.transport_start ;
else
transport = 0 ;
/*
* Turn the relative slot address into an absolute slot
* address by adding the slot start address.
*/
source += robot_info.slot_start ;
/*
* For each destination address on the command line,
* move the the cartridge in the source to the
* destination. After each (successful) move, replace
* the previous source with this destination.
*/
for(i = 3; i < argc; i++) {
/*
* Calculate the absolute address.
*/
dest = atoi(argv[i]) + robot_info.slot_start ;
/*
* Print an audit as we go. Since we know these
* are slots, convert back to relative addresses
* for the audit.
*/
printf("Move the medium in slot %d to slot %d\n",
source - robot_info.slot_start,
dest - robot_info.slot_start) ;
status = mrd_move_medium(&robot_info, transport, source,
dest, invert, &dev_status) ;
if( status != MRD_STATUS_SUCCESS ) {
printf("Move failed on %s: %s\n", robot,
mrd_strstatus(status)) ;
/*
* Since the cartridge didn't move, don't
* reset the source, by skipping the remainder
* of the loop.
*/
continue ;
}
/*
* Make the next source, this destination.
*/
source = dest ;
}
(void)mrd_shutdown(&robot_info) ;
return 0 ;
}
5 – Return Values
Upon successful completion, mrd_move_medium(3mrd) will
return MRD_STATUS_SUCCESS. On a failure, an MRD_STATUS value
corresponding to the error will be returned. Common errors are:
5.1 – MRD_STATUS_PARAM
This error is returned if the robot_info or dev_status arguments
are NULL pointers.
5.2 – 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.
5.3 – 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.
5.4 – MRD_STATUS_SOURCE_EMPTY
On routines that perform a SCSI Move Medium command, this error
indicates that the source element is empty.
5.5 – MRD_STATUS_ELEMENT_INVALID
This error occurs when a SCSI command fails with the ASC set to
0x21. The log_info will contain the ASCQ. This indicates that an
invalid element address reached the medium-changer. For example,
specifying the 13th slot when only 12 slots are present.
5.6 – 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.7 – MRD_STATUS_IVCHAN
This error code is used when an OpenVMS system service fails
with the status SS$_IVCHAN. It is likely when an operating system
specific routine is used on a device that hasn't been opened by
mrd_startup(3mrd).
6 – Related Functions
Functions:
o mrd_move(3mrd)
o mrd_load(3mrd)
o mrd_unload(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)