MMPM/2 Device Driver Reference:AP2/P2STRING Tool

This chapter describes the AP2 and P2STRING tools.

AP2
AP2 is the easiest and most complete automated method of testing the audio and video device driver. AP2 provides an easy to use PM interface to the P2STRING tool with a complete set of test scripts for the audio and video device driver. AP2 queries the device driver to determine the functions it supports by using the capability MCI (media control interface) string command. Based on these compatibilities, AP2 will create a list of test scripts that are supported by the default device drivers. You can run any combination of these scripts.

The AP2 tool consists of the file AP2.EXE, AP2.HLP, and AP2.INI and P2S_DESC.TXT. AP2 also requires the P2STRING tool consisting of P2STRING.EXE AND P2S_DLL.DLL. These files are located in the IBM Developer Connection Device Driver Kit for OS/2. The AP2 script files are located in a subdirectory under AP2 called SCRIPTS, and the data files are located in another subdirectory called DATA.

AP2 does not require any parameters If AP2 is entered from the command line, AP2 will run, test the device capabilities and display all scripts that can be tested. The file P2S_DESC.TXT file contains the descriptions for all the AP2 test scripts. The results of the capability test are placed in the file CAPABLTY.TXT.

The following table shows the parameters that are available for AP2. The AP2 parameters include:

Starting and Running AP2
When running AP2 for the first time, it is necessary to set the Data Path. The Data Path points to the directory where all the data files for AP2 are located. Every AP2 script that requires a data file uses an environment variable AP2PATH, which is set by AP2. The Start Test button tests the selected scripts. To test scripts, highlight the selected scripts and click on the Start Test button. After each script is completed, the status for that script is displayed. The output for every script is located in the OUT directory. The output file has the same name as the script with the extension of "OUT".

The View Output button allows the viewing of the files that are generated from the execution of the *.P2S files. To view the output for a specific script, highlight the script, and click on the View Output button.

The Data Path button displays a dialog box and allows you to select the location of the AP2 data directory. AP2 will not run correctly if the data path is not set to the directory containing the AP2 data files.

P2STRING
Use the P2STRING script processing tool to test media control interface string commands in the MMPM/2 environment.

The P2STRING tool processes script files (containing string commands and tool directives) to test string commands in your application programs. The P2STRING tool tests your low-level components at the Ring 3 level (as compared to the PMADDE tool, which tests code at the Ring 0 level). P2STRING extracts the strings from the script files and processes the commands through the mciSendString function. Messages and error conditions of the processes included in the scripts are logged to an output file and displayed in windows. P2STRING comes with a set of predefined scripts to test audio and video functions. These tests are a group of test files called test suites. For more information about test suites, see Testing Device Drivers. Each process logs to its own display window, but all processes log to the same output file. In addition, if you close the display window, the string execution thread is immediately destroyed and the entire process ends.

Output messages include all non-comment lines read from the script (for example, script directives, command strings, expected return values, expected and received notify messages, and status lines). In addition, errors and debugging statements of unsuccessful string commands are logged to a file named P2STRING.LOG file.

Setting Font Size and Type
Before you start the P2STRING tool, you can change the size and type of font displayed in the P2STRING window on the desktop. For example, to specify Times Roman font with a 10 point font size, type:

You can specify either font face, font size, or both. Possible FONTFACE values include SYSTEM, COURIER, TIMES, or HELVETICA (default). Possible FONTSIZE values include 8 (default), 10, 12, 14, or 18.

Starting P2STRING
The P2STRING tool consists of two files: P2STRING.EXE and P2S_DLL.DLL. These files are located in the IBM Developer Connection Device Driver Kit for OS/2. The following example displays the syntax used to start the P2STRING program. Associated parameters are described in the following table.

Note: The parameters are case sensitive.

The following list describes the parameters associated with the P2STRING program.

P2STRING Script Language
This section describes the contents of a script file and how to interpret the script language. Script files can contain several types of lines including:
 * Comments
 * Tool Directives
 * MMPM/2 String Commands
 * Expected Return Strings
 * Expected Error Messages
 * Expected Notification Messages

The following example displays an example of how a script file appears. @PROCESSES = 2 @EVENTS = {HASCTRL1=1, HASCTRL2=0} @PROCESS 1 masteraudio volume 10 open waveaudio alias wav1 shareable notify + MM_MCINOTIFY MCI_NOTIFY_SUCCESSFUL MCI_OPEN #1 @WAIT_NOTIFY 1 60000 @WAIT_PASSDEVICE wav1 60000 @WAIT_NOTIFY 21 60000
 * set masteraudio level for session to 10% - will affect all
 * 3 processes
 * 3 processes
 * open waveaudio device non-exclusively
 * open waveaudio device non-exclusively

Comments
Script comment lines must start with either a semi-colon or comment sign(#) in the first column. These comment lines are neither displayed nor echoed in the output file. If you want a remark to appear in the output, use the @REM directive.

P2STRING allows for a variable number of lines to be displayed in its window. Regular comment lines (header lines) are not displayed nor written to the output file.

Tool Directives
The P2STRING tool supports either multithreaded or multiprocess execution, but not both. You can use tool directives to test either @PROCESSES or @THREADS in a script file.

Tool directives start with an at sign(@) in the first column. These directives affect the execution and appearance of the output. The following classes of directives are recognized:
 * Initialization
 * Execution

Initialization Directives
Use initialization directives to set up the content of the script file. These directives must appear before execution directives because the tool preprocesses the script file and builds process command buffers.

The @THREADS and @PROCESSES directives are mutually exclusive. In other words, the P2STRING tool supports either multithreaded or multiprocess execution in a script file (not both). In addition, there is a limit of 10 processes or threads per script file.

The following table lists the supported initialization directives.

Execution Directives
Use execution directives to process the script file. Again, the @THREAD and @PROCESS directives are mutually exclusive.

The following table lists the supported execution directives.

Note: Timing out on the @WAIT_EVENT and @WAIT_NOTIFY directives is not considered a failure.

MMPM/2 String Commands
All lines that do not fall into any of the other categories are interpreted as MMPM/2 string commands. These lines are passed to the Media Device Manager (MDM) through the mciSendString function after the environment variables have been substituted.

Any token in the string command line bracketed by question marks (such as ? FOO?) is interpreted as an environment variable. The actual value of the environment variable is substituted into the string before it is passed to the mciSendString function. If the variable is not found, a warning is issued and the token is replaced with a null string. For example, assuming the environment string MMDATA is set to D:\DATA, open ?mmdata?\temp.wav alias a is equal to open d:\data\temp.wav alias a.

Expected Return Strings
Many MMPM/2 commands return strings. It is possible to check these strings against an expected value with an expected return string line.

An expected return string line has the format: =result

The equal sign(=) must be in column 1 and should have no trailing spaces. If an empty string is expected, nothing should follow the = (not even spaces). For example: status cdaudio ready wait =TRUE status cdaudio mode wait =stopped The expected result is always interpreted as a string. This might produce some unusual outputs for commands that return binary data.

Where the return is a textual numerical value, it can be matched to a tolerance range of +/-10% using a tilde (~) before the number. This is typically used when the exact value cannot be known. For example: set foo time format milliseconds wait play foo notify @PAUSE 1000 stop foo wait status foo position wait =~1000 Thus, the status command is considered successful if the returned string is in the range 900 - 1100.

Expected Error Messages
When an MMPM/2 string command is expected to fail with an error, use the expected error line to specify the expected error. The expected error line has the format: =!error

The =! must start in column 1. If any error is acceptable, then use the keyword ERROR. If a specific error is expected, type the exact error message after the =!. For example: open sequencer alias mymidi wait load mymidi nofile.foo =!File not found. Be careful about extra blanks in the expected-error and expected-result lines. The case of the strings is unimportant; however, the comparison will fail if the spacing or punctuation does not match exactly.

Expected Notification Messages
Many MMPM/2 string commands cause notification messages to be sent to the P2STRING tool. The system uses notification messages to respond to applications. For example, notification messages indicate system status regarding completion of a media device function or passing of the ownership of a media control device from one process to another.

It is possible to verify that the proper notifications are received by using an expected-notify line. Each expected notification line begins with a plus sign (+) in column 1. The following types of notification lines are possible:
 * Command completion/error notifications
 * Event notifications
 * Position change notifications

Note: Any or all notification messages might be expected for a single MMPM /2 string command.

Command Completion/Error Notifications
A MM_MCINOTIFY line notifies an application when a device successfully completes the action indicated by a media message or when an error occurs. +MM_MCINOTIFY notify-code [#x]

Event Notifications
A MM_MCIPOSITIONCHANGE line notifies an application of the current media position. +MM_MCIPOSITIONCHANGE position %user-parameter #x

Position Change Notifications
A MM_MCICUEPOINT line notifies an application that the playlist processor has encountered a messageinstruction.

Note: Other notifications cannot be compared because they do not allow for a user-parameter as part of the message, which is essential for the tracking of related notifications.

Limitations of MM_MCIPOSITIONCHANGE Verification
There are limitations to what you can verify in the P2STRING tool using event notification lines. The MM_MCIPOSITIONCHANGE line requires the use of the "return value" item in the respective string commands. This line also does not provide for timing start point, for example, playing has started. The P2STRING tool can only count the number of messages received for a specific user parameter (used as a key) and check if subsequent messages have positions approximate to the given expected position interval. The script writer has the responsibility to determine how many POSITIONADVISE messages are expected, taking into account the duration of playing, time format, and start position of the play/record. The reference position given in the expected notification line must be in MMTIME units. If the "expected number of messages" parameter is omitted, the tool verifies only the position interval (not the number). In case of scripts where play, seek, or record are used to cover non-monotonic ranges, the tool might report failures on position-advises because it expects each positionadvise to be in the next position interval from the previous message. If the script makes a jump to a position that does not conform to this, the status will be logged as failed.

For example: setpositionadvise SomeDevice every 10000 on return 5 +MM_MCIPOSITIONCHANGE 10000 %5 play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages) seek SomeDevice to 30000 wait play SomeDevice notify (produces a number of messages starting at 30000) The position-change messages are logged as failed, because of the lapse in position interval. A way to handle this situation is to disable the position-change before an explicit position jump is made and enable the same position-advise with a different user parameter.

For example: setpositionadvise SomeDevice every 10000 on return 5 +MM_MCIPOSITIONCHANGE 10000 %5 play SomeDevice from 35000 to 55000 notify (produces 3 positionchange messages) setpositionadvise SomeDevice every 10000 off seek SomeDevice to 30000 wait setpositionadvise SomeDevice every 10000 on return 6 +MM_MCIPOSITIONCHANGE 10000 %6 play SomeDevice notify (produces a number of messages starting at 30000)

Processing Logic
A string command line can be followed by zero to one return value lines, or zero to three notification lines. Note that this is an exclusive OR, meaning that specifying both expected return value and expected notification is not going to give reliable results due to the fact that returned buffer does not become valid prior to the end of the notify message. Also, in case of notify flags, return values are in the procedural interface format rather than in the string interface format.

The MDM will not be able to convert return values to strings for commands processed with the notify flag because media control drivers will be sending their notify messages directly to the application.

Status of each command is determined in two stages. The first stage is at string execution. If the mciSendString function returns an error and there was no =!ERROR reference line in the script following the command string line, the command is considered failed. If a return value was found after mciSendString is processed, the tool will check for expected return and perform comparison of the two. It they do not match, the command is considered failed. In case of an error that is not in the range understood by the mciGetErrorString function, the command is considered failed even if the !ERROR was encountered.

The second stage of the comparison is after a notification is received and after all the commands are issued. If a notification was received and it was successfully compared to the expected notification line, the command is considered successful. If there was no reference notification line, status of the command will not be assigned, unless notify-error was returned. After all the scripts are processed, expected reference notifications will be used to determine if all the notifications were received. The commands that did not receive a notification, and had an expected notification line of the type, are marked failed. Note that command strings are not examined for presence of a notify flag and it is the writer's responsibility to create an expected notify line if it is of importance. In case of expected NOTIFY_SUCCESSFUL messages, all codes other than NOTIFY_ERROR are considered valid. This includes NOTIFY_SUCCESSFUL, NOTIFY_ABORTED and NOTIFY_SUPERSEDED. If any other notify code was specified as expected, and exact match will be checked for. If NOTIFY_ERROR is expected, all errors in the range are verified as passed. There is no facility for verification of an exact error code returned in the notification.

Testing Device Drivers
Test suites have been provided with this release of the DDK to assist in certifying audio and video device drivers. The test suites provided consist of several test cases. The following sections describe how to:
 * Set up the environment for running the test suites
 * Run the test suites
 * Analyze the test

Setting Up the Environment for Running Test Suites
Before using the audio or video test suites with the P2STRING tool, do the following:

1. Make sure that OS/2 2.1 and the adapter to be tested are installed.

2. Update the CONFIG.SYS file.
 * All the test suites use environment variable to determine the location of the input data files. Add the following SET statements to the CONFIG.SYS file.
 * SET MMDATA=
 * SET MMDATA-AUD=
 * SET TESTDATA=
 * The path for MMDATA and MDATA-AUD must specify the path to the audio input files. For example, your .WAV or .MID files. The path for TESTDATA must specify a path to a temporary working directory that you create.
 * The following files must be loaded, and their path must be specified in the CONFIG.SYS file:
 * SETENV.CMD
 * RESETINI.CMD
 * HWCODE.CMD
 * P2STRING.EXE
 * P2S_DLL.DLL

3. Shut down and restart your workstation so the CONFIG.SYS parameters will take effect.

4. Run HWCODE.CMD for each test suite to be tested.
 * This file is in the IBM Developer Connection Device Driver Kit for OS/2 HWCODE.CMD is a REXX command that determines each test case's exact hardware needs and displays the results. The test case's name contains information that HWCODE.CMD uses to make these determinations, so it is important not to change the name of the test case.


 * The syntax for HWCODE.CMD is:
 * Note: The Test Case Name must include the file name extension. HWCODE.CMD displays the brand and model of audio and video adapters currently supported by OS/2 2.1. The adapter being tested is not listed if it is new, but this information is useful for comparing results based on expected compatibility with other manufactures.
 * HWCODE.CMD also displays audio and video hardware codes.
 * HWCODE.CMD also displays audio and video hardware codes.

Hardware Codes
The hardware codes are two digit codes. The hyphen (-) in the tables indicate the position of the unspecified digit in the code. For example, if you receive the hardware code 84, you would look in the 8- column and the - 4 column to decipher the hardware code.

Video Hardware Codes
Please note that this is as it was printed in the original MMPM/2 DDR, it is more than possible that "-I" should be "Any video capture card and a ProAudio Spectrum 16"

Running the Test Suites
The suites are run using P2STRING. For more information about P2STRING, see AP2/P2STRING Tool.

To run a device test, do the following:
 * 1.Open an OS/2 window.
 * 2.Run SETENV.CMD.
 * Note: Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
 * This file is in the IBM Developer Connection Device Driver Kit for OS/2. This command should be run prior to running the first test (each time you open an OS/2 window) because it sets up the audio devices correctly. To run this command, type:
 * 3.Run RESETINI.CMD prior to each test.
 * Note: Nothing is displayed when running this command. When the OS/2 command prompt is displayed again, this command is finished.
 * This file is in the IBM Developer Connection Device Driver Kit for OS/2. This command resets system connections in the appropriate INI files for audio and video tests to their defaults. To run this command, type:
 * 4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:
 * 4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:
 * 4.Run each test. Each test can be run from the command line and the output is saved in a file for analysis. The P2STRING syntax is:

For more information about running tests from the command line, see Starting P2STRING.

The tests display messages in a message box and might not automatically close the message box when the test finishes. If the test does not close the message box, you need to manually close it. The message box is not closed if P2STRING is waiting for a return value that might or might not be returned. The test has finished processing if the string "Script completed successfully" is displayed at the bottom of the message box. Allow approximately one minute after this message is displayed before manually closing the message box to allow for any late return codes.


 * Note: The "Script completed successfully" message does not indicate that all the tests passed. It only indicated the script has finished processing.

Analyzing a Device Driver Test
After an audio or video test is run, the results of the test are stored in a file with a .IND extension appended to the file name. The media control interface strings that passed are flagged with a PASSED keyword in the return string, and failed strings are flagged with a FAILED keyword.

Those that are flagged as FAILED can be analyzed further. When all strings are passed successfully, the device driver is handling all conditions specified by the test correctly.

Note: If a string command is supposed to fail and does, the return string is considered PASSED, because the return string matches the expected results.

The following example illustrates how to compare the results file with the test script. TEST SCRIPT (AUDIO1.P80)

############################################        #                                          #         #   OPEN THE MIDIPLAYER                    # #  WAIT FOR SUCCESSFUL OPEN               # #                                         #         ############################################         # /--->   open sequencer alias midiplayer notify |/-->  +MM_MCINOTIFY MCI_NOTIFY_SUCCESSFUL MCI_OPEN #1 ||     @WAIT_NOTIFY 1 45000 ||     @WAIT_PASSDEVICE midiplayer ||     ############################################ ||      #                                          # ||      #   LOAD AND CUE TYPE1. MID FILE          # ||     #   PLAY jesu.mid  FILE AND EXPECT AN      # ||     #   ABORT FROM A PAUSE                     # ||     #                                          # ||      ############################################ ||      # ||  /-> load midiplayer ?MMDATA-AUD?\jesu.mid  wait || |   cue midiplayer output wait || |   play midiplayer from 100 to 60000 notify || |   +MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY || |   # ||  | ||  | ||  |                 TEST OUTPUT FILE (AUDIO1.LOG) || | ||  | ||  |          ****************Opening script file || | ||  | ||  |          Thread 1 executing 21 commands. \|--|> T:1 send string # 1 open sequencer alias midiplayer notify \--|> EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1 |    |--> T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1 |    \--> NOTIFY STATUS FOR #1: PASSED |         T:1 Notify received MM_MCIPASSDEVICE MCI_GAINING_USE Device ID 1 |          returned string for #  1: 1 |         T:1 @WAIT_NOTIFY 1 45000 |         T:1 @WAIT_PASSDEVICE MIDIPLAYER \> T:1 send string # 2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait |--> no returned string for #  2. \--> NOTIFY STATUS FOR #2: FAILED .                  ..

END OF SCRIPT FILE REACHED. 14 COMMANDS SENT

Waiting for late notifications for 30 sec T:1 Notify received for # 14 MM_MCINOTIFY SUCCESSFUL by command MCI_CLOSE ID 1 NOTIFY STATUS FOR #14: PASSED

Script completed successfully The first command "open sequencer alias midiplayer notify" in the test expects the following results: +MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY

Following the first and second line down in the previous example, you can see that this command passed successfully: EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1 T:1 Notify received for # 1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1 NOTIFY STATUS FOR #1: PASSED

The following lines in the test script are not expecting returned information: @WAIT_NOTIFY 1 45000 @WAIT_PASSDEVICE midiplayer Therefore, the test output echoes these commands to show they were received. T:1 @WAIT_NOTIFY 1 45000 T:1 @WAIT_PASSDEVICE MIDIPLAYER However, the "load midiplayer ?MMDATA-AUD?\jesu.mid wait" command did not receive the expected message, and the following is logged to the test file: T:1 send string # 2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait no returned string for # 2. NOTIFY STATUS FOR #2: FAILED The bottom of the test output file indicates how many commands were processed, it also indicates if it is waiting for late notifications. Depending on the test, and the devices being tested, expected notifications might not always arrive on time or in the order expected. If a notification does not arrive when expected, it can arrive later if the device driver has not failed.

This is especially important on multi-threaded or multi-process processing. The more complicated the test (for example stress testing the device driver with multiple devices), the more difficult it is to decipher the output file. You will have to keep track of each thread or process separately to determine the results of the test.