The media robot driver library routines comprise two categories,
the common routines and operating system specific routines.
1 – Common Routines
The following list identifies the common routines.
o mrd_eject(3mrd)
o mrd_find_cartridge(3mrd)
o mrd_home(3mrd)
o mrd_initialize(3mrd)
o mrd_inject(3mrd)
o mrd_load(3mrd)
o mrd_lock(3mrd)
o mrd_map_element(3mrd)
o mrd_move(3mrd)
o mrd_position(3mrd)
o mrd_ready_inport(3mrd)
o mrd_scsi_decode(3mrd)
o mrd_startup(3mrd)
o mrd_show(3mrd)
o mrd_shutdown(3mrd)
o mrd_strelement(3mrd)
o mrd_strexcept(3mrd)
o mrd_unload(3mrd)
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.
2 – OpenVMS Routines
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.