Test
Automation
Subsystem
List
Top
level

Parameterizing QAP Scripts

Passing
Parameters
to Scripts 		Retrieving
Parameters 		Using
Parameter
Files 		More About
Scripts and
Parameters 		Implementation
Details 		Parameter
Methods

See also:

Standard
Parameters 		PRODUCT
Parameters 		Recovery
Framework 		PRODUCT
Recovery System

Introduction

 The Recovery Framework supports the parameterization of test scripts. This means that you can pass parameters to a test script to modify its behaviour, without modifying the script itself.

Some examples of script parameters are:

From the user's perspective, there are three ways to pass parameters to a script:

Passing Parameters Directly to Scripts

You can pass a parameter to a script by specifying the name and value of the parameter in a suite file, following the name of the script.

For example, let's say we have a script named "MyScript.t", and we want to pass it a parameter named "Project" whose value is "MyPALproject". In order to do this, we would need a test suite that contained the following line: 

    MyScript.t  "Project = 'MyPALproject';"
Notice the double quotes around the entire assignment statement.

In suite (.s) files -- and nowhere else -- QAP treats every sequence of non-white spaces as a single script argument and throws away the intervening spaces, unless the sequence begins with a single or double quote. When QAP encounters a single quote (following a space) it takes everything up to the next single quote as a single script argument, keeping the single quotes. When QAP encounters a double quote (following a space) it takes everything up to the next single quote as a single script argument -- and throws away the enclosing double quotes.

Here are some examples of how QAP translates suite file arguments, and whether or not the example will work:

What Appears in the Suite File    What Your Script Gets as Arguments    Works?
script.t x=5; x=5; yes
script.t x = 5; x   =   5; yes
script.t x="hello"; x="hello"; yes
script.t x = "hello"; x   =   hello   ; NO
script.t 'x="hello";' 'x="hello";' NO
script.t 'x = "hello";' 'x = "hello";' NO
script.t "x='hello';" x='hello'; yes
script.t "x = 'hello';" x = 'hello'; yes

Thus, to ensure that parameter assignment statements are interpreted correctly, you must enclose each one (or all of them together) in double quotes -- but only in suite files.

Retrieving Parameters in Your Script

To retrieve a parameter's value inside your script so that you can use it, you must call one of the parameter retrieval routines provided by the Recovery Framework. For example:

// MyScript.t

use "MCdefs.inc";

main ()
{
    string sProjName = "DefaultProject";

    RECgetStringParam("Project", sProjName);    

    gwPRJwindow.OpenNewProject(sProjName);
}

In the preceding example, OpenNewProject will open the project "MyPALproject".

Using Parameter Files

If your script uses many parameters, specifying all of them on a single line of a suite file can be unwieldy. Instead, you can specify any number of parameters in a Parameter File. Here is an example of a parameter file:

// MyParamFile.dat
DefaultProject = "myProject";
ProjectFormat = "PAL";
NumberOfAudioTracks = 4;
SequenceName = "MySequence";
DeleteMediaFiles = FALSE;

Note that the syntax for parameters is different, depending on whether the parameters are in a parameter file or in a suite file. This is because QAP treats suite file arguments in a less-than-ideal manner, over which we have no control. On the other hand, we have complete control over the syntax of parameter files, and thus can make the syntax more reasonable. You can find a complete description of parameter file syntax here.

Once you have a parameter file, you can pass the name of the parameter file to your script through a suite file, for example: 

    MyScript.t  "use MyParamFile.dat";
Note that you must put quotes around the "use" statement in a suite file.

You can pass any number of parameters or parameter files to a script. If a parameter is defined in more than one file, the rightmost one takes precedence. If you specify a parameter twice in the same file, an exception is raised.

Where Do Parameter Files Live?

If a "use" statement specifies a partially qualified path name, then the file must reside in the QAP Input Data directory specified by the glsMC_INPUT_DATA_DIR constant in MClocal.inc. Parameter files should live in the appropriate subsystem's directory in the input data directory.

You can also use a fully qualified path name in a "use" statement, but this practice should be avoided.

The default parameter file, which is read automatically by the recovery system, is specified by the glsREC_DEFAULT_PARAMETER_FILE parameter in your MClocal.inc file.

More About Scripts and Parameters

A script should never require parameters. It should always be able to run on its own.

Many parameters will be ignored by many scripts. The documentation (web page) for each script must document which parameters, if any, the script uses.

Parameters are intended to be used as arguments to a script, i.e. to main(). They must never be used implicitly inside subsystem APIs, except for the Recovery System.

Parameter values must never be modified by a script.

You can find a list of pre-defined system parameters here. If your script needs parameters that are specific to that script alone, those parameter names should begin with the subsystem prefix.

Implementation Details

The parameter file (if any) is read and interpreted by the recovery system at the beginning of each script (i.e. by ScriptEnter).

Parameter Retrieval Routines

The following routines are provided by the Recovery Framework. Each of these routines returns a boolean value that tells whether the parameter was defined. If it wasn't, then the output parameter of the routine is left unchanged.

boolean RECgetBooleanParam (string sParamName, out boolean bValue)
boolean RECgetIntegerParam (string sParamName, out integer iValue)
boolean RECgetListParam (string sParamName, out list of anytype laValue)
boolean RECgetRealParam (string sParamName, out real rValue)
boolean RECgetStringParam (string sParamName, out string sValue)

The following routines are provided by other subsystems for retrieving more complex parameters.

boolean MONgetClipParam (string sParamName, out string sClipName, out string sMarkIn, out string sMarkOut, out MONposTypeAndTrack uPosType)
boolean MONgetPosTypeParam (string sParamName, out MONposTypeAndTrack uPosType)

This page is maintained by (REMOVED).
It was last updated on 10 September 1998.