Input/Output Device Driver Reference/Parallel Port Device Driver Test Tool
This chapter explains how to use the parallel port Device Driver Test Tool.
Overview
The parallel port Functional Verification Tests (FVTs) exercise the Application Program Interfaces (APIs) defined for the DosDevIOCtl interface of parallel port device drivers. The tests are implemented with the Device Driver Test Tool (DDTT). Each test is defined in a script file and these files can be modified using a text editor to create additional, specialized test cases. The test scripts give the user a repeatable set of tests that demonstrate parallel port function and performance. Errors are reported and are isolated to a specific test sequence and API.
User input and output from each thread of the parallel port tests is performed by way of a separate Presentation Manager window. Test cases log all information to a log files, clearly indicating the actual execution sequence in the event of errors.
Parallel Port Test Architecture
The DDTT provides a common front-end parser for test-case scripts. The following DDTT parallel-specific files are required:
- DDTPARA.DLL
- PARALLEL.GRA
- GEN.GRA - needed for test script file, REQEX.SCR
- GENDRV.SYS - needed for test script file, REQEX.SCR
The C++ source code for DDTPARA.DLL is available on the IBM Developer Connection Device Driver Kit for OS/2.
The following required, common components of the DDTT implement the DDTT's programmable parser and common test functions such as SET, LOOP, and PAUSE:
- DDTT.EXE
- DDTT.DLL
- GLOBAL.DLL
- GLOBAL.GRA
Installation
There are two directory structures that utilize test suites in the IBM Developer Connection Device Driver Kit for OS/2. The TESTCERT substructure contains the executables and test cases; the TESTTOOL substructure contains the files required to change and rebuild the code for a particular test DLL.
The following procedure describes installation for running test cases:
- Copy the executable and parallel port test case files from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc to the hard drive. All the executable (.EXE and .DLL) files can reside in one directory, such as \TESTPARA. Test-case script and command files can also be placed in this directory on the hard disk. If the target directory is C:\TESTPARA and the E drive contains the information from the IBM Developer Connection Device Driver Kit for OS/2 CD-ROM disc, then use the following commands to copy the parallel port test suite:
- [C:\]md testpara
- [C:\]cd testpara
- [C:\testpara]copy e:\ddk_x86\testcert\inputout\function\parallel\*
- [C:\testpara]copy e:\ddk_x86\testcert\general\ddtt\*
- Add the C:\TESTPARA to the LIBPATH and PATH in the CONFIG.SYS file.
- For script testcase REQEX.SCR, which requests and releases exclusive access, a generic driver named GENDRV.SYS must be installed. Edit your system's CONFIG.SYS file and add the following line:
- DEVICE=c:\testpara\gendrv.sys
- Reboot your machine so the new LIBPATH entry and DEVICE statement take effect.
Test-Case Execution
The DDTT parallel port tests must be executed on a directly-attached printer device. These tests will not work when executed against a printer device accessed by way of a network connection.
There are two ways to run parallel port tests. To run the program from a command file, be sure the files are installed in the current directory. Then, execute the TESTFONT or TESTPARA command files. The command file will run a set of script files. The TESTFONT executes scripts related to font testing and requires the spooler to be enabled. The TESTPARA executes scripts using other printer functions that require the spooler to be disabled.
To run one script file at a time, see #Description of Test Cases of the file to get a description of each script file. Then, after determining which script file to run, type in DDTT followed by the script file name:
[C:\TESTPARA]DDTT QFONT.SCR
After the script has finished executing, control will transfer back to the OS/2 Window. If the script files are run individually, and a TESTxxx command file has not been run first, then run SETINFO to set up your printer device.
There are three different sets of script files in the DDTT parallel port package. The first set is the font script files, the second set is the general printer script files, and the third is only one script file, REQEX. SCR, which requests and releases exclusive access. When TESTFONT or TESTPARA is run, it will ask for the printer device (such as LPT1 or LPT2).
The SETINFO command file will set up the necessary information that is needed for the parallel port script files. The command file will ask the following question:
PLEASE ENTER THE OUTPUT PORT OF YOUR PRINTER, SUCH AS LPT1
After this information is entered, the command file will store this information in the SYSINFO.TXT file. The contents of the file is
PARA SET DEVICENAME=LPT1
DDTT Parallel Port Test Grammar Function Calls
The following is a list of the DDTT Parallel Port Test Grammar Function Calls:
- PARA_OPEN
- PARA_CLOSE
- PARA_SETRAMECTRL
- PARA_SETRETRY
- PARA_INIT
- PARA_ACTIVATEFONT
- PARA_SETTITLE
- PARA_SETWRTTIMEOUT
- PARA_QFRAMECTRL
- PARA_QRETRY
- PARA_QPORT
- PARA_QACTIVEFONT
- PARA_VERIFYFONT
- PARA_QWRTTIMEOUT
- PARA_READFILE
- PARA_WRITEFILE
PARA_OPEN
This function opens the given parallel port.
- Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DEVICENAME | STRING | Output port identification, such as LPT1 |
- Output Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Logged Data
- None.
PARA_CLOSE
This function closes the opened parallel port.
- Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- None.
PARA_SETFRAMECTRL
Category 05h - Function 42h
This function sets frame control (characters-per-line, lines-per-inch).
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| CPL | NUM | Characters-per-line |
| LPI | NUM | Lines-per-inch |
- Output Parameter Keywords
- None.
- Logged Data
- Frame Control Message with characters-per-line and lines-per-inch.
PARA_SETRETRY
Category 05h - Function 44h
This function sets infinite retry on/off (0=OFF, 1=ON).
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| RETRY | NUM | ON or OFF setting |
- Output Parameter Keywords
- None.
- Logged Data
- Retry state Message with Infinite Retry Disabled/Enabled
PARA_INIT
Category 05h - Function 46h
This function initializes parallel port.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- None.
PARA_ACTIVATEFONT
Category 05h - Function 48h
This function activates a font.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| CODEPAGE | NUM | Number of code page |
| FONTID | NUM | Number of font |
- Output Parameter Keywords
- None.
- Logged Data
- Font information Message with CODEPAGE and FONTID
PARA_SETTITLE
Category 05h - Function 4Dh
This function sets job title.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| JOBTITLE | STRING | Job title identification |
- Output Parameter Keywords
- None.
- Logged Data
- Job title information Length and address with job title information.
PARA_SETWRTTIMEOUT
Category 05h - Function 4Eh
This function sets write timeout.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| PPWRTTIMEOUT | NUM | Seconds for write timeout |
- Output Parameter Keywords
- None.
- Logged Data
- Write time out value Parallel Port Write Time Out Value in seconds
PARA_QFRAMECTRL
Category 05h - Function 62h
This function queries frame control (characters-per-line, lines-per-inch).
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- Frame Control Message with characters-per-line and lines-per-inch.
PARA_QRETRY
Category 05h - Function 64h
This function queries infinite retry.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- Retry state Message with Infinite Retry Disabled/Enabled
PARA_QPORT
Category 05h - Function 66h
This function queries port.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- Data Value in data field
PARA_QACTIVEFONT
Category 05h - Function 69h
This function queries active font.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- Font information Message with CODEPAGE and FONTID
PARA_VERIFYFONT
Category 05h - Function 6Ah
This function verifies font.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| CODEPAGE | NUM | Number of code page |
| FONTID | NUM | Number of font id |
- Output Parameter Keywords
- None.
- Logged Data
- Font information Message with CODEPAGE and FONTID
PARA_QWRTTIMEOUT
Category 05h - Function 6Eh
This function queries write time out.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
- Output Parameter Keywords
- None.
- Logged Data
- Time out information Message with PP Write Time Out Value in seconds.
PARA_READFILE
This function reads a file.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| FILENAME | STRING | File to be read |
| BYTECOUNT | NUM | Number of bytes to read |
| $BUFFER | STRING | Buffer to hold data |
- Output Parameter Keywords
- None.
- Logged Data
- None.
PARA_WRITEFILE
This function writes a file.
- Required Input Parameter Keywords
| Keyword | Type | Description |
|---|---|---|
| DRIVEHANDLE | NUM | Handle number of output parallel port |
| FILENAME | STRING | Name of file to write |
| $BUFFER | STRING |
- Output Parameter Keywords
- None.
- Logged Data
- None.
Description of Test Cases
Each of the parallel port test cases can be executed individually as previously described. The corresponding test scripts are described below. The user can create additional tests or combine tests into multi-threaded test cases after becoming familiar with the DDTT and the parallel grammar file.
All of the parallel port test cases use the DDTT @IMPORT command to include one script file:
- SYSINFO.TXT
- The content of the SYSINFO.TXT files is set by the SETINFO.CMD command file. SETINFO.CMD should be executed once to establish values for the following DDTT parameter keywords:
- DEVICENAME - drive name of the parallel port device under test, such as LPT1.
All test scripts open and close the parallel port device and verify successful status return from every exercised API. All test scripts log information to a log file with the same file name and a file name extension .LOG. When current status is queried (for example, the font, timeout, or port), this data is written to DDTT's output windows and to the log file. Log files can be examined after the test case has completed.
- ACTFONT.SCR
- Activates and logs the font identified by the CODEPAGE and FONTID.
- FRAMES.SCR
- Sets and queries the frame controls for four combinations of characters-per-line and lines-per-inch.
- INITPAR.SCR
- Initializes the parallel port.
- QFONT.SCR
- Queries the active font, logging, CODEPAGE, and FONTID.
- QFRAME.SCR
- Queries frame control, logging characters-per-line, and lines-per-inch settings.
- QPARPORT.SCR
- Queries the parallel port and logs the value in the data field.
- QPPWTOUT.SCR
- Queries write time out and logs time, in seconds.
- QRETRY.SCR
- Queries to determine if infinite retry is enabled.
- REQEX.SCR
- Requests exclusive access of LPT1 and displays Have exclusive access, pauses for two minutes, and then releases exclusive access. This process requires installation of the generic device driver, GENDRV.SYS.
- RETRY.SCR
- Enables infinite retry, queries retry, disables infinite retry, and queries retry, again.
- SETFRAME.SCR
- Sets frame control of 80 characters-per-line and 6 lines-per-inch.
- SPPWTOUT.SCR
- Sets parallel port write time out value to 10 seconds.
- SRETRY.SCR
- Sets infinite retry enabled.
- TITLERD.SCR
- Sets jobtitle to BIDI TEST JOB-TITLE, reads file READ.SCR, and writes file.
- VFONT.SCR
- Verifies font with CODEPAGE=34000 and FONTID=34000.
Evaluation of Test Case Results
Unless otherwise stated in the test-case descriptions, all test cases are expected to succeed. If a test case fails in a mode detectable by DDTT, then the token "ERROR" will be written to the corresponding log file.
The script files test all of the different parallel port functions. After each script file has finished executing, it will log all of the test information out to a log file. When all of the script files have finished executing, the command file will search all of the log files for any errors that have occurred. The results from this search are stored in the RESULTS.TXT file.
When the command file has completed searching the log files, it also displays the results on the screen. The command file is searching only for the word "ERROR".