AP2 - Automated Audio Device Driver Test Tool

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

Introduction

AP2 automates the testing of audio device drivers using #P2String. It first tests the default device driver's capabilities (if the option is checked) and then displays a list of test cases that the device supports. You can select several test cases to run. At the end of each test case, AP2 displays the status of that test case (success or failure).

This Help file is composed of the following sections:

How to use AP2

Command Line Arguments

When running AP2, you can invoke it by simply typing AP2, or by including any of the following arguments:

SCRIPTS: Specifying the SCRIPTS parameter loads into AP2 all scripts that match the filename given for SCRIPTS. Wildcards "*" and "?" are supported.

If no switches are used to designate which files are to be selected, then all the loaded scripts will be selected. Otherwise, only those scripts matching the selection switches will be highlighted.

/ALL: Specifying the /ALL switch selects all scripts that are displayed. If the #/BATCH switch is used in conjunction with /ALL, the selected scripts will be

tested.

/AMPMIX: Specifying the /AMPMIX switch selects all AMPMIX scripts that are displayed. If the #/BATCH switch is used in conjunction with /AMPMIX, the selected scripts will be tested.; AMPMIX scripts are identified by the first letter of the filename beginning with "A".
/CD: Specifying the /CD switch selects all CD scripts that are displayed. If the #/BATCH switch is used in conjunction with /CD, the selected scripts will be tested.; CD scripts are identified by the first letter of the filename beginning with "C".
/CDXA: Specifying the /CDXA switch selects all CDXA scripts that are displayed. If the #/BATCH switch is used in conjunction with /CDXA, the selected scripts will be tested.; CDXA scripts are identified by the first letter of the filename beginning with "X".
/MIDI: Specifying the /MIDI switch selects all MIDI scripts that are displayed. If the #/BATCH switch is used in conjunction with /MIDI, the selected scripts will be tested.; MIDI scripts are identified by the first letter of the filename beginning with "M".
/VIDEO: Specifying the /VIDEO switch selects all VIDEO scripts that are displayed. If the #/BATCH switch is used in conjunction with /VIDEO, the selected scripts will be tested.; VIDEO scripts are identified by the first letter of the filename beginning with "V".
/WAVE: Specifying the /WAVE switch selects all WAVE scripts that are displayed. If the #/BATCH switch is used in conjunction with /WAVE, the selected scripts will be tested.; WAVE scripts are identified by the first letter of the filename beginning with "W".
/MPEG: Specifying the /MPEG switch selects all MPEG scripts that are displayed. If the #/BATCH switch is used in conjunction with /MPEG, the selected scripts will be tested.; MPEG scripts are identified easily because the files contain the letters "MPEG". AP2 queries the user at startup if MPEG testing will be required during this session.
/INTERACTIVE: Specifying the /INTERACTIVE switch selects all INTERACTIVE scripts that are displayed. If the #/BATCH switch is used in conjunction with /INTERACTIVE, then the interactive switch will be ignored.; A file is designated as interactive if the seventh character in its filename is an "I". For example: C1____I1.P2S. A file should be designated as interactive if it uses the @BREAK or the @CHECK #P2String directive.
/BATCH: Specifying the /BATCH switch runs AP2 in a batch mode. When running AP2 in batch mode, no user interaction is required, nor is it necessary. The program will run, test all scripts, and automatically terminate when there is an error, or when all scripts have been tested.; To run in batch mode, you must specify which scripts are to be tested. Use any combination of the previous seven switches. Specifying /VIDEO /WAVE /BATCH will automatically test all video and wave scripts and terminate when done.

Note: If none of the selection switches are specified, AP2 will return an error message specifying that no test cases were selected.

All errors and failed scripts are logged to an OUTPUT file. The output file can be specified with the #/O switch. If no output file is specified, AP2.OUT will be the default.

In batch mode, testing #Device Capabilities is defaulted to on, unless the #/NOTEST switch is specified.

During batch execution, only those files not designated by their naming convention as INTERACTIVE are run. A file is designated as interactive if the seventh character in its filename is an "I". For example: C1____I1.P2S. A file should be designated as interactive if it uses the @BREAK or the @CHECK #P2String directive.

/TEST: Specifying the /TEST switch automatically tests #Device Capabilities at startup. This setting will also be saved. The next time AP2 is run, AP2 will test the capabilities, unless this option is turned off.
/NOTEST: Specifying the /NOTEST switch turns off automatic testing of #Device Capabilities at startup. This setting will also be saved. The next time AP2 is run, AP2 will not test the capabilities, unless this option is turned on.
/DATAPATH: The /DATAPATH switch is used to specify the directory used for the data files. Specifying the DATAPATH switch is the same as pressing the #DataPath button.; To set the DATAPATH to "C:\DATA", use the following switch: /DATAPATH=C:\DATA
/O: The /O switch is used to specify an output file for AP2. The output file will contain the output generated from all #P2String scripts that FAIL. The output file will also report the number of scripts that SUCCEEDED and FAILED. When running in BATCH mode, all errors will also be logged to this file.; To set the output file to "MYTEST.OUT", use the following switch:; /OMYTEST.OUT; Note: There is no spaces between the /O and the filename.

Testing

You can select several test cases. You can also use the All or the None button to select all or none of the test cases, respectively.

Press the Start Test button to start running the test cases you selected. As each test case terminates, the result of the test is displayed in the list box (success or failure).

Device Capabilities

AP2 starts by testing the audio device driver's capabilities. According to the outcome of the device capability testing, only the supported test cases will be displayed. If you are familiar with #P2String, you can view the file CAPABLTY.TXT, which lists the outcome of the device capability testing.

You can disable device capability testing by unchecking the appropriate check box in the main window. In that case, all test cases will be displayed, regardless of whether the device supports their functions or not.

Capabilities tested include:

Wave Audio

Record
Save
Set the volume
PCM: (8 or 16 bits per sample - 11K, 22K, or 44K samples per second - mono or stereo - play or record)
ADPCM: (16 bits per sample - 11K, 22K, or 44K samples per second - mono or stereo - play or record)
ALAW: (8 bits per sample - 11K, 22K, or 44K samples per second - mono or stereo - play or record)
MULAW: (8 bits per sample - 11K, 22K, or 44K samples per second - mono or stereo - play or record)

MIDI

Play
Save
Set the volume

CD Audio

Play
Eject
Lock the Eject button
Set the volume
Stream

CDXA

Play
Eject
Lock the Eject button
Set the volume

VIDEO

Play
Record
Set the volume

MPEG

Play
Moves the appropriate window
Sizes the appropriate window

The Stop button

The Stop button allows interruption of testing. This can be helpful if many files are highlighted and the Start Test button was pressed by mistake. It can also be used if the first in a series of related test cases fails. In that case, there might be no reason to run the remaining test cases.

The viewing process can be interrupted in the same fashion.

The View Output button

The View Output button allows the viewing of the *.OUT files that are generated from the execution of the *.P2S files.

To view the output for a specified script, highlight the script, and click on the View Output button.

The DataPath button

The DataPath button allows the selection of a directory where data files necessary for the execution of scripts are located. When the DataPath button is pressed, a standard directory dialog box is presented. Any directory on any drive can be specified. Data files consist of *.WAV, *.MID, *.AVI, *.MPG, and so on.

All the data files must exist in the same directory. If data files span more than one directory, it is not possible to test all the scripts at once using the DataPath.

Note for Script writers: When AP2 executes #P2String, it passes it an environment variable AP2PATH which the script writer will use when specifying a data file. If the file TEST.WAV is to be used, it would appear as follows: ?AP2PATH?TEST.WAV with no spaces between the question mark and the filename.

Data Structure

After installing AP2, the data structure would appear as follows:

AP2\
   SCRIPTS\
   OUT\

The AP2 directory contains all files necessary for execution. All output files that are created during the execution of AP2, will be stored in the OUT subdirectory.

If AP2 was installed from the DDK, the data files will be located in the following directory:

\DDK\TESTCERT\MMEDIA\SYSTEM\AP2\DATA\

The #DataPath Button should be set to this directory. This will allow AP2 to locate the data files necessary for the successful execution of the #P2String scripts.

Test Case Output

The #P2String output files have the same name as the test cases, but have the extension ".OUT". They are located in the OUT subdirectory. Subsequent execution of the same test case will overwrite the old ".OUT" file.

Delete unnecessary output files at any time.

RECORD test cases will save wave files in a file called "DELETE.WAV". Video RECORD will save files called "DELETE.AVI". These files will be overwritten by subsequent RECORD test cases. The "DELETE.WAV" and the "DELETE.AVI" files can be erased at any time.

Note that a test case that says Error is not necessarily failing. Test cases with the text "FAILED" are not working correctly.

Description File

AP2 uses a file P2S_DESC.TXT to read in the descriptions for the #P2String scripts in the SCRIPTS subdirectory. Each description is to be on only one line. The format for the file is the script filename followed by a ":" followed by a description. If the description is over 256 characters, it will be trimmed to 256, or the maximum length available to the Window. An example of a description file follows:

A______1.P2S : Ampmix Test #1
A______2.P2S : Ampmix Test #2

If there is no matching description for a test script, the script will be shown, but without a description. If the P2S_DESC.TXT file does not exist, there will be no descriptions for the test scripts.

Install and Error Messages

The following is a list of all install and error messages the program generates:

MPEG Installation: This install message appears everytime you run AP2.EXE.

If you have MPEG hardware and the device driver installed, press "YES", otherwise press "NO".

Help Not Available: This error message appears if the AP2.HLP file is missing.
Help Terminated Due to Error: This error message appears if the program encounters an error while loading the help file.
Unable to create file: CAPABLTY.TXT; This error message appears if the program can not create the named file. This could happen if you were trying to run the program from a read-only medium.
Could not find test cases: This error message appears if no test cases were found in the SCRIPTS subdirectory. Test cases have a ".P2S" extension.
Device driver does not support test cases: This error message appears if the program determines that none of the available test cases are supported by the device driver.
Error Opening AP2.INI; file not found: This error message appears if the AP2.INI file can not be found in the current directory.
Error Reading AP2.INI: This error message appears if an error occurred while reading from the AP2.INI file. Delete the AP2.INI file and run AP2.EXE. (This will create a new AP2.INI file.)
Error writing AP2.INI: This error message appears when the program is trying to update the settings for AP2. This could happen if you were trying to run the program on a read-only medium.
DataPath is Invalid. Please choose a new one: This error message appears if the DataPath is invalid. You will be prompted to select a new DataPath after selecting OK.
No DataPath specified. Press ENTER to quit AP2: This error message appears if there was an invalid DataPath, and a valid one was not chosen.
Memory Allocation Error: You should probably close your applications and shutdown your system when you see this message.
Error starting P2STRING: This error message appears when P2String.EXE can not be found on the path.
Error opening file filename: This error message appears when the program fails to open the named output file.
Error reading file filename: This error message appears when the program fails to read the named output file.
Error closing file filename: This error message appears when the program fails to close the named output file.
Error starting the Editor: This error message appears when the program can not find the standard editor.

P2String

P2String script processing tool is used to test the MCI (media control interface) string commands in the MMPM/2 environment.

You can find additional information on P2String in the MMPM/2 Device Driver Reference which is provided with the DDK.

CDXA

CDXA test cases require path and filename information. Before running any of the test cases for the first time, use an editor to supply that information. CDXA test cases start with an X and have a .P2S extension. The CDXA test cases clearly indicate where to change this information.

Note: CDXA test cases will fail (or not be available) if the audio card does not support AVC ADPCM wave audio format.