Media Robot Utility Version 1.4
Possession, use, or copying of the software described in this documentation is authorized only pursuant to a valid written license from COMPAQ, an authorized sublicenser, or the identified licenser.
While COMPAQ believes the information included in this publication is correct as of the date of publication, it is subject to change without notice.
Compaq Computer Corporation makes no representations that the interconnection of its products in the manner described in this document will not infringe existing or future patent rights, nor do the descriptions contained in this document imply the granting of licenses to make, use, or sell equipment or software in accordance with the description.
Copyright Compaq Computer Corporation 1997, 1998, 1999
All Rights Reserved.
Printed in the United States of America.
COMPAQ, DIGITAL, DIGITAL UNIX, and the COMPAQ and :DIGITAL logos Registered in U.S. Patent and Trademark Office.
DECconnect, HSZ, StorageWorks, VMS, and OpenVMS are trademarks of Compaq Computer Corporation.
AIX is registered trademark of International Business Machines Corporation.
FTP Software is a trademark of FTP SOFTWARE, INC.
HP is a registered trademark of Hewlett-Packard Company.
NT is a trademark of Microsoft Corporation.
Oracle, Oracle Rdb, and Oracle RMU are all registered trademarks of Oracle Corporation.
PostScript is a registered trademark of Adobe Systems, Inc.
RDF is a trademark of Touch Technologies, Inc.
SGI is a registered trademark of Chemical Bank.
Solaris is a registered trademark of Sun Microsystems, Inc.
StorageTek is a registered trademark of Storage Technology Corporation.
SunOS is a trademark of Sun Microsystems, Inc.
UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Ltd.
Windows and Windows NT are both trademarks of Microsoft Corporation.
All other trademarks and registered trademarks are the property of their respective holders.
This document was prepared using VAX DOCUMENT, Version V3.2-1a.
| Contents |
Media Robot Driver Library - A programming interface for controlling
SCSI-2 medium-changers.
1.1 Description
The Media Robot Driver library is a callable interface for controlling SCSI-2 medium-changers. The interface consists of two include files and an object library which are installed in an operating system specific location. The operating system specific locations are shown in Table 1-1.
| Windows NT | \Program Files\MRU\mrd.dll |
| UNIX | /usr/lib/libmrd.a |
| OpenVMS | SYS$LIBRARY:MRD$RTL.EXE |
The distribution also includes examples showing how each callable routine can be used and a manual page for each routine.
The <mrd_common.h> include file defines data structures used to provide information about the medium-changer and its elements. The <mrd_common.h> file also defines a large number of symbolic constants for element type codes, offsets within SCSI structures, masks for SCSI bit fields, and other useful structures. The <mrd_common.h> file also includes prototype definitions of all the medium-changer functions provided in the interface.
The <mrd_message.h> include file defines constants for each error code returned by the MRD interface. Function prototypes are also included for routines that will return a string corresponding to the error code.
On Digital UNIX, these strings are retrieved from an I18N message
catalog that is part of the installed software. Code and routines are
also included for words and element exception messages that might be
commonly used by a medium-changer application.
1.1.1 Element Address Naming
The first OpenVMS implementation of MRD supported the TF and TA family DLT media-changers. It used Mass Storage Control Protocol Display commands to indicate what cartridge should be moved. The MSCP uses cartridge address names instead of numbers as SCSI does. When SCSI support was added to the MRD, the convention of using strings for the address was kept and thus it has been since.
In the common interface example programs, the character strings for the addresses are taken directly from the command line arguments and no special formatting is necessary. But, in practice, a program will probably keep SCSI addresses in numeric form and will have to convert those to strings. In the MRU command line interface and graphic user interface we use sprintf(3) for this:
int element_number ; char element[MRD_NAME_SIZE+1] ; element_number = 5 ; sprintf(element, "%d", element_number) ; |
The media robot driver library routines comprise two categories, the
common routines and operating system specific routines.
1.2.1 Common Routines
The following list identifies the common routines.
The common routines will open a robot to perform their operations. All these routines will close the robot when successfully completed, except for mrd_show(3mrd). The mrd_show(3mrd) routine closes the robot only when it encounters an error.
The routine mrd_startup(3mrd) is used to open a medium-changer. It will fill in a robot_info_t data structure that contains the number of elements of each type, their addresses and the medium-changer SCSI Inquiry data. Thus, it is unnecessary (and often not desirable) to keep the robot open while it is being used. The routine mrd_shutdown(3mrd) can be used to close the robot. Aside from closing the file and setting the channel field to BAD_CHANNEL, it has no effect on the other data in the robot_info_t data structure.
Use the mrd_show(3mrd) routine to obtain information about the contents and state of the slots, drive, ports and transports of the medium-changer. The mrd_show(3mrd) routine will open a robot, but it will also work if the robot is already open when the routine is called. For each element requested, an element_info_t data structure will be set if the element exists. The mrd_show(3mrd) function will accept the address of a robot_info_t data structure. If the robot has already been opened by mrd_startup(3mrd), this open robot will be used by the routine. If the robot isn't open (indicated by the channel field set to BAD_CHANNEL), the medium-changer indicated by the robot_name will be opened. If the routine completes successfully, the medium-changer will remain open. On an error, the medium-changer will be closed and the channel field reset to BAD_CHANNEL. By keeping the medium-changer open, multiple calls can be made to mrd_show(3mrd) without incurring the time to call mrd_startup(3mrd) each time.
The routine mrd_move(3mrd) is a general interface to the SCSI Move Medium command. It allows the specification of source and destination elements for the move, whether the medium should be inverted and an optional volume tag. On medium-changers which have a vision system to read bar-codes, the volume tag can be used to verify that the medium in the source slot is the one desired.
The routines mrd_load(3mrd), mrd_unload(3mrd), mrd_inject(3mrd) and mrd_eject(3mrd) are specialized interfaces to the SCSI Move Medium command. Load will move a medium from a slot to a drive. Unload will move a medium from a drive to a slot. Inject moves a medium from a port to a slot and Eject from a slot to a port. On the TL82x family of libraries, mrd_eject(3mrd) can also be used to clear a medium from the Pass-Through Mechanism.
The routine mrd_lock(3mrd) enables sending a SCSI Prevent/Allow Media Removal command. Whether this command is supported, and its effect, depends on the robot.
The routine mrd_initialize(3mrd) sends a SCSI Initialize Element Status command. The effect of this command varies among robots, but it typically causes complete reinventory of the medium-changer.
The routine mrd_position(3mrd) sends a SCSI Position to Element command.
The routine mrd_ready_inport(3mrd) sends a vendor unique, Ready Inport command. On the TL82n family of libraries, this command enables the button which opens the Inport/Outport Device inport door. Other libraries and loaders may silently ignore this command or treat it as an illegal command.
On medium-changers which keep track of a medium's previous element location, the routine mrd_home(3mrd) returns a medium to that location.
On medium-changers with vision systems to read bar-code labels, the routine mrd_find_cartridge(3mrd) will search for a specified volume tag. The routine will search the entire library, or just a subset of elements according to the arguments used.
The routine mrd_map_element(3mrd) accepts an element's absolute address and returns the element type and zero relative address.
The routine mrd_strstatus(3mrd) accepts an MRD error
status code and returns the corresponding message text. The routine
mrd_strelement(3mrd) accepts an MRD_ELEMENT code for
various words which apply to SCSI-2 medium-changer elements and returns
the corresponding string. The routine
mrd_strexcept(3mrd) accepts the Additional Sense Code
and Additional Sense Code Qualifier for an element with an exception
and returns the corresponding message text.
1.2.2 Operating System Routines
The following list identifies the operating system specific routines.
The operating system interface routines can be called directly and share three common traits.
Trait 1
Instead of a medium changer name, they accept a robot_info_t data structure that has been opened by mrd_startup(3mrd). This allows them to be called without the repeated start-up time of mrd_startup(3mrd) and allows keeping the medium changer open by a single application.
Trait 2
Instead of zero-relative element addresses, these routines all use absolute element addresses. These address can be calculated by adding the zero-relative address of a specific element to the element start address from the robot_info_t structure.
For example:
/*
* Given an robot_info_t initialized with mrd_startup(3mrd)
* or mrd_show(3mrd), an element type and a relative element
* address, convert it to an absolute address.
*/
convert_relative(robot_info_t *robot_info, int type, int element)
{
switch( type )
case SLOT:
return element + robot_info->slot_start ;
case TRANSPORT:
return element + robot_info->transport_start ;
case DRIVE:
return element + robot_info->device_start ;
case PORT:
return element + robot_info->port_start ;
default:
return -1 ;
}
}
|
The routine mrd_move_medium(3mrd) is used by mrd_move(3mrd), mrd_load(3mrd), mrd_unload(3mrd), mrd_eject(3mrd) and mrd_inject(3mrd). These routines accepts the absolute transport, source and destination element addresses for a Move Medium command, as well as a value to indicate whether the medium should be inverted when moved.
The routine mrd_read_element_status(3mrd) is used by mrd_show(3mrd) and a variety of internal utility functions. It offers direct access to the SCSI Read Element Status command. However, the data returned is also uninterpreted Read Element Status data, so the application using it must interpret the data for itself. Since mrd_show(3mrd) allows keeping the medium changer open as well, it is usually easier to use, except for simple requests.
The routine mrd_position_to_element(3mrd) is used by mrd_position(3mrd). It offers direct access to the SCSI Position to Element command, accepting absolute element addresses for the transport and destination elements. It can also invert the transport where this is supported.
The routine mrd_initialize_element(3mrd) is used by mrd_initialize(3mrd). It offers direct access to the SCSI Initialize Element Status command.
The routine mrd_ready(3mrd) is used by mrd_ready_inport(3mrd). It offers direct access to the SCSI Position to Element command, accepting the absolute addresse of the port to be readied.
The routine mrd_prevent_allow(3mrd) is used by mrd_lock(3mrd). It offers direct access to the SCSI Prevent Allow Media Removal command, accepting a value to indicate which is desired.
The mrd_test_unit_ready(3mrd) 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).
The mrd_request_sense(3mrd) routine performs a SCSI Request Sense command, or equivalent if some other I/O architecture is supported. It is used by all MRD API routines to determine the cause of a command failure.
Trait 3
Finally, these routines accept the address of a dev_status_t structure for holding error status, instead of a the log_info string used by the other routines. This allows custom formatting of 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.
Compiling a Digital UNIX Application with MRD
The files <mrd_common.h> and <mrd_message.h> must be included by any source module wishing to use the MRD interface. The library was compiled with the -migrate and default optimization options available with the DEC OSF/1 V1.3 C compiler.
If the calling program is not compiled with the -migrate option, it will be necessary to link with the OTS library, </usr/lib/libots.a>. If not, the following symbols will be unresolved:
% make mrd_move cc -O -c mrd_move.c cc -O mrd_move.o -lmrd -o mrd_move ld: Unresolved: _OtsDivide64Unsigned _OtsMove _OtsDivide32 *** Exit 1 Stop. |
The subset containing the <libots.a> object
library has changed over the versions. In DEC OSF/1 V1.3 it is part of
the OTABASE. subset. By DEC OSF/1 V3.0 it had moved to OSFCMPLRS300,
where it has remained through Digital UNIX V4.0.
1.2.3 About Return Values
Upon successful completion, the Media Robot Driver library routines that access a medium-changer return the value MRD_STATUS_SUCCESS. On a failure, one of the following errors may be returned. The Media Robot Driver library will attempt to map SCSI failures to one of a small group of error codes, but not all errors have been anticipated.
Many of the MRD routines accept a log_info argument that is a character array. When a SCSI error occurs, the the Sense Key, additional Sense Code and Additional Sense Code Qualifier are formatted into the space provided. If the error is an operating system specific error, then the text corresponding to the error will be copied into the space provided.
1.2.3.1 Common Values
Common return values.
1.2.3.1.1 MRD_STATUS_PARAM
This error is returned when a pointer argument passed to an MRD routine is NULL, unless the routine is documented as one allowing a NULL pointer.
1.2.3.1.2 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.
1.2.3.1.3 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.
1.2.3.1.4 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).
1.2.3.1.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.
1.2.3.1.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.
1.2.3.1.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.
1.2.3.1.8 MRD_STATUS_DEVICE_INVALID
This error is returned when the element address for a drive is less than zero or greater than the number of drives.
1.2.3.1.9 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.
1.2.3.1.10 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.
1.2.3.1.11 MRD_STATUS_SOURCE_EMPTY
On routines that perform a SCSI Move Medium command, this error indicates that the source element is empty.
1.2.3.1.12 MRD_STATUS_AUTOCLEAN
This error occurs when a SCSI command fails with the ASC set to 0x30 and the ASCQ set to 0x3. On TL8nn libraries supporting Auto-clean, it indicates that a command was attempted while an auto-clean was in progress.
1.2.3.1.13 MRD_STATUS_CART_DAMAGED
This error occurs when a SCSI command fails with the ASC set to 0x30, but the ASCQ is NOT a value of 0x3. The log_info will contain the ASCQ.
1.2.3.1.14 MRD_STATUS_CART_NOT_FOUND
This error is returned by mrd_find_cartridge(3mrd) when it can't find the cartridge with the desired volume tag.
1.2.3.1.15 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.
1.2.3.1.16 MRD_STATUS_INSFMEM
The mrd_show(3mrd) and mrd_find_cartridge(3mrd) functions allocate virtual memory using malloc(3) to store temporary element data. If the attempt to allocate the memory fails, these routines will return this error.
1.2.3.1.17 MRD_STATUS_NO_ELEMENTS
This error occurs in mrd_show(3mrd), mrd_find_cartridge(3mrd) and mrd_home(3mrd) when the medium-changer has no elements within the range and type specified by the arguments.
1.2.3.1.18 MRD_STATUS_NO_VISION
This error occurs in mrd_find_cartridge(3mrd) when the medium-changer has no vision system with which to read bar-code labels.
1.2.3.1.19 MRD_STATUS_RES_INVALID
This error occurs in mrd_home(3mrd) when the element data returned from mrd_show(3mrd) is not valid.
1.2.3.1.20 MRD_STATUS_ROBOT_ATTENTION
This error occurs when a SCSI command fails with the ASC set to one of 0x29, 0x2A or 0x2F. The log_info contains the ASCQ. The SCSI translations for these error codes are:
This occurs when a SCSI command fails with the ASC set to 0x80 and the ASCQ set to 0x0. On TL8nn libraries this typically indicates that the cabinet door was opened during a command operation.
1.2.3.1.22 MRD_STATUS_ROBOT_ILLEGAL_REQUEST
This error occurs for a variety of reasons. It is used when a sanity check fails in the code that attempts to move a cartridge to the Pass-Through Mechanism, when the robot type isn't a TL82n. It is used in the mrd_lock(3mrd) code when the value is not one of ALLOW_REMOVAL or PREVENT_REMOVAL. It is used when the medium changer does not support the Prevent/Allow Medium Removal command or the lock value is not one or zero. The specific cause can be determined by examining the ASC/ASCQ values in the status data. It is used when a call to mrd_initialize_element(3mrd) is issued against a medium changer that does not support the Initialize Element Status command. 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 used 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:
This error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error occurs in mrd_home(3mrd) when the return address in the element data isn't valid.
1.2.3.1.25 MRD_STATUS_VENDOR_UNIQUE_ERROR
This error occurs when the internal routine used to decode SCSI-2 errors encounters an error that it has not been written to antipicate. This error is also returned when the ASC is zero and the ASCQ is not one of zero or six, and when ASC/ASCQ are both zero and the key is 9h.
1.2.3.1.26 MRD_STATUS_NO_SENSE
This error is returned by mrd_scsi_decode(3mrd) when the asc, ascq and key values are all zero (0). It is also returned when the key value is less than zero or greater than 15.
1.2.3.1.27 MRD_STATUS_RECOVERED_ERROR
This error occurs when a SCSI device returns only a sense key of 1h. This indicates that although a command successfully completed, the target device had performed some internal error recovery.
1.2.3.1.28 MRD_STATUS_MEDIUM_ERROR
This error occurs when ASC and ASCQ are zero, but the sense key is 3h. This occurs when the target encounters a nonrecoverable error due to a flaw in the medium.
1.2.3.1.29 MRD_STATUS_ROBOT_HW_ERROR
This error occurs when ASC and ASCQ are zero, but the sense key is 4h. This occurs when the target encounters a nonrecoverable hardware error.
1.2.3.1.30 MRD_STATUS_DATA_PROTECT
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is seven (7).
1.2.3.1.31 MRD_STATUS_BLANK_CHECK
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is eight (8).
1.2.3.1.32 MRD_STATUS_COPY_ABORTED
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is ten (10).
1.2.3.1.33 MRD_STATUS_SENSE_EQUAL
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Ch (12).
1.2.3.1.34 MRD_STATUS_VOLUME_OVERFLOW
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Dh (13).
1.2.3.1.35 MRD_STATUS_MISCOMPARE
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Eh (14).
1.2.3.1.36 MRD_STATUS_SENSE_RESERVED
This error is returned by mrd_scsi_decode(3mrd) when the asc and ascq are zero, but the key value is Fh (15).
1.2.3.1.37 MRD_STATUS_SCSI_CHECK
The SCSI Check Condition error should never occur. It indicates that it is safe to use a Request Sense command and that you are likely to get a different error.
1.2.3.1.38 MRD_STATUS_SCSI_CONDMET
The SCSI Condition Met status indicates a SCSI command completed with the status "Condition Met".
1.2.3.1.39 MRD_STATUS_SCSI_BUSY
The SCSI Device is Busy status code indicates a SCSI command completed with the status "Busy". Some TZ87x media changers are known to cause this condition.
1.2.3.1.40 MRD_STATUS_SCSI_INTER
The SCSI Intermediate Command Completed status code indicates a SCSI command completed with the status "Intermediate".
1.2.3.1.41 MRD_STATUS_SCSI_INTER_CONDMET
The SCSI Intermediate-Condition Met status code indicates a SCSI command completed.
1.2.3.1.42 MRD_STATUS_SCSI_RESCON
The SCSI Reservation Conflict status code indicates a SCSI command completed with the status "Reservation Conflict".
1.2.3.1.43 MRD_STATUS_SCSI_TERM
The SCSI Command Terminated status code indicates a SCSI command completed with the status "Terminated".
1.2.3.1.44 MRD_STATUS_SCSI_QUEUE
The SCSI Queue Full status code indicates a SCSI command completed with the status "Queue Full".
1.2.3.1.45 MRD_STATUS_SCSI_RESERVED
The SCSI Status Code Reserved return indicates a SCSI command completed with a status that wasn't listed in Chapter 7 of the SCSI-2 specification and is "Reserved".
1.2.3.2 Windows NT Codes
The codes in this section apply only to the Windows NT operating system variant of the Media Robot Driver.
1.2.3.2.1 MRD_STATUS_ROBOT_COMM_ERROR
This error occurs as the result of a failure to open the specified medium-changer. This may occur directly by calling mrd_startup(3mrd) or by a routine that calls mrd_startup(3mrd) internally. This error also occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error is returned when a regular file or robot was specified without the ":BnTnLn" string.
1.2.3.2.3 MRD_STATUS_ROBOT_CMD_ABORTED
This error is returned by mrd_scsi_decode(3mrd) when the asc is zero and the ascq is six, or when the asc and ascq are zero and the key is eleven (11).
1.2.3.2.4 MRD_STATUS_IVCHAN
This error code is returned when the handle in NT parlance has been closed or is otherwise an invalid handle.
1.2.3.2.5 MRD_STATUS_EINVAL
This error code is returned when the ":BnTnLn" string points to an invalid or nonexistent SCSI address.
1.2.3.2.6 MRD_STATUS_ENOENT
This error is returned when the system cannot find the specified device.
1.2.3.2.7 MRD_STATUS_ROBOT_NOT_READY
Under Microsoft Windows NT, this error code is returned when the specified robot exists but is not responding.
1.2.3.3 Digital UNIX Codes
The following error codes can occur when a open(2) or ioctl(2) system call fails. Open(2) is used by mrd_startup(3mrd) to open the medium-changer. The ioctl(2) system call is used to perform all other SCSI medium-changer commands.
1.2.3.3.1 MRD_STATUS_ROBOT_COMM_ERROR
This error occurs as the result of a failure to open the specified medium-changer. This may occur directly by calling mrd_startup(3mrd) or by a routine that calls mrd_startup(3mrd) internally. This error also occurs as the result of a SCSI command failure, when the ASC is set to one of:
Under OpenVMS and Digital UNIX, this error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error is returned by mrd_scsi_decode(3mrd) when the asc is zero and the ascq is six, or when the asc and ascq are zero and the key is eleven (11).
1.2.3.3.4 MRD_STATUS_EBADF
This error occurs when the medium changer has not been opened by mrd_startup(3mrd) or has been closed by mrd_shutdown(3mrd).
1.2.3.3.5 MRD_STATUS_EINVAL
This error is returned by mrd_map_os_error(3mrd) when the os_status is EINVAL. This typically occurs during mrd_startup(3mrd) when the special file is not a SCSI device: for example, /dev/tty.
1.2.3.3.6 MRD_STATUS_STARTUP_ERROR
This error is returned by mrd_map_os_error(3mrd) when the os_status is ENODEV. This typically occurs during mrd_startup(3mrd) when the special file is not a SCSI device; /dev/null.
1.2.3.3.7 MRD_STATUS_NO_SUCH_DEVICE
This error occurs when a UNIX system call returns ENXIO, to indicate that the device corresponding to the special device does not exist.
1.2.3.3.8 MRD_STATUS_EBUSY
This error occurs when a UNIX system call returns EBUSY, to indicate that some other process is using that medium-changer device.
1.2.3.3.9 MRD_STATUS_EINTR
This error occurs when a UNIX system call returns EINTR. This error corresponds to an interrupted system call, but also occurs when the SCSI CAM Layered Components Medium-Changer driver is not configured into the running system.
1.2.3.3.10 MRD_STATUS_EIO
This error occurs when a UNIX system call returns EIO to indicate that there was an I/O error. In most cases an I/O error on a SCSI medium-changer indicates a SCSI error which be translated to another MRD error.
1.2.3.3.11 MRD_STATUS_ENOENT
This error occurs when a UNIX system call returns ENOENT to indicate that a special device file doesn't exist.
1.2.3.3.12 MRD_STATUS_EACCES
This error occurs when a UNIX system call returns EACCES to indicate that the caller does not have sufficient permission to open the special device file corresponding to the medium-changer. MRD expects to have read permission on the special device file.
1.2.3.3.13 MRD_STATUS_OS_ERROR
This error occurs when a UNIX system call returns an error that is not among those previously mentioned. The routine strerror(3) will be used to translate the error code into a standard text message which will be copied to log_info.
1.2.3.3.14 MRD_STATUS_INVALID
This error is a catch-all for MRD failures. All cases where this error is returned are those instances where MRD should have caught and reported the true cause of the failure.
1.2.3.4 OpenVMS Codes
The codes in this section apply only to the OpenVMS operating system variant of the Media Robot Driver.
1.2.3.4.1 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:
This error is returned when the element address for a drive is less than zero or greater than the number of drives. 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.
1.2.3.4.3 MRD_STATUS_ROBOT_NOT_READY
Under OpenVMS and Digital UNIX, this error occurs as the result of a SCSI command failure, when the ASC is set to one of:
This error code is used when an OpenVMS system service fails with the status SS$_ABORT.
1.2.3.4.5 MRD_STATUS_NOPRIV
This error code is used when an OpenVMS system service fails with the status SS$_NOPRIV. This will typically occur in mrd_startup(3mrd) when the caller doesn't have sufficient privilege to assign a channel to the device.
1.2.3.4.6 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).
1.2.3.4.7 MRD_STATUS_MOUNTED
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.
1.2.3.4.8 MRD_STATUS_PAGE_CODE
This error occurs in mrd_startup(3mrd) when a SCSI Mode Sense command fails to return the expected data. It uses the SCSI Element Address Assignment mode page to fill in the element count and base address fields of the robot_info_t structure. If the data returned by the medium changer does not have the expected page code, this error is returned. This error has been seen when medium changers are connected to HS family array controllers running V2.7 firmware.
1.2.3.4.9 MRD_STATUS_EBUSY
This error code is used when an OpenVMS system service fails with the status SS$_DEVALLOC. This generally happens in mrd_startup(3mrd) when another process already has the device allocated.
1.2.3.4.10 MRD_STATUS_DEVOFFLINE
This error code is used when an OpenVMS system service fails with the status SS$_DEVOFFLINE and SS$_MEDOFL.
1.2.3.4.11 MRD_STATUS_ACCVIO
This error indicates an internal application failure.
1.2.3.4.12 MRD_STATUS_EXQUOTA
This error occurs when an operation requested of the application causes you to exceed a process quota. To correct this problem, increase your process quotas.
1.2.3.4.13 MRD_STATUS_ILLEFC
For more information about this error, refer to the OpenVMS system documentation.
1.2.4 Related Information
Functions:
Standards: American National Standard for Information Systems, "Small Computer System Interface - 2", X3.131-199X, Chapter 17, Medium-Changers and Annex D, Numeric order codes
| Next | Contents |