Optical IOCtl Device Driver Test Tool

This chapter explains how to use the DDTT to test optical devices by executing removable DASD and optical-oriented test scripts.

Overview
Optical functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with optical device drivers. The test environment is defined by the Device Driver Test Tool (DDTT) and each test is written as a DDTT script using Global and optical grammars. See Device Driver Test Tool (DDTT) for a description of the DDTT. The tests described herein give the user a repeatable set of scripts for verifying disk and diskette functions. They may also be used as examples for creating additional specialized test cases. As the DDTT parses and executes each test script, it simultaneously creates a disk log file that timestamps the activity and logs each script command. If the command initiates an API call, then the result of the command is logged, be it failure with a return code or success with possible returned data. If the script fails to complete, the log, up to the point of failure, is available for diagnosis. These tests can be used to verify correct interaction between the optical device and the following OS/2 components: Optical device support is currently limited to media that are blocked for 512 bytes (a file system limitation).
 * DOSDevIOCtl API interface
 * FAT file system
 * OPTICAL.DMD, device manager
 * SCSI Adapter device drivers
 * Non-SCSI Adapter device drivers

Installation
This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run optical test suites. The following procedure describes installation for running test cases: [C:\]md toptical [C:\]cd toptical [C:\toptical]copy e:\ddk\testcert\storage\function\dasd\* [C:\toptical]copy e:\ddk\testcert\general\ddtt\* The following DDTT files are required for execution of optical scripts:
 * 1) Copy the component files from the Device Driver Kit for OS/2 CD-ROM to the hard drive. All files should reside in a common directory, such as \TOPTICAL. If the target directory is C:\TOPTICAL and the E: drive contains the information from the Device Driver Kit for OS/2, then use the following commands to copy the optical test suite:
 * 1) Add C:\TOPTICAL to the LIBPATH and PATH in the CONFIG.SYS file.
 * 2) Reboot your machine so the new LIBPATH entry takes effect.
 * DDTT.EXE
 * DDTT.DLL
 * GLOBAL.DLL
 * GLOBAL.GRA
 * DDTOPTI.DLL
 * OPTI.GRA

Test-Case Execution
Test case scripts are driven by the DDTT. The DDTT can be initiated via an OS/2 command line or from a batch file or REXX statement: [C:\TOPTICAL]DDTT OPTISTD.SCR The DDTT creates a Presentation Manager thread window that consists of: The DDTT optical tests must be executed on a directly-attached optical device. These tests will not work when executed against an optical device accessed by way of a network connection.
 * a multi-line, scrolled output field for logging script progress
 * a single-line entry field for operator input
 * a single-line text output field for script-initiated prompts and messages

Optical IOCtl Test Grammar Function Calls
The following is a list of Optical IOCtl Test Grammar Function Calls:
 * DASD_OPEN
 * DASD_CLOSE
 * LOCK_LOGICAL
 * UNLOCK_LOGICAL
 * QUERY_LOCK
 * GET_LOGICAL_PARAMS
 * BLOCK_REMOVABLE
 * REDETERMINE_MEDIA
 * READ_LOGICAL
 * WRITE_LOGICAL
 * VERIFY_LOGICAL
 * FORMAT_TRACK
 * BEGIN_FORMAT
 * LOCK_DOOR
 * UNLOCK_DOOR
 * EJECT_MEDIA
 * QUERY_SUPPORT
 * SCSI_INQUIRY
 * SCSI_MODE_SENSE
 * READ_FILE
 * WRITE_FILE
 * SET_DEVICEPARAMS
 * CHECKRETURN
 * CHECKVALUE

DASD_OPEN
This function opens the optical device for processing. An optical cartridge must be mounted for successful completion.


 * Input Parameter Keywords


 * Output Parameter Keywords

None.
 * Logged Data

DASD_CLOSE
This function closes the processing connection to the optical device.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Output Parameter Keywords

None.
 * Logged Data

LOCK_LOGICAL
Category 8h Function 00h - Lock Drive This function logically locks the optical device for exclusive processing.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

UNLOCK_LOGICAL
Category 8h Function 01h - Unlock Drive This function releases a logical lock to the optical device.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

QUERY_LOCK
Category 8h Function 66h - Get Lock Status This function indicates if the drive is locked with or without media in it.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * PRESENCE           |NUM                 |Media presence flag |
 * LOCKCODE           |NUM                 |2-bit lock code     |
 * OPRC               |NUM                 |Function return code|
 * LOCKCODE           |NUM                 |2-bit lock code     |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

Lock status and Lock/Unlock/Eject command support statement Media presence status
 * Logged Data

GET_LOGICAL_PARAMS
Category 8h Function 63h - Query Device Parameters This function gets the logical parameters for the addressed drive. BIOS parameter block data may be a generic default for the optical drive.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * CLUSTERSIZE        |NUM                 |Cluster size in     |
 * |                   |sectors             |
 * FATCOUNT           |NUM                 |Number of FATs      |
 * ROOTCOUNT          |NUM                 |Number of root      |
 * |                   |directory entries   |
 * SECTORCOUNT        |NUM                 |Number of sectors   |
 * |                   |(small disk)        |
 * FATSIZE            |NUM                 |Number of sectors   |
 * |                   |per FAT             |
 * TRACKSIZE          |NUM                 |Size of tracks      |
 * HEADCOUNT          |NUM                 |Number of heads     |
 * CYLINDER           |NUM                 |Number of physical  |
 * |                   |drive cylinders     |
 * HIDDEN             |NUM                 |Number of hidden    |
 * |                   |sectors             |
 * RESERVED           |NUM                 |Number of reserved  |
 * |                   |sectors             |
 * LGSECTORCOUNT      |NUM                 |Number of sectors   |
 * |                   |(large disk)        |
 * $SECTORCOUNT       |NUM                 |Applicable sector   |
 * |                   |count               |
 * DEVICETYPE         |NUM                 |Device layout code  |
 * MEDIATYPE          |NUM                 |Media descriptor    |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes)             |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * OPRC               |NUM                 |Function return code|
 * LGSECTORCOUNT      |NUM                 |Number of sectors   |
 * |                   |(large disk)        |
 * $SECTORCOUNT       |NUM                 |Applicable sector   |
 * |                   |count               |
 * DEVICETYPE         |NUM                 |Device layout code  |
 * MEDIATYPE          |NUM                 |Media descriptor    |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes)             |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * OPRC               |NUM                 |Function return code|
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes)             |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|


 * Logged Data (where defined)
 * Size of sectors
 * Size of clusters
 * Fat count
 * Root directory size
 * Number of sectors per FAT
 * Sectors per track
 * Reserved sector count
 * Hidden sector count
 * Number of heads
 * Total sector count
 * Number of cylinders
 * Media descriptor
 * Device attributes

BLOCK_REMOVABLE
Category 8h Function 20h - Block Removable This function is used to determine if the media is removable or fixed.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * REMOVABLE          |NUM                 |1 if true; 0 if     |
 * |                   |false               |
 * REMOVABLE          |NUM                 |1 if true; 0 if     |
 * |                   |false               |

Removable Media Returns a byte that specifies if the media is removable or not. Where:
 * Logged Data
 * 0 = Removable media
 * 1 = Nonremovable media

REDETERMINE_MEDIA
Category 8h Function 02h - Redetermine Media This function redetermines the media for the optical device.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

READ_LOGICAL
Category 8h Function 64h - Read Track This function reads sectors from an optical drive.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * HEAD               |NUM                 |The target head     |
 * |                   |value (only 0 valid)|
 * CYLINDER           |NUM                 |The target cylinder |
 * |                   |value               |
 * SECTORSTART        |NUM                 |The target start    |
 * |                   |sector value        |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |be read             |
 * $BUFFER            |STRING              |Buffer name         |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |be read             |
 * $BUFFER            |STRING              |Buffer name         |
 * |                   |be read             |
 * $BUFFER            |STRING              |Buffer name         |
 * $BUFFER            |STRING              |Buffer name         |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * BUFFER             |NUM                 |Pointer to Read     |
 * |                   |buffer              |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

WRITE_LOGICAL
Category 8h Function 44h - Write Track This function writes sectors to an optical device. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer. The sector count is defaulted to the Read buffer size.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * HEAD               |NUM                 |The target head     |
 * |                   |value (only 0 valid)|
 * CYLINDER           |NUM                 |The target cylinder |
 * |                   |value               |
 * SECTORSTART        |NUM                 |The target start    |
 * |                   |sector value        |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * $BUFFER            |STRING              |Name of an existing |
 * |                   |Read buffer         |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * $BUFFER            |STRING              |Name of an existing |
 * |                   |Read buffer         |
 * $BUFFER            |STRING              |Name of an existing |
 * |                   |Read buffer         |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

VERIFY_LOGICAL
Category 8h Function 65h - Verify Track This function verifies sectors on an optical drive.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * HEAD               |NUM                 |The target head     |
 * |                   |value (only 0 valid)|
 * CYLINDER           |NUM                 |The target cylinder |
 * |                   |value               |
 * SECTORSTART        |NUM                 |The target start    |
 * |                   |sector              |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |verify              |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |verify              |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |verify              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

FORMAT_TRACK
Category 8h Function 45h - Format Track This function formats and verifies a track.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * TRACKSIZE          |NUM                 |Track size in       |
 * |                   |sectors             |
 * TRACKSTART         |NUM                 |Starting track      |
 * |                   |number              |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * LGSECTORCOUNT      |NUM                 |Maximum number of   |
 * |                   |media sectors       |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * LGSECTORCOUNT      |NUM                 |Maximum number of   |
 * |                   |media sectors       |
 * LGSECTORCOUNT      |NUM                 |Maximum number of   |
 * |                   |media sectors       |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

BEGIN_FORMAT
Category 8h Function 04h - Format Track This function provides initialization for a format command.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

LOCK_DOOR
Category 80h Function 40h - Lock/Unlock Door This function locks the drive door.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

UNLOCK_DOOR
Category 80h Function 40h - Lock/Unlock Door This function unlocks the drive door.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

EJECT_MEDIA
Category 80h Function 41h - Eject Media This function ejects the cartridge from the drive. It should fail if the drive is locked.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

QUERY_SUPPORT
Category 80h Function 60h - Query Drive Support This function queries the optical drive support parameters.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|


 * Logged Data
 * Signature
 * Release level
 * ROM level
 * Hardware level
 * Format time

SCSI_INQUIRY
Category 80h Function 4Fh - Write Device Control String This function constructs a SCSI Inquiry command for the optical device manager to relay to the SCSI device driver. The Device ID string will be returned to the DDTT. Support is limited to SCSI connections.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

Device type Device product ID Device vendor ID
 * Logged Data

SCSI_MODE_SENSE
Category 80h Function 4Fh - Write Device Control String This function constructs a SCSI Mode Sense command for the optical device manager to relay to the SCSI device driver. Mode type code will be returned to the DDTT. Support is limited to SCSI connections.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |File handle for     |
 * |                   |optical device being|
 * |                   |tested              |
 * |                   |tested              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * MEDIACODE          |NUM                 |Media type: 1=OROM, |
 * |                   |3=MO, 5=PROM        |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

Media type
 * Logged Data

READ_FILE
This function reads from an optical drive file.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * FILENAME           |STRING              |The qualified name  |
 * |                   |of the file to read |
 * BYTESTART          |NUM                 |The byte offset     |
 * |                   |within the file     |
 * BYTECOUNT          |NUM                 |The number of bytes |
 * |                   |to read             |
 * $BUFFER            |STRING              |Name of the Read    |
 * |                   |buffer              |
 * |                   |to read             |
 * $BUFFER            |STRING              |Name of the Read    |
 * |                   |buffer              |
 * |                   |buffer              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * BUFFER             |NUM                 |Read buffer         |
 * |                   |reference           |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

WRITE_FILE
This function writes to an optical file. You can only perform a write after the DDTT script has done a read. You must use the same buffer. You cannot alter the contents of this buffer.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * FILENAME           |STRING              |The qualified name  |
 * |                   |of the target file  |
 * BYTESTART          |NUM                 |The byte offset     |
 * |                   |within the file     |
 * $BUFFER            |STRING              |Name of the Read    |
 * |                   |buffer              |
 * $BUFFER            |STRING              |Name of the Read    |
 * |                   |buffer              |
 * |                   |buffer              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

SET_DEVICEPARAMS
Category 8h Function 43h - Set Device Parameters This function sets the device parameters. Input parameters are most easily initialized by issuing a GET_LOGICAL_PARAMS.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |optical device being|
 * |                   |tested              |
 * SECTORSIZE         |NUM                 |Sector size in bytes|
 * CLUSTERSIZE        |NUM                 |Cluster size in     |
 * |                   |sectors             |
 * FATCOUNT           |NUM                 |Number of FATs      |
 * ROOTCOUNT          |NUM                 |Number of root      |
 * |                   |directory entries   |
 * HIDDEN             |NUM                 |Number of hidden    |
 * |                   |sectors             |
 * RESERVED           |NUM                 |Number of reserved  |
 * |                   |sectors             |
 * LGSECTORCOUNT      |NUM                 |Number of sectors   |
 * |                   |(large disk)        |
 * SECTORCOUNT        |NUM                 |Number of sectors   |
 * |                   |(small disk)        |
 * FATSIZE            |NUM                 |Number of sectors   |
 * |                   |per FAT             |
 * TRACKSIZE          |NUM                 |Size of the tracks  |
 * |                   |on the specified    |
 * |                   |device              |
 * HEADCOUNT          |NUM                 |Number of heads on  |
 * |                   |the physical disk   |
 * CYLINDER           |NUM                 |The number of       |
 * |                   |cylinders           |
 * MEDIATYPE          |NUM                 |Media descriptor    |
 * DEVICETYPE         |NUM                 |Device layout code  |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes; 0=no)       |
 * |                   |device              |
 * HEADCOUNT          |NUM                 |Number of heads on  |
 * |                   |the physical disk   |
 * CYLINDER           |NUM                 |The number of       |
 * |                   |cylinders           |
 * MEDIATYPE          |NUM                 |Media descriptor    |
 * DEVICETYPE         |NUM                 |Device layout code  |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes; 0=no)       |
 * ADDR16             |NUM                 |16MB size flag      |
 * |                   |(1=greater)         |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes; 0=no)       |
 * HARDDISK           |NUM                 |Hard disk flag      |
 * |                   |(1=yes; 0=no)       |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * OPRC               |NUM                 |Function return code|
 * OPRC               |NUM                 |Function return code|

None.
 * Logged Data

CHECKRETURN
Check Return Code Diagnostic Function This function verifies that the return code from a previous function is equal to a given value. The function is used for error testing to verify expected return codes. It is assumed that a previous function has set the OPRC parameter. $RC is set by the script author to the expected value.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * $RC                |NUM                 |The expected return |
 * |                   |code                |
 * |                   |code                |


 * Logged Data
 * Message stating the result of the comparison - either failure or success.

CHECKVALUE
Check Parameter Value Diagnostic Function This function verifies that a parameter, returned by a previous DASD function, is equal to a given numeric value. $PARM must be explicitly equated to the parameter being tested and $EXPECT set to the expected value.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * $PARM              |NUM                 |The returned        |
 * |                   |parameter value     |
 * $EXPECT            |NUM                 |The expected value  |
 * $EXPECT            |NUM                 |The expected value  |
 * $EXPECT            |NUM                 |The expected value  |

Message stating the result of the comparison - either failure or success.
 * Logged Data

Description of Test Cases
Each of the optical test cases can be executed by invoking the DDTT from either a command line, a batch file, or a REXX file. Test scripts are described below. The user is free to create additional tests or construct multi-threaded test cases after becoming familiar with the DDTT and the optical grammar files.

Test scripts generally start by opening to the optical drive and closing at completion. File operations do not require Open or Close operations as they do this internally. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When lock status or device parameters are queried, the data is written to the DDTT's scroll output window and to the log file. Log files can be examined with a text editor after the test case has completed.

Optical cartridge sectors are addressed by cylinder, head, and sector. Head value is currently defined only for a value of 0. The maximum value for the other parameters can be found with GET_LOGICAL_PARAMS.

Test scripts currently address drives configured as removable. If an optical drive is configured as non-removable, then the fixed-disk test suite would be appropriate.


 * OPTISTD.SCR
 * This script exercises all optical device related API commands, except those for file I/O. An optical cartridge supporting read and write must be mounted in the drive.


 * OPTIFILE.SCR
 * This script exercises optical device file read and write commands. An optical cartridge supporting read and write must be mounted in the drive. Since file I/O is supported, the cartridge must be formatted and this script must be copied to it in order to serve as a sample file.


 * OPTIERR.SCR
 * This script exercises the device driver's ability to detect errors related to invalid handle, device-not-ready, and invalid sequence conditions for an optical drive. It requires an optical cartridge to be mounted.


 * OPTIERR2.SCR
 * This script exercises the device driver's ability to detect errors related to invalid head/cylinder/sector values for an optical drive. It requires an optical cartridge to be mounted.

Evaluation of Test Case Results
Standard (non-error) test cases are expected to succeed and there should be no ERROR statements in the logs. SCSI Inquiry and Mode Sense commands will fail if the drive is not connected to a SCSI adapter.

Error test cases will have many ERROR statements but should have no failure statements. Failure statements indicate that an expected error code was not received.

Test case logs need to be examined to verify that data is returned as expected. Not all returned data is automatically checked. Script comments will note what data is expected.