CD-ROM Device Driver Test Tool

From EDM2
Jump to: navigation, search
Storage Device Driver Reference
  1. About This Book
  2. Introduction to DASD, SCSI, and CD-ROM Programming Interfaces
  3. Installation of OS/2, DASD, SCSI, and CD-ROM Device Drivers
  4. Adapter Device Driver Development Considerations
  5. DASD, SCSI, and CD-ROM Device Manager Interface Specification
  6. Error Handling
  7. Adapter Device Driver Command-Line Parameters
  8. DASD IOCtl Device Driver Test Tool
  9. Optical IOCtl Device Driver Test Tool
  10. Using Filter Device Drivers
  11. Library and Services
  12. CD-ROM Device Manager Interface Specification
  13. CD-ROM Device Driver Test Tool
  14. Building an OS/2 Virtual Disk Driver
  15. OS2DASD.DMD - Technical Reference
  16. Boot Record Architecture
  17. Extended Device Driver Interface Specification
  18. I/O Request Block - C Definitions
  19. OS/2 SCSI Device Driver Interface Specification
  20. Advanced SCSI Programming Interface (ASPI) OS/2 Specification
  21. Adapter Device Driver Interface Questions and Answers
  22. Device Driver Test Tool (DDTT)
  23. Glossary

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation


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.

  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:
[C:\]md tstcdrom
[C:\]cd tstcdrom
[C:\tstcdrom]copy e:\ddk\testcert\storage\function\cdrom\*
[C:\tstcdrom]copy e:\ddk\testcert\general\ddtt\*
  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

Storage-img2.gif

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              |
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.    |
Logged Data

None.

CDROM_CLOSE

This function closes the CD-ROM.

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

None.

Logged Data

None.

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        |
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|
Logged Data

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

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        |
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|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|HIGHTRACK           |NUM                 |Highest track number|
|--------------------+--------------------+--------------------|
|LOWTRACK            |NUM                 |Lowest track number |
|--------------------+--------------------+--------------------|
|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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|PAUSE               |NUM                 |Pause bit Where:    |
|                    |                    |0=not paused        |
|                    |                    |1=paused            |
|--------------------+--------------------+--------------------|
|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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

CD-ROM device driver ID

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|SECTORSIZE          |NUM                 |Bytes per sector    |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Sector size in bytes

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|VOLSIZE             |NUM                 |Disc sector count   |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Volume size in sectors

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Starting point of track Track-control information

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|STATUS              |NUM                 |Status bits         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

CD-ROM drive status information

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Control and ADR byte Universal product code Frame

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|TRACK               |NUM                 |Current track number|
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

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

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        |
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|
Logged Data

Input channel for output channel 0 Volume control for output channel 0 Input channel for output channel 1 Volume control for output channel 1

CDROM_AUDIOCHANINFO

Category 81h Function 40h - Set Audio Channel Controls

This function sets the audio channel controls.

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            |

EXAMPLE:

   VOL1 = (0-255)
   VOL2 = (0-255)
   INPUT1 = 0
   INPUT2 = 1
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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        |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None.

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
Output Parameter Keywords
|Keyword             |Type                |Description
|--------------------+--------------------+--------------------
|CDRC                |NUM                 |Function return code
Logged Data

None.

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).

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
SECTORCOUNT NUM If using logical block
TIMESTART STRING If using Redbook
TIMESTOP STRING If using Redbook

EXAMPLES: Logical Block:

   ADDRESSMODE=LOGICALBLOCK
   SECTORSTART=20000
   SECTORCOUNT=10000

Redbook:

   ADDRESSMODE=REDBOOK
   TIMESTART=02:45:00
   TIMESTOP=05:55:00

</pre>

Output Parameter Keywords
Keyword Description
CDRC NUM Function return code
Logged Data

None.

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).

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
EXAMPLES: 
Logical Block 
    ADDRESSMODE=LOGICALBLOCK
    SECTORSTART=20000
Redbook 
    ADDRESSMODE=REDBOOK
    TIMESTART=02:45:00
Output Parameter Keywords
|Keyword             |Type                |Description
|--------------------+--------------------+--------------------
|CDRC                |NUM                 |Function return code
Logged Data

None.

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.

Required Input Parameter Keywords
|Keyword             |Type                |Description
|--------------------+--------------------+----------------
|DRIVEHANDLE         |NUM                 |Drive handle for
|                    |                    |CD-ROM drive    
|--------------------+--------------------+----------------
|ADDRESSMODE         |STRING              |Addressing mode:
|                    |                    |LOGICAL BLOCK or
|                    |                    |REDBOOK

EXAMPLES: Logical Block

ADDRESSMODE=LOGICALBLOCK

Redbook

ADDRESSMODE=REDBOOK
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Location of drive head

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                |
Optional Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|BUFFER              |STRING              |Buffer name         |
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Byte(s) read

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                |
Optional Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|BUFFER              |STRING              |Buffer name         |

EXAMPLE: 
Logical Block 
    BUFFER=ALPHA
    SECTORSTART=20000
    SECTORCOUNT=10000
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

Byte sync Byte header Byte data area Byte EDC/ECC area

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                |
Optional Input Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|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|
Logged Data

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

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    |

EXAMPLE: 
Logical Block 
    ADDRESSMODE=LOGICALBLOCK
    SECTORSTART=20000
    SECTORCOUNT=10000
Output Parameter Keywords
|Keyword             |Type                |Description         |
|--------------------+--------------------+--------------------|
|CDRC                |NUM                 |Function return code|
Logged Data

None

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
Logged Data

Error message if comparison fails

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
Keyword Type Description
$RC NUM The expected return code
Logged Data

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

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
Keyword Type Description
$PARM NUM The returned parameter value
$EXPECT NUM The expected value
Logged Data

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

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.

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.

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.

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.