I got this from Joel Fuhrman of washington.edu. I have scripts that work,
so I know the document speaks accurately.
----------------------------------------------------------------------
lbtest
Caveat
======
This document describes how to use the lbtest tool shipped with
the ADSM server. This tool is shipped as a service aid for
diagnosing hardware problems for SCSI libraries used by ADSM.
This document describes an old version of the tool and is
slightly out of date. At this point in time lbtest and the
other service aids are not supported for customer use. (i.e. If
you find bugs in this document or lbtest, we are not obligated
to fix them).
----------------------------------------------------------------------
Invoking lbtest
The tool can be invoked as a command from the command line or
from within a shell script or REXX EXEC using this syntax:
lbtest <-f input-file> <-o output-file> <-d special-file> <-t>
<-p special-file>
options:
-f input-file This specifies the input file for batch mode.
If a file is specified, lbtest will execute in
batch mode and read input from this file.
The default for this file is lbtest.in.
-o output-file Specifies the output file.
The default for this file is lbtest.out.
-d special-file Specifies the special file value to substitute
on the "open" statement in the input file.
-p special-file Specifies the special file value to substitute
on the "passthru" statement in the input file.
-t Specifies trace will be invoked
e.g. lbtest -d /dev/lb0 -o test.output -f lbtest.mt
note.If no parameters are specified, lbtest will operate in interactive
mode.
Interactive Mode
When lbtest is invoked with no -f, it defaults to running in
interactive, or manual, mode. This allows a developer to
interactively determine the kind of testing to be done. When in
interactive mode, lbtest provides a menu of functions that can
be performed that looks like this:
Main Menu:
==========
1: Manual test
2: Batch test
9: Exit lbtest
Enter selection: 1
After selecting option 1 from the main menu, a manual test menu
appears that allows individual device driver functions to be
tested:
variables settings
=========================
special file: /dev/lb0
return_error_when_fail 1 exit_on_unexpected_result 0
manual test menu:
=================
1: set device special file
2: display symbols
3: set return error when fail
4: set exit on unexpected result
5: set buffer address
6: open 7: close
8: ioctl return element count
9: ioctl return all library inventory
10: ioctl return library inventory
11: ioctl move medium
12: ioctl audit 13: ioctl extend
14: ioctl retract 15: ioctl inquiry
16: ioctl get IOCINFO 17: ioctl return error
18: ioctl move slot to slot 19: ioctl move slot to drive
20: ioctl move drive to slot 21: ioctl move from empty
22: ioctl move to full 23: ioctl move slot to ee
24: ioctl move ee to slot 25: ioctl move from bad addr
26: ioctl move to bad addr 27: ioctl invalid ioctl
28: ioctl position to element 29: ioctl position to slot
30: ioctl library info
40: execute command
88: trace menu
99: return to main menu
Batch Mode
If a batch input file was specified with the "-f" option on
invocation, lbtest will run in batch mode, rather than
interactive. Batch input files can contain these kinds of
statements:
commands
comments
exit
if
passthru
pause
set
skip
symbols
system
type
Each type of statement is described next.
Comment
Any line beginning with "#", or any blank line, is a comment and will
be ignored.
command Statements
Device driver function is exercised by "command" entries in the
input file. Command statements must be on a single line of the
input file. The data is case sensitive, but leading or embedded
blanks are ignored.
command command-text <result-text>
This statement is used to execute a library command and to test
the command completion status for an expected result.
The "command-text" is used to specify which tape operation to
perform. The possible values for this field are described next.
open
SYNTAX:
open device-file
$D
e.g. open /dev/lb0
open $D
If the special file "$D" is specified, the -d value given on the
command line will be substituted for $D.
FUNCTION Tested:
"open" will call the device driver ddopen entry point and
attempt to open a medium changer device special file.
close
SYNTAX:
close
e.g. close
FUNCTION Tested:
"close" will call the device driver ddclose entry point and
close the medium changer device special file previously opened.
return_elem_count
SYNTAX:
return_elem_count
e.g. return_elem_count
FUNCTION Tested:
"return_elem_count" will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_RETURN_ELEMENT_COUNT and
attempt to return the number of the following types; medium
changers, drives, storage slots, and entry/exit ports. If this
command is successful, the information returned will be
displayed in the batch output file.
return_lib_inventory
SYNTAX:
return_lib_inventory dno= sno= eeno= tno=
e.g. return_lib_inventory dno=2 sno=3 eeno=1 tno=1
Where dno = number of drives
sno = number of storage slots
eeno = number of entry/exit ports
tno = number of transport elements
FUNCTION Tested:
"return_lib_inventory" will call the device driver ddioctl
entry point with an opcode of
ADSM_LBIOC_RETURN_LIBRARY_INVENTORY and attempt to return
information about various hardware components in a library. If
this command is successful, the information returned will be
displayed in the batch output file.
return_lib_inventory_all
SYNTAX:
return_lib_inventory_all
e.g. return_lib_inventory_all
FUNCTION Tested:
"return_lib_inventory_all" will call the device driver ddioctl
entry point with an opcode of
ADSM_LBIOC_RETURN_LIBRARY_INVENTORY and attempt to return
information about all the hardware components in a library. If
this command is successful, the information returned will be
displayed in the batch output file.
note return_elem_count must be issued before issuing this
return_lib_inventory_all command.
move_medium
SYNTAX:
move_medium taddr= saddr= daddr= invert=
e.g. move_medium taddr = 121 saddr = 11 daddr = 13 invert = 0
Where taddr = transport element address
saddr = source address moving from
daddr = destination address moving to
invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_medium" will call the device driver ddioctl entry point
with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to move a
data cartridge from a source element location to a destination
element location inside the library. If this command is
successful, the information returned will be displayed in the
batch output file.
move_slot_slot
SYNTAX:
move_slot_slot move_count=n invert =n
e.g. move_slot_slot move_count = 10 invert = 0
Where move_count = number of cartridge moves to execute
invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_slot_slot" will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to
move a random data cartridge from a source element location to
a destination element location inside the library. move_count
will indicate how many times the random move will perform. If
this command is successful, the information returned will be
displayed in the batch output file.
move_slot_drive
SYNTAX:
move_slot_drive invert =n
e.g. move_slot_drive invert = 0
Where invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_slot_drive will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to
move a random data cartridge from a source element location to
a drive inside the library. If this command is successful, the
information returned will be displayed in the batch output
file.
move_drive_slot
SYNTAX:
move_drive_slot invert =n
e.g. move_drive_slot invert = 0
Where invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_drive_slot will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to
move data cartridge from a drive to a random slot location
inside the library. If this command is successful, the
information returned will be displayed in the batch output
file.
move_ee_slot
SYNTAX:
move_ee_slot invert =n
e.g. move_ee_slot invert = 0
Where invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_ee_slot will call the device driver ddioctl entry point
with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to move a
data cartridge from an entry/exit port to a random slot
location inside the library. If this command is successful, the
information returned will be displayed in the batch output
file.
move_slot_ee
SYNTAX:
move_slot_ee invert =
e.g. move_slot_ee invert = 0
Where invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"move_slot_ee will call the device driver ddioctl entry point
with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to move a
random data cartridge inside the library slot to an entry/exit
port. If this command is successful, the information returned
will be displayed in the batch output file.
move_empty_slot
SYNTAX:
move_empty_slot
e.g. move_empty_slot
FUNCTION Tested:
"move_empty_slot" will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to
move from an empty slot to a destination element location
inside the library. This command should fail with completion
code DD_SOURCE_EMPTY.
move_slot_full
SYNTAX:
move_slot_full
e.g. move_slot_full
FUNCTION Tested:
"move_slot_full" will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_MOVE_MEDIUM and attempt to
move a random data cartridge to a destination element location
which is full. This command should fail with completion code
DD_DESTINATION_FULL.
audit
SYNTAX:
audit barcode =
e.g. audit barcode = 1
Where barcode = 0 do not scan cartridge barcode
1 scan barcodes
FUNCTION Tested:
"audit" will call the device driver ddioctl entry point with an
opcode of ADSM_LBIOC_LIBRARY_AUDIT and attempt to check all
elements for media and for the status of all elements. If this
command is successful, the information returned will be
displayed in the batch output file.
position_slot
SYNTAX:
position_slot move_count=n invert=n
e.g. position_slot move_count=5 invert=0
Where invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"position_slot" will call the device driver ddioctl entry point
with an opcode of ADSM_LBIOC_POSITION and attempt to position
to a random slot location inside the library. If this command
is successful, the information returned will be displayed in
the batch output file.
position_element
SYNTAX:
position_element taddr= daddr= invert=
e.g. position_element taddr = 121 daddr = 13 invert = 0
Where taddr = transport element address
daddr = destination address to position to
invert = 1 for invert, 0 for not invert
FUNCTION Tested:
"position_element" will call the device driver ddioctl entry
point with an opcode of ADSM_LBIOC_POSITION and attempt to
position to a specified element in the library. If this command
is successful, the information returned will be displayed in
the batch output file.
inquiry
SYNTAX:
inquiry
e.g. inquiry
FUNCTION Tested:
This command will call the device driver ddioctl entry point
with an operation of ADSM_LBIOC_INQUIRY. If the command is
successful, the information returned will be displayed in the
batch output file.
IOCINFO
SYNTAX:
IOCINFO
e.g. IOCINFO
FUNCTION Tested:
This command will call the device driver ddioctl entry point
with an operation of IOCINFO. If the command is successful, the
information returned will be displayed in the batch output
file.
extend
SYNTAX:
extend
e.g. extend
FUNCTION Tested:
"extend" will call the device driver ddioctl entry point with
an opcode of ADSM_LBIOC_EXTEND_RETRACT_IO_PORT and attempt to
open the Import/Export door and allow a cartridge to be either
removed or inserted. If this command is successful, the
completion code returned will be displayed the batch output
file.
retract
SYNTAX:
retract
e.g. retract
Where eaddr = entry exit port address
taddr = transport element address
FUNCTION Tested:
"retract" will call the device driver ddioctl entry point with
an opcode of ADSM_LBIOC_EXTEND_RETRACT_IO_PORT and attempt to
open the Import/Export door. If this command is successful, the
completion code returned will be displayed the batch output
file.
invalid_ioctl
This command generates a call to ddioctl with an invalid
operation code specified in the ioctl structure.
return_error_state
SYNTAX:
return_error_state
e.g. return_error_state
FUNCTION Tested:
This command will call the device driver ddioctl entry point
with an operation of ADSM_LBIOC_RETURN_ERR. If the command is
successful, the information returned will be displayed in the
batch output file.
system
SYNTAX:
system any-host-command
e.g. system tctl -f /dev/mt0 rewind
FUNCTION Tested:
This command will pass all input after the word "system" to the
host operating system for execution in a command subshell.
Supported result-text Fields
The result-text on a command statement is used to test
completion status for an expected result. Further execution of
a test case is affected by the current settings of the
"return_error_when_fail" and "exit_on_unexptected_result"
variables. These can be set using a "set" statement.
The syntax for result-text is:
< rc < n> <err < n> <cc < n>
> > >
<= <= <=
>= >= >=
== == ==
!= != !=
where:
rc = return code from the last command.
err = errno(UNIX) or status(OS/2) value for the last command.
cc = completion code from the last command.
resid = residual count from the last command.
e.g. Consider this statement in the input file:
command extend result rc == -1 err == EINVAL cc == DD_ILLEGAL_REQUEST
This means we will try to open the import/export door and expect this to
fail ith return code -1, errno EINVAL and completion code
DD_ILLEGAL_REQUEST.
Note: symbolic values or integers can be used for err and cc. See the
appendix on symbolic values for a list of those recognized.
set
This statement allows setting of variables that affect how tests are
executed. The syntax for a "set" statement is:
set variable = value
e.g. set return_error_when_fail = 1
Here are the variables that can be set:
vender_id
product_id
firmware_version_level
eeno (number of import/export ports in the library)
return_error_when_fail
Can be set to 1(true) or 0(false). A setting of "true" means
lbtest will end by returning an error at the end of the test if
any command does not produce a correct expected result as
specified in result-text.
exit_on_unexpected_result
Can be set to 1(true) or 0(false). If set to "true", the first
occurrence of an unexpected result will terminate the test.
buffer
Can be used to set a buffer address to be used for the next command
only. This allows setting invalid storage addresses.
symbols
the "symbols" statement will cause the symbols known to lbtest
to be output into the batch output file.
type
Text following the word "type" will be typed on the terminal.
This can be used to show the progress of the test or to prompt
for a subsequent pause statement.
if
This statement can be used to conditionally execute a statement.
Syntax is:
if variable-name == string statement
!=
>
<
has
!has
Where "has" means contained as a substring.
"variable-name" can be one of:
vender_id
product_id
firmware_version_level
eeno (number of import/export ports in the library)
e.g. if product_id == 'EXB-120' skip 3
Note: The test case file must contain "command inquiry" in the file
prior to execute an "if" statement. This is required so all the
possible variables will be defined and have values.
skip
This statment can be used to skip one or more subsequent statement
in the input file.
e.g. skip 3
This would skip the next 3 statements.
Note: "skip" is meant to be used mainly in conjunction with "if"
to control processing based on device characteristics contained
in the INQUIRY data.
passthru
This statment can be used to invoke a system function to pass a
command to the command interpreter, which executes the string
as an operating system command. This statement can be used to
invoke another test tool such as mttest or optest.
e.g. passthru optest -f optest.in -o optest.out
This would invoke the system function to invoke optest test tool
and start to execute optest batch job as the next sequence of
execution.
Note: A -p parameter must be specified when invoking lbtest to
indicate which device special file to be opened for passthru
test.
pause
The pause will stop until a character is typed at the terminal.
This allows for tests that require manual intervention.
exit
The statement will cause immediate termination of the batch
test and no further lines will be read from the input file.
lbtest Output File
A file showing test progress is created every time lbtest is
run. The name of this file can be controlled via the "-o"
option on the command line. The file will show each input file
line (or interactive command) processed and the results
produced by the execution. The contents of this file is meant
to be preserved as a quality record at the end of testing.
Symbolic values:
Successful = 0 (0x0)
EBUSY = 16 (0x10)
EIO = 5 (0x5)
EINVAL = 22 (0x16)
EMEDIA = 110 (0x6e)
ENODEV = 19 (0x13)
ENOMEM = 12 (0xc)
ENOSPC = 28 (0x1c)
ENOTREADY = 46 (0x2e)
ENXIO = 6 (0x6)
EPERM = 1 (0x1)
ESOFT = 111 (0x6f)
ETIMEDOUT = 78 (0x4e)
EWRPROTECT = 47 (0x2f)
ENOTTY = 25 (0x19)
IOCINFO = 65281 (0xff01)
ADSM_DDIOC_INQUIRY = 25601 (0x6401)
ADSM_DDIOC_RETURN_ERR = 25602 (0x6402)
ADSM_LBIOC_RETURN_ELEMENT_COUNT = 27649 (0x6c01)
ADSM_LBIOC_LIBRARY_INVENTORY = 27650 (0x6c02)
ADSM_LBIOC_LIBRARY_AUDIT = 27652 (0x6c04)
ADSM_LBIOC_MOVE_MEDIUM = 27651 (0x6c03)
ADSM_LBIOC_POSITION = 27655 (0x6c07)
ADSM_LBIOC_EXTEND_RETRACT_IO_PT = 27653 (0x6c05)
ADSM_LBIOC_LIBRARY_INFO = 27654 (0x6c06)
DD_UNKNOWN_ERROR = -1 (0xffffffff)
DD_NO_ERROR = 0 (0x0)
DD_NO_SENSE = 200 (0xc8)
DD_DEVICE_DRIVER_FAILURE = 201 (0xc9)
DD_EEPROM_FAILURE = 202 (0xca)
DD_MANUAL_INTERVENTION = 203 (0xcb)
DD_RECOVERED_ERROR = 204 (0xcc)
DD_SCSI_ADAPTER_ERROR = 205 (0xcd)
DD_SCSI_ERROR = 206 (0xce)
DD_ILLEGAL_REQUEST = 207 (0xcf)
DD_COMMAND_ABORTED = 208 (0xd0)
DD_HARDWARE_MICROCODE = 209 (0xd1)
DD_UNIT_ATTENTION = 210 (0xd2)
DD_CARTRIDGE_ENTRY_FAILURE = 300 (0x12c)
DD_CARTRIDGE_LOAD_FAILURE = 301 (0x12d)
DD_CARTRIDGE_IN_FAILED_DRIVE = 302 (0x12e)
DD_CAROUSEL_NOT_LOADED = 303 (0x12f)
DD_CHANGER_FAILURE = 304 (0x130)
DD_DRIVE_FAILURE = 305 (0x131)
DD_DRIVE_OR_MEDIA_FAILURE = 306 (0x132)
DD_ENTRY_EXIT_FAILURE = 307 (0x133)
DD_ENTRY_EXIT_NOT_PRESENT = 308 (0x134)
DD_LIBRARY_AUDIT = 309 (0x135)
DD_LIBRARY_FULL = 310 (0x136)
DD_MEDIA_EXPORT = 311 (0x137)
DD_SLOT_FAILURE = 312 (0x138)
DD_SLOT_OR_MEDIA_FAILURE = 313 (0x139)
DD_SOURCE_EMPTY = 314 (0x13a)
DD_DESTINATION_FULL = 315 (0x13b)
DD_END_PHYSICAL_MEDIA = 400 (0x190)
DD_MEDIA_BLANK = 401 (0x191)
DD_MEDIA_CORRUPTED = 402 (0x192)
DD_MEDIA_FAILURE = 403 (0x193)
DD_MEDIA_INCOMPATIBILITY = 404 (0x194)
DD_SECTOR_RELOCATION = 405 (0x195)
DD_SECTOR_OUT_OF_RANGE = 406 (0x196)
DD_WRITE_PROTECT = 407 (0x197)
DD_CLEAN_MEDIA = 408 (0x198)
DD_MEDIA_FAULT = 409 (0x199)
DD_CLEANING_COMPLETE = 410 (0x19a)
DD_LOGICAL_END_OF_MEDIA = 411 (0x19b)
DD_MEDIA_NOT_PRESENT = 412 (0x19c)
DD_BEGINNING_OF_MEDIA = 413 (0x19d)
DD_ERASE_FAILURE = 414 (0x19e)
DD_WRITE_TO_WRITTEN_WORM = 415 (0x19f)
DD_WRONG_LENGTH_BLOCK = 416 (0x1a0)
Appendix - Symbolic Values
These symbolic values can be used for err:
EBUSY
EIO
EINVAL
EMEDIA
ENODEV
ENOMEM
ENOSPC
ENOTREADY
ENXIO
EPERM
ESOFT
ETIMEDOUT
EWRPROTECT
These symbolic values can be used for compcode:
DD_UNKNOWN_ERROR = -1, /* -1 */
DD_NO_ERROR = 0, /* 0 */
DD_NO_SENSE = 200, /* 200 */
DD_DEVICE_DRIVER_FAILURE, /* 201 */
DD_EEPROM_FAILURE, /* 202 */
DD_MANUAL_INTERVENTION, /* 203 */
DD_RECOVERED_ERROR, /* 204 */
DD_SCSI_ADAPTER_ERROR, /* 205 */
DD_SCSI_ERROR, /* 206 */
DD_ILLEGAL_REQUEST, /* 207 */
DD_COMMAND_ABORTED, /* 208 */
DD_HARDWARE_MICROCODE, /* 209 */
DD_UNIT_ATTENTION, /* 210 */
DD_CARTRIDGE_ENTRY_EXIT = 300, /* 300 */
DD_CARTRIDGE_LOAD_FAILURE, /* 301 */
DD_CARTRIDGE_IN_FAILED_DRIVE, /* 302 */
DD_CAROUSEL_NOT_LOADED, /* 303 */
DD_CHANGER_FAILURE, /* 304 */
DD_DRIVE_FAILURE, /* 305 */
DD_DRIVE_OR_MEDIA_FAILURE, /* 306 */
DD_ENTRY_EXIT_FAILURE, /* 307 */
DD_ENTRY_EXIT_NOT_PRESENT, /* 308 */
DD_LIBRARY_AUDIT, /* 309 */
DD_LIBRARY_FULL, /* 310 */
DD_MEDIA_EXPORT, /* 311 */
DD_SLOT_FAILURE, /* 312 */
DD_SLOT_OR_MEDIA_FAILURE, /* 313 */
DD_SOURCE_EMPTY, /* 314 */
DD_DESTINATION_FULL, /* 315 */
DD_END_PHYSICAL_MEDIA = 400, /* 400 */
DD_MEDIA_BLANK, /* 401 */
DD_MEDIA_CORRUPTED, /* 402 */
DD_MEDIA_FAILURE, /* 403 */
DD_MEDIA_INCOMPATIBILITY, /* 404 */
DD_SECTOR_RELOCATION, /* 405 */
DD_SECTOR_OUT_OF_RANGE, /* 406 */
DD_WRITE_PROTECT, /* 407 */
DD_CLEAN_MEDIA, /* 408 */
DD_MEDIA_FAULT, /* 409 */
DD_CLEANING_COMPLETE, /* 410 */
DD_LOGICAL_END_OF_MEDIA, /* 411 */
DD_MEDIA_NOT_PRESENT, /* 412 */
DD_BEGINNING_OF_MEDIA, /* 413 */
DD_ERASE_FAILURE, /* 414 */
DD_WRITE_TO_WRITTEN_WORM, /* 415 */
DD_WRONG_LENGTH_BLOCK, /* 416 */
DD_OPEN_READ_ONLY, /* 417 */
DD_OPEN_WRITE_ONLY, /* 418 */
DD_MEDIUM_SCAN_FAILED /* 419 */
