CD-ROM Device Driver Test Tool

This chapter explains how to use the DDTT to test a CD-ROM Device Driver by executing CD-ROM-oriented test scripts.

Overview
CD-ROM functional verification tests exercise the Application Program Interfaces (APIs) - mainly DosDevIOCtl variations - that interface with CD- ROM 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 CD-ROM 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 CD-ROM 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 CD-ROM device and the following OS/2 components:
 * DOSDevIOCtl API interface
 * CDFS file system
 * OS2CDROM.DMD and OS2ASPI.DMD device managers
 * CDROM adapter (.ADD) device drivers
 * CDROM filter (.FLT) device drivers

Installation
This CD-ROM contains the executables, libraries, grammars, and test cases necessary to run CD-ROM test suites.

The following procedure describes installation for running test cases. [C:\]md tstcdrom [C:\]cd tstcdrom [C:\tstcdrom]copy e:\ddk\testcert\storage\function\cdrom\* [C:\tstcdrom]copy e:\ddk\testcert\general\ddtt\*
 * 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 \TSTCDROM. If the target directory is C:\TSTCDROM and the E: drive contains the information from the Device Driver Kit for OS/2, then use the following commands to copy the CD-ROM test suite:
 * 1) Add C:\TSTCDROM to the LIBPATH and PATH in the CONFIG.SYS file.
 * 2) Reboot your machine so the new LIBPATH entry takes effect.

The following DDTT files are required for execution of CD-ROM scripts:
 * DDTT.EXE
 * DDTT.DLL
 * GLOBAL.DLL
 * GLOBAL.GRA
 * DDTCDROM.DLL
 * CDROM.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:\TSTCDROM]DDTT XADATA.SCR

The DDTT creates a Presentation Manager thread window that consists of:
 * 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

The DDTT CD-ROM tests must be executed on a directly-attached CD-ROM device. These tests will not work when executed against a CD-ROM device accessed by way of a network connection.

DDTT CD-ROM Test Grammar Function Calls
Test scripts are ASCII text files containing calls to DDTT commands, global functions, and device-specific functions (the latter two are defined by grammar files). The following is a list of the CD-ROM-specific grammar functions:
 * CDROM_OPEN
 * CDROM_CLOSE
 * CDROM_GETDEVPARAMS
 * CDROM_QUERYDRIVELETTER
 * CDROM_EJECT
 * CDROM_LOCKDOOR
 * CDROM_UNLOCKDOOR
 * CDROM_QUERYAUDIODISKINFO
 * CDROM_QUERYAUDIOSTATUS
 * CDROM_QUERYDRIVERINFO
 * CDROM_QUERYSECTORINFO
 * CDROM_QUERYVOLUMESIZE
 * CDROM_QUERYAUDIOTRACKINFO
 * CDROM_QUERYSTATUS
 * CDROM_QUERYUPC
 * CDROM_QUERYCHANINFO
 * CDROM_QUERYAUDIOCHANINFO
 * CDROM_AUDIOCHANINFO
 * CDROM_RESET
 * CDROM_STOPAUDIO
 * CDROM_RESUMEAUDIO
 * CDROM_PLAYAUDIO
 * CDROM_SEEK
 * CDROM_DRIVELOCATION
 * CDROM_READFILE
 * CDROM_READ2048
 * CDROM_READ2352
 * CDROM_READPRE2352
 * CDROM_CHECKSECTOR
 * CDROM_CHECKRETURN
 * CDROM_CHECKVALUE

CDROM_OPEN
This function opens the CD-ROM.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DEVICENAME         |STRING              |Drive letter of     |
 * |                   |CD-ROM              |
 * |                   |CD-ROM              |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Returned drive      |
 * |                   |handle              |
 * $DRIVES            |NUM                 |Number of CD-ROM    |
 * |                   |drives in the system|
 * |                   |being tested        |
 * $FIRSTCD           |NUM                 |First CD-ROM drive  |
 * |                   |number Where:       |
 * |                   |00=Drive a          |
 * |                   |01=Drive b          |
 * |                   |02=Drive c, etc.    |
 * |                   |00=Drive a          |
 * |                   |01=Drive b          |
 * |                   |02=Drive c, etc.    |

None.
 * Logged Data

CDROM_CLOSE
This function closes the CD-ROM.


 * Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |

None.
 * Output Parameter Keywords

None.
 * Logged Data

CDROM_GETDEVPARAMS
Category 08h Function 63h - Get Device Parameters This function returns the device parameters including the BIOS parameter block (BPB).


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * BYTESPERSECTOR     |NUM                 |Sector size in bytes|
 * LARGESECTORS       |NUM                 |Media sector count. |
 * DEVICETYPE         |NUM                 |Device code         |
 * CDRC               |NUM                 |Function return code|
 * DEVICETYPE         |NUM                 |Device code         |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

Media sector size in bytes Media sector count Device type code (should be 7 for CD-ROM)
 * Logged Data

CDROM_QUERYDRIVELETTER
Category 82h Function 60h - Return Drive-Letter Information This function queries the CD-ROM drive letter from the system.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |

None.
 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * $DRIVES            |NUM                 |Number of CD-ROM    |
 * |                   |drives in the system|
 * |                   |being tested        |
 * $FIRSTCD           |NUM                 |Drive number for    |
 * |                   |CD-ROM drive in the |
 * |                   |system. Where:      |
 * |                   |00=Drive a          |
 * |                   |01=Drive b          |
 * |                   |02=Drive c, etc.    |
 * CDRC               |NUM                 |Function return code|
 * |                   |02=Drive c, etc.    |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * Logged Data

CDROM_EJECT
Category 80h Function 44h - Eject Disc This function ejects the CD-ROM disc from the CD-ROM drive.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

None.
 * Logged Data

CDROM_LOCKDOOR
Category 80h Function 46h - Lock Door This function locks the CD-ROM drive door.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

None.
 * Logged Data

CDROM_UNLOCKDOOR
Category 80h Function 46h - Unlock Door This function unlocks the CD-ROM drive door.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

None.
 * Logged Data

CDROM_QUERYAUDIODISKINFO
Category 81h Function 61h - Return Audio-Disc Information This function returns the first and last track numbers as well as the Redbook address for the lead-out track.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * HIGHTRACK          |NUM                 |Highest track number|
 * LOWTRACK           |NUM                 |Lowest track number |
 * CDRC               |NUM                 |Function return code|
 * LOWTRACK           |NUM                 |Lowest track number |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|


 * Logged Data
 * Highest track number
 * Lowest track number
 * Starting point of lead-out track

CDROM_QUERYAUDIOSTATUS
Category 81h Function 65h - Audio-Status Information This function returns the audio status, and the starting and ending locations of the last play or next resume.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * PAUSE              |NUM                 |Pause bit Where:    |
 * |                   |0=not paused        |
 * |                   |1=paused            |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|


 * Logged Data
 * Audio status bits
 * Starting location of last play audio or resume audio command
 * Ending location of last play audio or resume audio command

CDROM_QUERYDRIVERINFO
Category 80h Function 61h - Identify CD-ROM Driver This function identifies the device driver as a valid CD-ROM driver.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

CD-ROM device driver ID
 * Logged Data

CDROM_QSECTORINFO
Category 80h Function 63h - Return Sector Size This function returns the disc sector size in bytes. (Defaulted to 2MB.)


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * SECTORSIZE         |NUM                 |Bytes per sector    |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

Sector size in bytes
 * Logged Data

CDROM_QUERYVOLUMESIZE
Category 80h Function 78h - Return Volume Size This function returns the total number of readable sectors on the disc.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * VOLSIZE            |NUM                 |Disc sector count   |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

Volume size in sectors
 * Logged Data

CDROM_QUERYAUDIOTRACKINFO
Category 81h Function 62h - Return Audio-Track Information This function returns, for a specified track, the Redbook address for the starting point plus track-control information.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * TRACK              |NUM                 |Track number        |
 * TRACK              |NUM                 |Track number        |
 * TRACK              |NUM                 |Track number        |


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

Starting point of track Track-control information
 * Logged Data

CDROM_QUERYSTATUS
Category 80h Function 60h - Device Status

This function returns the device driver status codes in a double word. Hardware disc/door status and software support are indicated.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * STATUS             |NUM                 |Status bits         |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

CD-ROM drive status information
 * Logged Data

CDROM_QUERYUPC
Category 80h Function 79h - Get UPC This function returns the UPC code for the CD-ROM disc.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

Control and ADR byte Universal product code Frame
 * Logged Data

CDROM_QUERYCHANINFO
Category 81h Function 63h - Return Audio Q Channel Information

This function reads and returns the most current address information from the Q channel. Data returned includes current track and running time for disc and track.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * TRACK              |NUM                 |Current track number|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

Control and ADR byte Track number Index Running time within a track, minutes Running time within a track, seconds Running time within a track, frames Running time within a disc, minutes Running time within a disc, seconds Running time within a disc, frames
 * Logged Data

CDROM_QUERYAUDIOCHANINFO
Category 81h Function 60h - Return Audio Channel Control Information

This function returns the current settings of the audio channel controls.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


 * Output Parameter Keywords
 * Keyword            |Type                |Description         |
 * INCHAN1            |NUM                 |Input channel for   |
 * |                   |output 0            |
 * INCHAN2            |NUM                 |Input channel for   |
 * |                   |output 1            |
 * OUTVOL1            |NUM                 |Volume for output 0 |
 * OUTVOL2            |NUM                 |Volume for output 1 |
 * CDRC               |NUM                 |Function return code|
 * OUTVOL1            |NUM                 |Volume for output 0 |
 * OUTVOL2            |NUM                 |Volume for output 1 |
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|
 * CDRC               |NUM                 |Function return code|

Input channel for output channel 0 Volume control for output channel 0 Input channel for output channel 1 Volume control for output channel 1
 * Logged Data

CDROM_AUDIOCHANINFO
Category 81h Function 40h - Set Audio Channel Controls

This function sets the audio channel controls.

EXAMPLE: VOL1 = (0-255) VOL2 = (0-255) INPUT1 = 0 INPUT2 = 1
 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * VOL1               |NUM                 |Volume for channel 0|
 * VOL2               |NUM                 |Volume for channel 1|
 * INPUT1             |NUM                 |Input channel for   |
 * |                   |output 0            |
 * INPUT2             |NUM                 |Input channel for   |
 * |                   |output 1            |
 * INPUT1             |NUM                 |Input channel for   |
 * |                   |output 0            |
 * INPUT2             |NUM                 |Input channel for   |
 * |                   |output 1            |
 * |                   |output 1            |


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

None.
 * Logged Data

CDROM_RESET
Category 80h Function 40h - Reset Drive

This function resets and reinitializes the drive and controller.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

None.
 * Logged Data

CDROM_STOPAUDIO
Category 81h Function 51h - Stop Audio

This function cancels any active play request.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * |                   |CD-ROM drive        |


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

None.
 * Logged Data

CDROM_RESUMEAUDIO
Category 81h Function 52h - Resume Audio

This function resumes playing audio after play has been interrupted by the stop audio command.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description
 * DRIVEHANDLE        |NUM                 |Drive handle for
 * |                   |CD-ROM drive
 * |                   |CD-ROM drive


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

None.
 * Logged Data

CDROM_PLAYAUDIO
Category 81h Function 50h - Play Audio

This function plays selected audio sectors. Sector interval may be designated using logical block or Redbook addressing (parameters for each set are mutually exclusive).

EXAMPLES: Logical Block: ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000 Redbook: ADDRESSMODE=REDBOOK TIMESTART=02:45:00 TIMESTOP=05:55:00
 * Required Input Parameter Keywords


 * Output Parameter Keywords

None.
 * Logged Data

CDROM_SEEK
Category 80h Function 50h - Seek

This function moves the read head to the specified sector. The function can operate in either address mode by specifying a sector-start value or a time-start value (mutually exclusive).

EXAMPLES: Logical Block ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 Redbook ADDRESSMODE=REDBOOK TIMESTART=02:45:00
 * Required Input Parameter Keywords
 * Keyword       |Type       |Description
 * DRIVEHANDLE   |NUM        |Drive handle for CD-ROM drive
 * ADDRESSMODE   |STRING     |Addressing mode:
 * |          |LOGICAL BLOCK or REDBOOK
 * SECTORSTART   |NUM        |If using logical block
 * TIMESTART     |STRING     |If using Redbook
 * SECTORSTART   |NUM        |If using logical block
 * TIMESTART     |STRING     |If using Redbook
 * TIMESTART     |STRING     |If using Redbook
 * TIMESTART     |STRING     |If using Redbook


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

None.
 * Logged Data

CDROM_DRIVELOCATION
Category 80h Function 70h - Location of Drive Head

This function returns the current head location in units valid for the requested addressing mode.

EXAMPLES: Logical Block ADDRESSMODE=LOGICALBLOCK Redbook ADDRESSMODE=REDBOOK
 * Required Input Parameter Keywords
 * Keyword            |Type                |Description
 * DRIVEHANDLE        |NUM                 |Drive handle for
 * |                   |CD-ROM drive
 * ADDRESSMODE        |STRING              |Addressing mode:
 * |                   |LOGICAL BLOCK or
 * |                   |REDBOOK
 * |                   |LOGICAL BLOCK or
 * |                   |REDBOOK


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

Location of drive head
 * Logged Data

CDROM_READFILE
DOS READ FILE

This function locates a selected file on the CD-ROM disc and reads in the specified number of bytes at the specified offset.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * FILENAME           |STRING              |Name of file to read|
 * BYTESTART          |NUM                 |Starting byte to    |
 * |                   |read                |
 * BYTECOUNT          |NUM                 |Number of bytes to  |
 * |                   |read                |
 * |                   |read                |
 * BYTECOUNT          |NUM                 |Number of bytes to  |
 * |                   |read                |
 * |                   |read                |


 * Optional Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * BUFFER             |STRING              |Buffer name         |
 * BUFFER             |STRING              |Buffer name         |


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

Byte(s) read
 * Logged Data

CDROM_READ2048
DOS READ

This function reads 2048 bytes of each specified sector into the data buffer. The number of sectors to read is passed as input. Address mode is defaulted (and limited) to Logical Block.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * SECTORSTART        |NUM                 |Starting sector to  |
 * |                   |read                |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |read                |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |read                |
 * |                   |read                |


 * Optional Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * BUFFER             |STRING              |Buffer name         |
 * BUFFER             |STRING              |Buffer name         |

EXAMPLE: Logical Block BUFFER=ALPHA SECTORSTART=20000 SECTORCOUNT=10000


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

Byte sync Byte header Byte data area Byte EDC/ECC area
 * Logged Data

CDROM_READ2352
Category 80h Function 72h - Read Long

This function reads 2352 bytes of each specified sector into the data buffer. Header and trailer data are read in addition to the 2048-byte data field. The number of sectors to read is passed as input. Address mode may be specified as either Redbook or Logical Block. SECTORSTART and TIMESTART parameters are mutually exclusive.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * ADDRESSMODE        |STRING              |Addressing mode:    |
 * |                   |LOGICALBLOCK or     |
 * |                   |REDBOOK             |
 * SECTORSTART        |NUM                 |If using logical    |
 * |                   |block               |
 * TIMESTART          |STRING              |If using Redbook    |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |read                |
 * TIMESTART          |STRING              |If using Redbook    |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |read                |
 * SECTORCOUNT        |NUM                 |Number of sectors to|
 * |                   |read                |


 * Optional Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * BUFFER             |STRING              |Buffer name         |
 * BUFFER             |STRING              |Buffer name         |

EXAMPLE: Logical Block ADDRESSMODE=LOGICALBLOCK BUFFER=ALPHA SECTORSTART=20000 SECTORCOUNT=10000


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

Byte sync (12 bytes) Byte header (4 bytes) Byte data area (2048 bytes) Byte EDC/ECC area (288 bytes)
 * Logged Data

CDROM_READPRE2352
Category 80h Function 71h - Read Long Prefetch

This function operates as an abortive or advisory seek command. No data is transferred to the caller. SECTORSTART and TIMESTART parameters are mutually exclusive.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * DRIVEHANDLE        |NUM                 |Drive handle for    |
 * |                   |CD-ROM drive        |
 * ADDRESSMODE        |STRING              |Addressing mode:    |
 * |                   |LOGICALBLOCK or     |
 * |                   |REDBOOK             |
 * SECTORSTART        |NUM                 |If using logical    |
 * |                   |block               |
 * TIMESTART          |STRING              |If using Redbook    |
 * SECTORSTART        |NUM                 |If using logical    |
 * |                   |block               |
 * TIMESTART          |STRING              |If using Redbook    |
 * TIMESTART          |STRING              |If using Redbook    |

EXAMPLE: Logical Block ADDRESSMODE=LOGICALBLOCK SECTORSTART=20000 SECTORCOUNT=10000


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

None
 * Logged Data

CDROM_CHECKSECTOR
Read Verification Diagnostic Function

This function verifies that the correct record has been read by the device driver. The expected sector value is compared with a doubleword in the input buffer that contains the sector number of the last record read (first doubleword for COOKED buffers and fifth doubleword for RAW buffers). This is a special function that only applies to the IBM Test Disc, tracks 1, 3, and 6.


 * Required Input Parameter Keywords
 * Keyword            |Type                |Description         |
 * READMODE           |STRING              |RAW or COOKED buffer|
 * $BUFFER            |NUM                 |Buffer reference    |
 * $SECTOR            |NUM                 |Expected sector     |
 * |                   |value
 * $SECTOR            |NUM                 |Expected sector     |
 * |                   |value
 * |                   |value

Error message if comparison fails
 * Logged Data

CDROM_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 CDRC parameter. $RC is set by the script author to the expected value.


 * Required Input Parameter Keywords

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

CDROM_CHECKVALUE
Check Parameter Value Diagnostic Function

This function verifies that a parameter returned by a previous CDROM 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

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

Description of Test Cases
Each of the CD-ROM 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 CD-ROM grammar files.

Test scripts generally start by opening to the device (CDROM_OPEN) and closing at completion (CDROM_CLOSE). The device open will not succeed unless a disc is present. All test scripts log information to a log file of the same file name, but with a file name extension of .LOG. When current status is queried (for example, track, channel, or drive), this 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.

The CD-ROM Play-Audio function causes the CD-ROM drive to play the audio media by sending the audio signal to the CD-ROM's own pre-amplified outputs. The audio is not played through the system speaker or any multi-media device.

CD-ROM discs are accessed by Logical Block or Redbook format. Logical block format sequentially addresses each block on the disc starting at 0. Redbook format addresses each block using a time format of MM:SS:FF (MM represents minutes from the start of the CD, SS represents seconds, and FF represents frames.) Each frame represents 1/75th of a second. Logical block 0 and Redbook format block 0:2:0 are coincident and both represent the first addressable block.

CDFILE.SCR This script exercises the device driver's ability to locate and read a file. It requires any data disk with a directory structure and a data file less than 150KB. The DDTT for this script is initiated by batch file CDFILE.CMD. The batch file first calls a filter program to search for a test file candidate. The name of this target file is passed to the DDTT test script as an included data file. Invoke by entering CDFILE followed by the CD-ROM drive letter and a colon.
 * XADATA.SCR: This script exercises all CD-ROM data API interfaces. It requires the IBM Test Disc (IBM part number 81F8902) which contains known data, known size parameters, and tracks containing mode 1 and mode 2 data.
 * XAAUDIO.SCR: This script exercises all CD-ROM audio API interfaces. It requires the IBM Test Disc and a pair of speakers or headphones plugged into the CD drive audio jack. The test disc has 3 audio tracks containing tones. Track 2 has different tones on left and right channels.
 * XAERROR.SCR: This script exercises the device driver's ability to detect errors related to invalid data, missing media, and invalid command sequences. It requires the IBM Test Disc.
 * CDDATA.SCR: This script exercises all CD-ROM data API interfaces. It requires any data CD-ROM with a directory structure. Since it is dealing with unknown data, the script is not as comprehensive as that for XADATA.SCR.
 * CDAUDIO.SCR: This script exercises all CD=ROM audio API interfaces. It requires any digital audio (music) CD-ROM. Since it operates on unknown audio tracks, the script is not as comprehensive as that for XAAUDIO.SCR.

Evaluation of Test Case Results
Except for XAERROR.SCR, all test cases are expected to succeed and there should be no ERROR statements in the logs (unless a function such as Read UPC is not supported by the hardware). The log for XAERROR.SCR 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 by certain CD-ROM commands as expected, particularly drive status commands. Not all returned data is automatically checked. Script comments will note what data is expected.