View source for MMPM/2 Device Driver Reference:AP2/P2STRING Tool

=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:
{| class="wikitable"
! Parameter||Description 
|-
| script_file||Specifies the script files to be used. The default is *.P2S.  Wildcards *,? are supported.
|-
| -AMPMIX||Specifies that the Ampmix scripts will be selected when AP2 is started. Ampmix scripts are denoted by an 'A' in the first character in the filename.  
|-
| -CD||Specifies that the CD scripts will be selected when AP2 is started. CD scripts are denoted by a 'C' in the first character in the filename.
|-
| -CDXA||Specifies that the CDXA scripts will be selected when AP2 is started. CDXA scripts are denoted by an 'X' in the first character in the filename. 
|-
| -MIDI||Specifies that the MIDI scripts will be selected when AP2 is started. MIDI scripts are denoted by an 'M' in the first character in the filename.
|-
| -WAVE||Specifies that the Wave scripts will be selected when AP2 is started. Wave scripts are denoted by a 'W' in the first character in the filename.
|-
| -VIDEO||Specifies that the Video scripts will be selected when AP2 is started. Video scripts are denoted by a 'V' in the first character in the filename. 
|-
| -MPEG||Specifies that the MPEG scripts will be selected when AP2 is started. MPEG scripts are denoted by "_M" as the first two characters in the filename.
|-
| -INTERACTIVE||Specifies that the Interactive scripts will be selected when AP2 is started. An interactive script requires some form of user input during the execution of the script. A script is denoted as interactive by an 'I' in the seventh character in the filename.
|-
| -ALL||Specifies that all loaded scripts will be selected.
|-
| -BATCH||Specifies that testing will be in a  batch mode. One or more of the above selection parameters is required to specify which scripts are to be tested. In batch mode AP2 will automatically start testing,  log any messages to an output file and terminate when complete. If the interactive switch is used in conjunction with batch, interactive will be ignored, and no interactive scripts are tested in batch mode. All output and failed scripts are logged to an output file. If an output file is not specified, the default is AP2.OUT.
|-
| -oOUT_FILE||If this parameter is specified, all scripts that FAIL will also be logged to this file.
|-
| -TEST||Specifies that AP2 will automatically test device capabilities at startup.
|-
| -NOTEST||Specifies that AP2 will preform no testing of device capabilities at startup.
|-
| -DATAPATH||Specifies the data path to be used by AP2. This is the same as selecting the Data Path button.
|}

=== 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.
 [[Image:Ap2.png|right|350px]]
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 [[00127.htm|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.

<pre class="western"> [Artwork not shown] </pre>
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:

<pre class="western">SET P2STRING_FONTFACE=TIMES
SET P2STRING_FONTSIZE=10</pre>
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.

<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>
'''Note:'''The parameters are case sensitive.

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

'''Parameter Description'''

''script_file''Specifies the script file name you want to process.

'''Note:'''Refer to [[00118.htm|P2STRING Script Language]]for information on the contents of a script file and how to interpret the script language.

[-a]''out_file''Specifies the output file name containing the results of the test. This file contains only the results of the test you are running, unless you specify the optional -a parameter. For example, to append the output of a script file named SAMPLE.SCR to output currently in a file named MDM.OUT, type:

<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT</pre>
[-e''err_file''] Specifies the optional error file name that receives messages from string commands that completed unsuccessfully. For example, to create an error file named MDM.ERR, type:

<pre class="western">P2STRING SAMPLE.SCR MDM.OUT -eMDM.ERR</pre>
[-d|-D] Specifies one of the following optional parameters:

<pre class="western">-d     Instructs P2STRING to end after processing a script file.
       Use this parameter when you are running test cases automatically  .
       There is no change in the output.
       When the script file has completed processing, P2STRING prompts 
       you with a message requiring you to end the test.
-D     Behaves identically to the -d parameter except that the script 
       directives requiring user input are ignored.</pre>
'''Note:'''Refer to [[00120.htm|Tool Directives]]for information on how to add execution directives (which require user input) in a script file.

-E Causes the script file to exit after the first error. By default, script files run to completion regardless of errors. For example, the following command ends the processing of SAMPLE.SCR after an error is encountered:

<pre class="western">P2STRING SAMPLE.SCR -aMDM.OUT -d -eMDM.ERR -E</pre>
-t Records time stamps for strings and MM_MCIPASSDEVICE notification messages.





=== 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:

�[[00119.htm|Comments]]<br />�[[00120.htm|Tool Directives]]<br />�[[00121.htm|MMPM/2 String Commands]]<br />�[[00122.htm|Expected Return Strings]]<br />�[[00123.htm|Expected Error Messages]]<br />�[[00124.htm|Expected Notification Messages]]

The following example displays an example of how a script file appears.

<pre class="western">@ PROCESSES = 2 
@ EVENTS = { HASCTRL1 = 1 , HASCTRL2 = 0 } 
# 
# 
# 
@ PROCESS   1 
; 
;   set   masteraudio   level   for   session   to   10 %   -   will   affect   all 
;   3   processes 
; 
masteraudio   volume   10 
; 
;   open   waveaudio   device   non - exclusively 
; 
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 </pre>




=== 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 <br />�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.

'''Directive Description'''



<pre class="western">@PROCESSES=x</pre>
Specifies the number (''x'') of processes the script file will be running. For example:

<pre class="western">@PROCESSES=2</pre>


<pre class="western">@THREADS=x</pre>
Specifies the number (''x'') of threads the script file will be running.



<pre class="western">@EVENTS={n[=0|1] [,n[=0|1]]}</pre>
Specifies one or more ''n''ames of events. Events are user-defined with a maximum of 15 characters. Events can be set to 1 or 0. Set an event to 1 for an event that is set with the @SET_EVENT execution directive. Set an event to 0 to clear or reset the event. If no initialization values are specified, the event is initialized to 0. For example:

<pre class="western">@EVENTS={brad=1,john=1,test=0}</pre>


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.

'''Directive Description'''



<pre class="western">@THREAD x</pre>
Specifies that the script lines following this directive belong to thread number ''x''until the next @THREAD directive is encountered.



<pre class="western">@PROCESS x</pre>
Specifies that the script lines following this directive belong to process number ''x''until the next @PROCESS directive is encountered.



<pre class="western">@SET_EVENT name 0|1</pre>
Sets the event ''name''to either 1 or 0. Use 1 to mark that the event has happened. Use 0 to clear or reset the event.

'''Note:'''The event must be declared through the @EVENTS directive.



<pre class="western">@WAIT_EVENT name [to]</pre>
Waits until the event ''name''is set to 1. @WAIT_EVENT does not cause a change of the event state. If you need a reusable event, use this directive.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.



<pre class="western">@WAIT_NOTIFY x [to]</pre>
Waits for a specific number (''x'') from an expected MM_ MCINOTIFY notification message. This number must match the index used in the MM_MCINOTIFY reference line. The @WAIT_NOTIFY events are not reusable because there are no events that logically reset it.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.

If the associated mciSendString function fails, the event is posted to prevent delays for notifications that are never going to be sent.



<pre class="western">@WAIT_PASSDEVICE alias [to]</pre>
Waits until the device instance with an alias of ''alias''gains use. This assumes that the alias names used within a script file are unique. The maximum alias name length is 20 characters.

'''Note:'''Use a unique alias for every OPEN command.

The timeout (''to'') is specified in milliseconds. If omitted, it defaults to 3 minutes.

The tool assumes that a unique alias is specified on each OPEN string command. If unique aliases are not used, errors conditions might occur.



<pre class="western">@REM comment</pre>
Echoes the ''comment''to the screen and the output log file. All other script comment lines (those starting with ''';'''or '''#''') are neither transferred nor displayed.



<pre class="western">@PAUSE to</pre>
Pauses processing of the current thread or process in the input script file for the specified time. It does not stop the processing of the notifications or window functions. Other threads or processes are not affected by this directive.



<pre class="western">@BREAK   [ message ] </pre>
Causes a message box to appear with ''message''text. Script processing is halted until the user responds with the correct action . For example:

<pre class="western">@BREAK [replace the CD]</pre>


<pre class="western">@CHECK [message]</pre>
Grades the success of the previous command based on the user's response. A pop-up window displays the ''message''and prompts the user with Yes or No push buttons. The status is passed if the user selects Yes, or failed if No is selected. For example:

<pre class="western">@BREAK The music will play for 5 seconds.  Ready to time it?
play cdaudio notify
@PAUSE 5000
@CHECK Did it play?</pre>






=== 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:

<pre class="western">=result</pre>
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:

<pre class="western">status cdaudio ready wait
=TRUE
status cdaudio mode wait
=stopped</pre>
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:

<pre class="western">set foo time format milliseconds wait
play foo notify
@PAUSE 1000
stop foo wait
status foo position wait
=~1000</pre>
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:

<pre class="western">=!error</pre>
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:

<pre class="western">open sequencer alias mymidi wait
load mymidi nofile.foo
=!File not found.</pre>
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 <br />�Event notifications <br />�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.

<pre class="western">+MM_MCINOTIFY  notify-code [#x]</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|notify-code       |Specifies the notification message code,  |
|                  |for example, MCI_NOTIFY_SUCCESSFUL. The   |
|                  |spelling must be the same as the #defines |
|                  |in the OS2ME.H file for the notify codes. |
|------------------+------------------------------------------|
|message           |Specifies the media control interface     |
|                  |message that caused the notification, for |
|                  |example, MCI_PLAY. The spelling must be   |
|                  |the same as the #defines in the OS2ME.H   |
|                  |file for media control interface messages.|
|------------------+------------------------------------------|
|x                 |Specifies a unique number (x) used to     |
|                  |associate @WAIT_NOTIFY directives with    |
|                  |particular notifications. This number has |
|                  |nothing to do with the order in which     |
|                  |strings are sent. The number must be      |
|                  |unique and in the range 1-99.             |
\-------------------------------------------------------------/</pre>
Event Notifications

A MM_MCIPOSITIONCHANGE line notifies an application of the current media position.

<pre class="western">+MM_MCIPOSITIONCHANGE position %user-parameter #x</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the             |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.           |
|------------------+------------------------------------------|
|x                 |Specifies the number (x) of position      |
|                  |change messages expected. For further     |
|                  |information, refer to Limitations of      |
|                  |MM_MCIPOSITIONCHANGE Verification.        |
\-------------------------------------------------------------/</pre>
Position Change Notifications

A MM_MCICUEPOINT line notifies an application that the playlist processor has encountered a ''message''instruction.

<pre class="western">+MM_MCICUEPOINT position %user-parameter</pre>


<pre class="western">/-------------------------------------------------------------\
|Keyword           |Description                               |
|------------------+------------------------------------------|
|position          |Specifies the expected MMTIME position of |
|                  |the first position-change message.        |
|------------------+------------------------------------------|
|user-parameter    |Specifies the user parameter to be        |
|                  |returned. This should be the same as the  |
|                  |return value specified in the             |
|                  |SETPOSITIONADVISE string command. Note    |
|                  |that the return value must be a unique    |
|                  |integer in the range of 1 - 99.           |
\-------------------------------------------------------------/</pre>
'''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 &quot;return ''value''&quot; 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 &quot;expected number of messages&quot; 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:

<pre class="western">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)</pre>
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:

<pre class="western">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)</pre>




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

<pre class="western">SET MMDATA=&lt;path&gt;
SET MMDATA-AUD=&lt;path&gt;
SET TESTDATA=&lt;path&gt;</pre>
The path for MMDATA and MMDATA-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 <br />RESETINI.CMD <br />HWCODE.CMD <br />P2STRING.EXE <br />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:

<pre class="western">HWCODE &lt;Test Case Name&gt;</pre>
'''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.





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

Audio Hardware Codes

'''Audio Capture Playback Adapters'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |ACPA                |Number of Cards     |
|                    |                    |Unspecified         |
|--------------------+--------------------+--------------------|
|0-                  |                    |                    |
|--------------------+--------------------+--------------------|
|1-                  |1                   |                    |
|--------------------+--------------------+--------------------|
|2-                  |2                   |                    |
|--------------------+--------------------+--------------------|
|3-                  |3                   |                    |
|--------------------+--------------------+--------------------|
|8-                  |                    |1                   |
|--------------------+--------------------+--------------------|
|9-                  |1                   |1                   |
|--------------------+--------------------+--------------------|
|A-                  |2                   |1                   |
|--------------------+--------------------+--------------------|
|B-                  |3                   |1                   |
|--------------------+--------------------+--------------------|
|G-                  |                    |2                   |
|--------------------+--------------------+--------------------|
|H-                  |1                   |2                   |
|--------------------+--------------------+--------------------|
|I-                  |2                   |2                   |
|--------------------+--------------------+--------------------|
|J-                  |3                   |2                   |
|--------------------+--------------------+--------------------|
|O-                  |                    |3                   |
|--------------------+--------------------+--------------------|
|P-                  |1                   |3                   |
|--------------------+--------------------+--------------------|
|Q-                  |1                   |3                   |
|--------------------+--------------------+--------------------|
|R-                  |3                   |3                   |
\--------------------------------------------------------------/</pre>
'''OEM'''

<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |OEM                 |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |                    |                    |
|--------------------+--------------------+--------------------|
|-1                  |OPL0 (original Sound|                    |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-4                  |Sound Blaster 16    |                    |
|--------------------+--------------------+--------------------|
|-5                  |ProAudio Spectrum 16|                    |
|--------------------+--------------------+--------------------|
|-6                  |Sound Blaster Pro   |                    |
|--------------------+--------------------+--------------------|
|-7                  |Any Sound Blaster   |                    |
|--------------------+--------------------+--------------------|
|-8                  |                    |1                   |
|--------------------+--------------------+--------------------|
|-9                  |OPL0 (original Sound|1                   |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-C                  |Sound Blaster 16    |1                   |
|--------------------+--------------------+--------------------|
|-D                  |ProAudio Spectrum 16|1                   |
|--------------------+--------------------+--------------------|
|-E                  |Sound Blaster Pro   |1                   |
|--------------------+--------------------+--------------------|
|-F                  |Any Sound Blaster   |1                   |
|--------------------+--------------------+--------------------|
|-G                  |                    |2                   |
|--------------------+--------------------+--------------------|
|-H                  |OPL0                |2                   |
|--------------------+--------------------+--------------------|
|-K                  |Sound Blaster 16    |2                   |
|--------------------+--------------------+--------------------|
|-L                  |ProAudio Spectrum 16|2                   |
|--------------------+--------------------+--------------------|
|-M                  |Sound Blaster Pro   |2                   |
|--------------------+--------------------+--------------------|
|-N                  |Any SB              |2                   |
|--------------------+--------------------+--------------------|
|-O                  |                    |3                   |
|--------------------+--------------------+--------------------|
|-P                  |OPL0 (original Sound|3                   |
|                    |Blaster chipset)    |                    |
|--------------------+--------------------+--------------------|
|-S                  |Sound Blaster 16    |3                   |
|--------------------+--------------------+--------------------|
|-T                  |ProAudio Spectrum 16|3                   |
|--------------------+--------------------+--------------------|
|-U                  |Sound Blaster Pro   |3                   |
|--------------------+--------------------+--------------------|
|-V                  |Any SB              |3                   |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''

<pre class="western">/-------------------------------------------------------------\
|Hardware Code       |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|W0                  |Pioneer laser disc V80000               |
|--------------------+----------------------------------------|
|W1                  |Pioneer laser disc V4400                |
|--------------------+----------------------------------------|
|W2                  |Pioneer laser disc V4200                |
|--------------------+----------------------------------------|
|W3                  |Pioneer laser disc V4300D               |
\-------------------------------------------------------------/</pre>
Video Hardware Codes

'''VCA'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |VCA                 |Number of Cards     |
|                    |                    |Unspecified         |
|--------------------+--------------------+--------------------|
|4-                  |                    |                    |
|--------------------+--------------------+--------------------|
|5-                  |1                   |                    |
|--------------------+--------------------+--------------------|
|6-                  |2                   |                    |
|--------------------+--------------------+--------------------|
|C-                  |                    |1                   |
|--------------------+--------------------+--------------------|
|D-                  |1                   |1                   |
|--------------------+--------------------+--------------------|
|E-                  |2                   |1                   |
|--------------------+--------------------+--------------------|
|K-                  |                    |2                   |
|--------------------+--------------------+--------------------|
|L-                  |1                   |2                   |
|--------------------+--------------------+--------------------|
|M-                  |2                   |2                   |
\--------------------------------------------------------------/</pre>
'''OEM'''



<pre class="western">/--------------------------------------------------------------\
|Hardware Code       |OEM                 |Number of CDROMs    |
|--------------------+--------------------+--------------------|
|-0                  |Any video capture   |                    |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-1                  |Any video capture   |                    |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-2                  |Any video capture   |                    |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16         |                    |
|--------------------+--------------------+--------------------|
|-8                  |Any video capture   |1                   |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-9                  |Any video capture   |1                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-A                  |Any video capture   |1                   |
|                    |card and a ProAudio |                    |
|                    |Spectrum 16         |                    |
|--------------------+--------------------+--------------------|
|-G                  |Any video capture   |2                   |
|                    |card                |                    |
|--------------------+--------------------+--------------------|
|-H                  |Any video capture   |2                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
|--------------------+--------------------+--------------------|
|-I                  |Any video capture   |2                   |
|                    |card and a Sound    |                    |
|                    |Blaster 16          |                    |
\--------------------------------------------------------------/</pre>
'''Special Hardware Needs'''



<pre class="western">/-------------------------------------------------------------\
|Hardware Code       |Special Hardware Needs                  |
|--------------------+----------------------------------------|
|X0                  |IBM VCA NTSC                            |
|--------------------+----------------------------------------|
|X1                  |Jovian SuperVia NTSC                    |
|--------------------+----------------------------------------|
|X2                  |Jovian QuickVia NTSC                    |
|--------------------+----------------------------------------|
|X3                  |Video Blaster NTSC                      |
|--------------------+----------------------------------------|
|X4                  |IBM VCA  PAL                            |
|--------------------+----------------------------------------|
|X5                  |Jovian SuperVia  PAL                    |
|--------------------+----------------------------------------|
|X6                  |Jovian QuickVia  PAL (WinMovie)         |
|--------------------+----------------------------------------|
|X7                  |Video Blaster PAL                       |
\-------------------------------------------------------------/</pre>




=== Running the Test Suites ===

The suites are run using P2STRING. For more information about P2STRING, see [[00112.htm|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:

<pre class="western">SETENV</pre>
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:

<pre class="western">RESETINI</pre>
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:

<pre class="western">P2STRING inp_file [-a]out_file [-eerr_file] [-d|-D] [-E] [-t]</pre>


For more information about running tests from the command line, see [[00117.htm|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 &quot;Script completed successfully&quot; 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 &quot;Script completed successfully&quot; 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.

<pre class="western">  TEST SCRIPT  (AUDIO1.P80)


         ############################################
         #                                          #
         #   OPEN THE MIDIPLAYER                    #
         #   WAIT FOR SUCCESSFUL OPEN               #
         #                                          #
         ############################################
         #
 /---&gt;   open sequencer alias midiplayer notify
 |/--&gt;   +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                     #
 ||      #                                          #
 ||      ############################################
 ||      #
 ||  /-&gt; 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.
 \|--|--------&gt; T:1 send string #  1 open sequencer alias midiplayer notify
  \--|--------&gt; EXPECTED NOTIFY FOR #1: MM_MCINOTIFY SUCCESSFUL by MCI_OPEN script param= 1
     |     |--&gt; T:1 Notify received for #  1 MM_MCINOTIFY SUCCESSFUL by command MCI_OPEN ID 1
     |     \--&gt; 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
     \--------&gt; T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
           |--&gt;  no returned string for #  2.
           \--&gt; 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</pre>
The first command &quot;open sequencer alias midiplayer notify&quot; in the test expects the following results:

<pre class="western">+MM_MCINOTIFY MCI_NOTIFY_ABORTED MCI_PLAY</pre>
Following the first and second line down in the previous example, you can see that this command passed successfully:

<pre class="western">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</pre>
The following lines in the test script are not expecting returned information:

<pre class="western">@WAIT_NOTIFY 1 45000
@WAIT_PASSDEVICE midiplayer</pre>
Therefore, the test output echoes these commands to show they were received .

<pre class="western">T:1 @WAIT_NOTIFY 1 45000
T:1 @WAIT_PASSDEVICE MIDIPLAYER</pre>
However, the &quot;load midiplayer ?MMDATA-AUD?\jesu.mid wait&quot; command did not receive the expected message, and the following is logged to the test file:

<pre class="western">T:1 send string #  2 load midiplayer D:\SYSTEST\DATA-AUD\type1.mid  wait
 no returned string for #  2.
NOTIFY STATUS FOR #2: FAILED</pre>
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.



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

[[Category:Driver Articles]]
[[Category:MMOS/2]]
[[Category:Multimedia]]
[[Category:MIDI]]