The following list identifies the operating system specific
routines.
o mrd_initialize_element(3mrd)
o mrd_move_medium(3mrd)
o mrd_position_to_element(3mrd)
o mrd_prevent_allow(3mrd)
o mrd_read_element_status(3mrd)
o mrd_ready(3mrd)
o mrd_request_sense(3mrd)
o mrd_test_unit_ready(3mrd)
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.