---------------------------------------------------------------------- lbtest 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 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 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> > > > <= <= <= >= >= >= == == == != != != 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 */ ------_=_NextPart_000_01C1B886.62B96450-- =======================================================================