mrd_test_unit_ready - Verify a medium changer is ready to accept
commands
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_test_unit_ready(
robot_info_t *robot_info,
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 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 Test Unit Ready command, or
equivalent if some other I/O architecture is supported. It is
used by the mrd_startup(3mrd) and the OpenVMS implementation
of mrd_ready(3mrd). Since it accepts a robot_info_t structure
associated with an open medium changer it can used to perform
Test Unit Ready command without having to re-open the medium
changer each time.
The robot_info_t is the address of a robot_info_t that has been
opened by mrd_startup(3mrd). If the medium changer isn't opened,
the Test Unit Ready Command will fail with the operating system
error for trying to use an unopened device.
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_test_unit_ready(3mrd)
* to see if a media changer will accept commands. On
* Digital UNIX this particular example will always
* succeed whether the robot is ready or not. See the
* Restrictions section of the manual page for more
* information.
*
* Usage:
*
* mrd_test_unit_ready robot [ more-robots... ]
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_test_unit_ready.c 1.1 4/16/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <mrd_common.h>
#include <mrd_message.h>
/*
* Message string.
*/
char *tur_failed_dev =
"Test unit ready failed on %s: %s (%d,0x%x,0x%x).\n ";
char *tur_failed_os = "Test unit ready failed on %s: %s (%d).\n" ;
char *tur_failed = "Test unit ready failed on %s: %s.\n" ;
/*
* The MRD can report three types of errors:
*
* o Device errors - When the "valid" field is set, at least one
* of the key, asc and ascq field should have values set from
* a SCSI Request Sense data or equivalent.
*
* o Operating System errors - When the valid field is zero, but
* the os_status field is set. Where possible an MRD error
* will be set if one corresponds to the error. If not, the
* MRD status will be MRD_STATUS_OS_ERROR. The os_status
* is the error specific to the operating system. On Digital
* UNIX it is an errno value. On OpenVMS it is a system
* service return value.
*
* o MRD Errors - The MRD error code is set explicitly.
*/
print_error(char *robot, int mrd_status, dev_status_t *dp)
{
/*
* Print the Key/ASC/ASCQ data for device errors.
*/
if( dp->valid )
printf(tur_failed_dev, robot, mrd_strstatus(mrd_status),
dp->key, dp->asc, dp->ascq) ;
/*
* Try to decode the os_status according to the operating
* system type.
*/
else if( dp->os_status == MRD_STATUS_OS_ERROR )
printf(tur_failed_os, robot, mrd_strstatus(mrd_status),
#ifdef unix
strerror(dp->os_status)) ;
#endif
#ifdef vms
strerror(EVMSERR, dp->os_status)) ;
#endif
/*
* Just print the message on others.
*/
else
printf(tur_failed, robot, mrd_strstatus(mrd_status)) ;
}
main(int argc, char *argv[])
{
int rc ; /* counter */
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 < 2 ) {
printf("usage: %s robot [ robot... ]\n", argv[0]) ;
exit(1) ;
}
/*
* Initialize the channel field of the robot_info, so
* mrd_startup(3mrd) will actually open the robot.
*/
robot_info.channel = BAD_CHANNEL ;
for(rc = 1; rc < argc; rc++) {
/*
* The robot for this command.
*/
robot = argv[rc] ;
status = mrd_startup(robot, &robot_info, log_info) ;
if( status != MRD_STATUS_SUCCESS ) {
printf("Startup failed on %s: %s.\n", robot,
mrd_strstatus(status)) ;
continue ;
}
memset((void *)&dev_status, 0, sizeof(dev_status)) ;
status = mrd_test_unit_ready(&robot_info, &dev_status) ;
/*
* Do some fancy error printing.
*/
if( status != MRD_STATUS_SUCCESS )
print_error(robot, status, &dev_status) ;
else
printf("%s is ready.\n", robot) ;
(void)mrd_shutdown(&robot_info) ;
}
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_test_unit_ready(3mrd)
function returns the value MRD_STATUS_SUCCESS. If the mrd_test_
unit_ready(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, or dev_status are NULL
pointers.
4.2 – 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.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).
4.4 – 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_startup(3mrd)