View source for AP2 - Automated Audio Device Driver Test Tool

{{IBM-Reprint}}
==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: <tt>/DATAPATH=C:\DATA</tt>
;/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: &#063;AP2PATH&#063;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.<br />
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.

{{IBM-Reprint}}

[[Category:Driver Articles]]