mrd_ready - Send a Ready Inport command
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_ready(
robot_info_t *robot_info,
int port,
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 port - The absolute integer element address of the port which
is to be used as the destination of the move.
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
It is used by mrd_ready_inport(3mrd). This command is used by
the TL820 family of DLT libraries to enable the button on the I/O
device (IOD) which opens the Inport door.
The robot_info argument is the address of a robot_info_t that has
been opened by mrd_startup(3mrd).
The port argument is the absolute address of the port to be
readied. On supported TL820 configurations which use a left
mounted IOD this will always be 64.
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 – Example
/*
* This is an example of using mrd_move_medium 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_ready robot port [ port... ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_ready.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 pc ; /* counter */
int port ; /* Port number */
int address ; /* Port 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 < 3 ) {
printf("usage: %s robot port [ port... ]\n", argv[0]) ;
exit(1) ;
}
else
robot = argv[1] ;
/*
* 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 on %s: %s.\n", robot,
mrd_strstatus(status)) ;
exit(1) ;
}
/*
* 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(pc = 2; pc < argc; pc++) {
/*
* Get the port number.
*/
port = atoi(argv[pc]) ;
/*
* Now the absolute address.
*/
address = port + robot_info.port_start ;
/*
* Print an audit as we go. Since we know these
* are slots, convert back to relative addresses
* for the audit.
*/
printf("Ready Inport #%d of %s\n", port, robot) ;
status = mrd_ready(&robot_info, address, &dev_status) ;
if( status != MRD_STATUS_SUCCESS ) {
printf("Ready Inport 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 ;
}
}
(void)mrd_shutdown(&robot_info) ;
return 0 ;
}
4 – Return Values
Upon successful completion, mrd_ready(3mrd) will return MRD_
STATUS_SUCCESS. On a failure, one of the following status values
will be returned.
4.1 – MRD_STATUS_PARAM
This error is returned if the robot_info or dev_status arguments
are NULL pointers.
4.2 – MRD_STATUS_ROBOT_ILLEGAL_REQUEST
This error occurs when the medium changer does not support the
Ready Inport command. The TL820 family of DLT libraries support
this command. The TL810 family of DLT libraries allows this
command to succeed, but it doesn't perform any function.
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_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).
5 – Related Functions
Functions:
mrd_ready_inport(3mrd)