mrd_strstatus
o mrd_strelement
o mrd_strexcept - I18N MRD messages and strings.
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
char *mrd_strstatus(int code) ;
char *mrd_strexcept(
unsigned char asc,
unsigned char ascq,
char *buffer,
size_t length) ;
char *mrd_strelement(int code) ;
1 – Parameters
o code - For mrd_strstatus(3mrd) this is the status
code returned from one of the MRD functions. For mrd_
strelement(3mrd) this is a code number corresponding to a
number of common strings that may occur in an appliation using
MRD.
o asc - This is the SCSI Additional Sense Code (ASC) in
the element status data (data.asc) obtained from the mrd_
show(3mrd) or mrd_find_cartridge(3mrd) functions.
o ascq - This is the SCSI Additional Sense Code Qualifer (ASCQ)
in the element status data (data.ascq) obtained from the mrd_
show(3mrd) or mrd_find_cartridge(3mrd) functions.
o buffer - This is the address of a user supplied buffer, into
which the message corresponding to the provided ASC/ASCQ code
will be copied. This message is formatted to include the ASC
/ASCQ codes in hexadecimal.
o length - This is size of the buffer provided. No more than
length characters will be copied from the internal temporary
buffer to the user's buffer. The internal buffer is limited to
BUFSIZ characters.
2 – Description
These routines offer an interface to convert MRD status codes,
element exception codes and constants for other common words
into internationalized text. The message catalogs used by these
routines are the same ones used by the Media Robot Utility
command line interface. However, if no message catalog is
available, a standard default message will be used for each code.
The routine mrd_strstatus(3mrd) accepts MRD error codes and
returns the corresponding message string from the catalog.
The routine mrd_strelement(3mrd) accepts one of the MRD_ELEMENT
codes defined in <mrd_message.h> and returns the corresponding
word. An effort has been made to ensure that the first four
code values correspond to the SCSI element types of SLOT, DRIVE,
PORT and TRANSPORT, but the routine will remap these values to
corresponding MRD_ELEMENT codes and return that string.
The routine mrd_strexcept(3mrd) accepts the ASC/ASCQ code set
in the element_info_t structure from an mrd_show(3mrd) or mrd_
find_cartridge(3mrd) when the ELEMENT_EXCEPT bit is set in the
data.state field. Using the user provided buffer and length
it will format the corresponding message to include the ASC
/ASCQ values and return a pointer to the space. Since many
of these code are vendor specific, we're unable to provide
translations for all them, but we have made an effort to include
the translations for many of the exception codes on supported
medium-changers.
3 – Codes Translated
The following MRD_ELEMENT codes are those currently supported by
mrd_strelement(3mrd), with their corresponding default strings.
The first items listed are self-explanatory.
o MRD_ELEMENT_TRANSPORT - Transport
o MRD_ELEMENT_SLOT - Slot
o MRD_ELEMENT_PORT - Port
o MRD_ELEMENT_DRIVE - Drive
o MRD_ELEMENT_EMPTY - Empty
o MRD_ELEMENT_FULL - Full
o MRD_ELEMENT_EXCEPT - Exception
o MRD_ELEMENT_ACCESS - Access
o MRD_ELEMENT_INPORT - Inport is suitable for use when the
ELEMENT_IMPENB bit is set in the state and data.state field
of the element_info_t data.
o MRD_ELEMENT_OUTPORT - OUTPORT is suitable for use when the
ELEMENT_EXPENB bit is set in the state and data.state field of
the element_info_t data.
o MRD_ELEMENT_IOPORT - IOPORT suitable for use when the ELEMENT_
IMPENB and ELEMENT_EXPENB bits are set in the state and
data.state field of the element_info_t data.
o MRD_ELEMENT_PASS - PassThru suitable in those cases where
the Pass-through mechanism of the TL820 can be identified.
Currently, the only way to do this is to know the absolute
address of the PTM depending on whether the library is in
Multi-unit Single-LUN (Transport 1) mode or Single-unit
Single-LUN (Port 2) mode.
o MRD_ELEMENT_MYSTERY - This code is suitable when neither
the ELEMENT_IMPENB nor ELEMENT_EXPENB bits are set in the
state and data.state field of the element_info_t data. Most
medium-changers identify their ports, when they have one
or the other, or both. The MRD engineering team has never
encountered a (correctly functioning) medium-changer with a
Mystery Port.
* We do not expect this text to survive critical
review of the management, but we tried.
4 – Example
/*
* Illustrate the different mrd_str*(3mrd) functions. For each
* case a code from one the mrd_message.h is selected and the
* resulting string printed. The command doesn't require
* any arguments.
*/
#ifndef lint
static char SccsId[] = "@(#)mrd_string.c 1.2 3/5/97" ;
#endif
#include <stdio.h>
#include <stdlib.h>
#include <mrd_common.h>
#include <mrd_message.h>
main(int argc, char *argv[])
{
/*
* This happens to be an obscure VMS system service error code.
*/
int status = MRD_STATUS_UNASEFC ;
/*
* The code for the TL820 Pass-through mechanism.
*/
int word = MRD_ELEMENT_PASS ;
/*
* The codes for when a TL820 doesn't a have a bin-pack
* installed for a certain range of slots.
*/
char asc = 0x80 ;
char ascq = 0x2 ;
/*
* Buffer for the message.
*/
char buffer[BUFSIZ] ;
printf("Status: %s\n", mrd_strstatus(status)) ;
printf("Word: %s\n", mrd_strelement(word)) ;
printf("Exception: %s\n", mrd_strexcept(asc,ascq,buffer,BUFSIZ));
return 0 ;
}
5 – Return Values
These routines try very hard to return the corresponding error
text, even to the point of formatting the integer value into
the provided string, into a static buffer or returning a default
string. These routines should never return NULL, but they rely on
catgets(3) to do the underlying work of looking the error code in
the message catalogs.
6 – Related Functions
Functions:
o mrd_move(3mrd)
o mrd_load(3mrd)
o mrd_unload(3mrd)
o mrd_inject(3mrd)
o mrd_eject(3mrd)
o mrd_show(3mrd)
o mrd_ready(3mrd)
o mrd_position(3mrd)
o mrd_initialize(3mrd)
o mrd_home(3mrd)
o mrd_find_cartridge(3mrd)
o mrd_lock(3mrd)
o mrd_unlock(3mrd)