mrd_find_cartridge - Search for a cartridge by volume tag.
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_find_cartridge(
const char *robot_name,
const char *volume_tag,
const int element_type,
const char *element_start,
const int element_count,
element_info_t *result,
char *result_name,
int *result_type,
char *log_info);
1 – Parameters
o robot_name - The name of the robot device to be opened. On
Digital UNIX, if the leading character of the name is not a
slash (/), /dev/ will be prepended to the name.
o volume_tag- A NULL terminated character string that is the
volume tag to search for.
o element_type - The type of robot element on which the
operation takes place. If an element type of zero (0) is used,
all elements will be searched starting at element 0 of each
type and searching all the elements of that type on the robot.
The order of this search is Slot, Drive, Transport and finally
Ports.
o element_start- A NULL terminated character string that is the
zero relative address of the element where the search should
be started. This argument is not used when the element_type is
zero (0).
o element_count - A volume tag search in a large library
can take a long time. Some applications (a graphic user
interface for example) may want to break up a large search
into smaller, quicker sub-searches. When a specific element_
type is specified only a range specified by the element_name
and element_count will be searched. This argument is ignored
when the element_type is zero (0).
o result_param- If an element matching the volume_tag string is
found, the element_info_t will copied into the space pointed
to by result.
o result_name- The zero relative element address of the matching
element will be copied into the space pointed to by result_
name. This space should be a character array of size MRD_NAME_
SIZE.
o result_type- The element type of the matching element will be
copied into the space pointed to by result_type.
o log_info - This is a character array that should be at least
MRD_MAX_LOG_STRING in length. If this function fails as the
result of a SCSI error, this will be filled with the formatted
request sense data. If this function fails as the result
of an operating system error, the operating system message
particular to the error will be copied into the array.
2 – Description
This routine allows searching for the element location of a piece
of media using the volume tag as a search key. If the element_
type value is zero (0), all elements will searched in the order
Slot, Drive, Transport and Port. The element_name and element_
count arguments will be ignored in this case.
When a specific element type is specified, the search will be
limited to that element type. The element_name will used as the
starting location for a search and element_count as the number
of elements from that address to search. Using these arguments
a search of a large number of elements may be broken up into a
number of smaller searches.
When a matching element is found, the element_info_t data for
that element will copied into the space pointed to by result.
The zero relative element address and element type will also be
copied into the space provided.
2.1 – Element Info
The element_info_t data structure is defined in the include file
<mrd_common.h>. The fields of this data structure are described
below:
o name - The name field holds the volume tag of the media if
applicable.
o state - The state field can have one of the following values:
ELEMENT_FULL,
ELELMENT_EMPTY, or
ELEMENT_EXCEPT.
o port_type - If the element_type parameter specifies PORT, the
port_type field will have one of the following values:
IN_OUT_PORT,
INPORT,
OUTPORT.
o status - The status field can have one of the following
values:
MRD_STATUS_SLOT_INVALID,
MRD_STATUS_DEVICE_INVALID,
MRD_STATUS_TRANSPORT_INVALID,
MRD_STATUS_PORT_INVALID, or
MRD_STATUS_SUCCESS.
o flags - Use the ELEMENT_VALID mask on the flags field to
indicate whether or not the full Read Element Status data
is valid. The ELEMENT_PVOLTAG and ELEMENT_AVOLTAG indicate
whether the primary or alternate volume tags of the Read
Element Status data are valid.
o element_addr - This is the address of the element, unadjusted
for the starting address. The routine mrd_map_element(3mrd)
can be used to convert an absolute element address to a
relative address and type. This field will be set to -1 when
the information is not valid.
o source_addr - On most SCSI-2 medium-changers, this is the
address where a cartridge resided before being moved to its
current location. The routine mrd_map_element(3mrd) can be
used to convert an absolute element address to a relative
address and type. This field will be set to -1 when the
information is not valid. On some SCSI-2 medium-changers (the
DLT family loaders) this will be the element address of the
slot itself.
o data - This a copy of the SCSI-2 Read Element Status data
when the ELEMENT_VALID bit is set in the flags field. A byte-
order neutral declaration of this data structure is included
in the <mrd_common.h> include file as the mrd_reades_t data
structure.
3 – Example
/*
* Example of mrd_find_cartridge(3mrd). The command usage is:
*
* mrd_find robot_name volume_tag
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_find.c 1.2 3/5/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <mrd_common.h>
#include <mrd_message.h>
main(int argc, char *argv[])
{
element_info_t element ; /* Element data result */
int status ; /* status from mrd_find_cartridge(3mrd) */
char *robot ; /* Medium changer to search */
char *volume_tag ; /* Volume tag for which to search */
int type ; /* Element type result */
char *content ; /* element content */
char *format ; /* format to print element data */
char address[MRD_NAME_SIZE+1] ; /* Element name result */
char log_info[MRD_MAX_LOG_STRING+1] ; /* error text */
char exception[BUFSIZ+1] ; /* exception buffer */
/*
* There are two required arguments; robot name and volume tag.
*/
if( argc < 3 ) {
printf("usage: %s robot volume-tag\n", argv[0]) ;
exit(1) ;
}
robot = argv[1] ;
volume_tag = argv[2] ;
/*
* Search all of the elements at the same time. With the
* type set to zero, the values of element_address ("")
* and element_count (0), don't matter.
*/
status = mrd_find_cartridge(robot, volume_tag, 0, "", 0, &element,
address, &type, log_info) ;
if( status != MRD_STATUS_SUCCESS )
printf("Can't find volume %s: %s: %s.\n", mrd_strstatus(status),
log_info[0] ? log_info : "none") ;
/*
* Need to print out the results of the find. This is
* similar to that used by mrd_show, but is a bit more
* extensive to show more features.
*/
format = "%s\t%s\t%s\n" ; /* default format */
if( element.name[0] )
content = element.name ;
else if( element.state & ELEMENT_FULL )
content = "Full" ;
else if( element.state & ELEMENT_EXCEPT ) {
format = "%s\t%s\t%s\t%s\n" ;
content = "Exception" ;
(void)mrd_strexcept(element.data.asc, element.data.ascq,
exception, BUFSIZ) ;
}
else
content = "Empty" ;
if( element.state & ELEMENT_EXCEPT )
printf(format, mrd_strelement(type), address, content,
exception) ;
else
printf(format, mrd_strelement(type), address, content) ;
return 0 ;
}
4 – Return Values
Upon successful completion, the mrd_find_cartridge(3mrd)
function returns the value MRD_STATUS_SUCCESS. If the mrd_find_
cartridge(3mrd) fails the returned status value may be set to one
of the following values. This routine may also return any of the
errors descibed in the mrd_show(3mrd) manual page. Other values
that correspond to specific SCSI errors may also be possible, but
the ones below are most likely.
4.1 – MRD_STATUS_PARAM
This error is returned if the robot_name, volume_tag, log_info,
result, result_name, element_start or result_type arguments are
NULL pointers.
4.2 – 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.
4.3 – 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.
4.4 – 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.
4.5 – 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.
4.6 – 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.
4.7 – 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.
4.8 – 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.
4.9 – 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.10 – 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 – Restrictions
The SCSI-2 specification includes two commands which allow a
medium-changer to perform most of the work that this routine
does by brute force. Unfortunately, a reliable implementation of
these commands was unavailable at the time MRD V1.2 was written.
A future version of the API may be able to make use of these
routines to speed up a search.
Unlike mrd_show(3mrd) this routine will open and close the robot
at each iteration.
6 – Related Functions
Functions:
o mrd_show(3mrd)
o mrd_map_element(3mrd)