mrd_lock - Send a SCSI Prevent-Allow Media Removal command
Windows NT mrd.dll
UNIX /usr/lib/libmrd.a
OpenVMS MRD$RTL.EXE
#include <mrd_common.h>
#include <mrd_message.h>
int mrd_lock(
const char *robot_name,
const int lock_value,
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 lock_value - This value indicates whether the the routine
should prevent or allow media removal for the robot. The
include file <mrd_common.h> defines two constants PREVENT_
REMOVAL and ALLOW_REMOVAL that will set the correct value.
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.
This routine sends a SCSI Prevent-Allow Media Removal command.
Some robots have been observed to silently ignore the command,
others will fail with an illegal request and others will do
something particular to the robot. This command is not supported
on the DSA medium-changers (TA and TF drives). SCSI defines this
a single command where the value of a single bit determines the
affect.
On some versions of TL820 firmware, the command with PREVENT_
REMOVAL will disable Move Medium commands to the outport. Other
versions will also disable Move Medium commands from the inport.
Other models will ignore the command entirely. The TL810 family
of libraries use the command to disable the front panel button
which allows opening the port door. Please refer to your robot's
documentation to see what affect this command will have.
2 – Return Values
Upon successful completion, the mrd_lock(3mrd) function returns
the value MRD_STATUS_SUCCESS. If the mrd_lock(3mrd) fails the
returned status value may be set to one of the following values.
Other values that correspond to specific SCSI errors may also be
possible, but these are the most likely.
2.1 – MRD_STATUS_PARAM
This error is returned if the robot_name or log_info arguments
are NULL pointers.
2.2 – MRD_STATUS_ROBOT_ILLEGAL_REQUEST
This is used in the mrd_lock(3mrd) code when the value is not one
of ALLOW_REMOVAL or PREVENT_REMOVAL.
It is also used for a SCSI command failure, when the ASC is set
to one of:
o 0x1A - Parameter list length error
o 0x20 - Invalid command operation code
o 0x22 - Unsupported command
o 0x24 - Illegal field in CDB
o 0x25 - Logical unit not supported
o 0x26 - Threshold parameters not supported
o 0x28 - Import or Export element accessed
o 0x2C - Command sequence error
o 0x39 - Saving parameters not supported
o 0x3D - Invalid bits in Identify message
o 0x53 - Medium removal prevented
This status is also returned when the ASC and ASCQ are zero, but
the key is five (5).
2.3 – 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
3 – Related Functions
Functions:
mrd_prevent_allow(3mrd)