QAA
API
Subsystem
list
Top
level

Common Utilities

This is a collection of common 4Test utility functions that don't belong to (or depend on) any particular subsystem.

Defined in: CommonUtils.inc

Data
Types 		Error Reporting
Routines 		Results File Indentation
Block Routines 		Other Results
File Routines 		Debugging
Routines 		Miscellaneous
Routines

Data Types

CUstringOrList -- a string or a list of strings
CUloggingOption -- logging options
CUfeature -- identifies a product feature
CUfeatureOrList -- a feature or list of features
CUtestPhase -- describes a phase of testing

Error Reporting Routines

See also Assertions.

list of CALL CUgetCallStack ( );
void CUlogCallStack (list of CALL luCalls, integer iSkip optional);
void CUlogError (string sErrorMessage);
void CUsetupError (string sErrorMessage);
void CUlogException (string sAdditionalInfo optional);
void CUlogWarning (string sWarningMessage);
void CUobsoleteRoutineWarning (string sNewRoutineName);
void LogHack (string sYourNameAndTheDate);

Results File Indentation Block Routines

CUlogBlockState CUbeginLogBlock (string sDescription);
void CUendLogBlock (string sDescription);
CUlogBlockState CUgetLogBlockState ( );
void CUrestoreLogBlockState (CUlogBlockState uState);
void CUlogBlockNesting ( );

Feature & Test Phase Routines

CUlogBlockState CUbeginFeatureTest (CUfeatureOrList uFeature);
void CUendFeatureTest (CUfeatureOrList uFeature);
void CUtestcaseFeature (CUfeatureOrList uFeature);
void CUlogTestPhase (CUtestPhase ePhase);
CUlogBlockState CUbeginTestOutOfContext (varargs of CUfeature);
void CUendTestOutOfContext (varargs of CUfeature);
list of CUfeature CUgetFeatureContext ();
string CUfeatureToString (CUfeature uFeature);

Other Results File Routines

void CUdisambiguateTC (varargs of anytype);
void CUlogOutputFileName (string sFullPathName);
void CUlogGuiAction (string sAction, window w);
void CUlogScreenShot ();
boolean CUloggingOptionEnabled (CUloggingOption eOption);

Debugging Routines

void CUdebugPrint (string sSubsystemPrefix, varargs of anytype);
boolean CUdebugEnabled (string sSubsystemPrefix);
void CUenableDebug (string sSubsystemPrefix, boolean bOn optional);

Miscellaneous Routines

string CUconcatPath (varargs of CUstringOrList);
void CUensurePathExists (list of string lsPath);
string CUgetDateTimeString ();
boolean CUisInRect (int iX, int iY, RECT rRect);
anytype CUmapList (list of anytype list1, anytype element1, list of anytype list2);
anytype CUmapTemplateToList (list of string list1, string element1, list of anytype list2 optional);
boolean CUstringIsEnumVal (string s, DATATYPE enumType);
boolean CUisDefined (string sVariableName, out anytype aValue optional);
string CUintegerToString (integer iValue, integer iRadix, string sDigits optional);
integer CUregisterSourceFile (list of string lsSourceTreePath, list of string lsSourceFilePath);
void CUcopyDirectoryAndContents (string sOriginalPath, string sDestinationPath);
integer _CUdeleteDirectoryAndContents (string sPath);

CUstringOrList

This is a data type whose value can be either a string or a list of string.

Declaration

type CUstringOrList is { string, list of string };

CUloggingOption

This enum type defines various options for what appears in the results file.
If you're executing a script, you can select the options you want by setting the value of glsCU_LOGGING_OPTIONS in MClocal.inc.
If you're writing or maintaining scripts or infrastructure, you can determine what options have been selected by calling CUloggingOptionEnabled.

Declaration

type CUloggingOption is enum { /* see below */ };

Values

eCU_LOG_GUI_ACTIONS When this option is enabled, every action performed by the script on the application's UI is logged in the results file. This option is not used by scripts or testcases, but only by the methods and subroutines of the infrastructure.
eCU_LOG_VERBOSE This option enables additional output. If it is used at all, it is used only by scripts and testcases, not by the infrastructure.
eCU_OBSOLETE_WARNING This option causes notifications of obsolete API features to be reported as warnings rather than as errors.
eCU_LOG_FULL_FEATURE_CONTEXT This option causes the complete feature context to be reported on every feature block. Without this option, only the individual feature is reported. (Not available yet.)

CUfeature

This is a data type whose value identifies a feature or functional area of the application. The implementation of this type is private. You can convert a CUfeature to a readable text string by calling CUfeatureToString.

Features are defined as constants. PRODUCT features are defined in "Shared/AllFeatures.inc".

See also Product Features - Identification & Management .

CUfeatureOrList

This data type can be either a CUfeature or a list of CUfeature.

CUtestPhase

This is a data type whose value identifies one of the phases of a test (see below). For information on usage, see CUlogTestPhase.

1. eCU_TEST_SETUP Perform any setup that the test requires, such as opening bins, loading sequences, changing settings, etc. Some tests may not require any setup; some or all of a test's setup may be performed implicitly by the recovery system.
2. eCU_TEST_EXECUTE This phase should only include the operation being tested. Typically, this phase will consist of a single call to a subroutine or method. Every test must include this phase.
3. eCU_TEST_VERIFY Verify the results of the test, to ensure that the test was successful. Some verification may be performed implicitly by the infrastructure and/or the recovery system.
4. eCU_TEST_CLEANUP Perform any cleanup that the test requires, such as deleting sequences, closing dialogs, etc. You should normally leave around anything that the test created, so that it can be examined after the test script finishes running. Most tests will not require this phase.
5. eCU_TEST_RESULTS Report any results from the test, e.g. timing or performance information. Most tests will not require this phase.

Declaration

type CUtestPhase is enum { /* see above */ };

CUbeginFeatureTest

You should call this in your script to indicate the beginning of a section of the script that tests a particular functional area. Every call to CUbeginFeatureTest must have a matching call to CUendFeatureTest later in your script. This routine implicitly sets the current test phase to eCU_TEST_SETUP.

You must not call this routine from inside a testcase. If you do, an assertion will fail. To set the feature for a testcase, use CUtestcaseFeature.

See also Product Features - Identification & Management .

Declaration

CUlogBlockState CUbeginFeatureTest (CUfeatureOrList uFeature);

Inputs

uFeature
The feature about to be tested. If a list of features is provided, each feature in the list narrows the function area.

Outputs

Returns
A magic value that identifies this indentation block. You will only need this if you need to call CUrestoreLogBlockState.

CUbeginLogBlock

Opens a new indentation block in the results file. You should use this instead of calling the built-in 4Test function ResOpenList directly. Every call to CUbeginLogBlock must have a matching call to CUendLogBlock later in your code.

Declaration

CUlogBlockState CUbeginLogBlock (string sDescription);

Inputs

sDescription
The description string that will appear in the log file.

Outputs

Returns
A magic value that identifies this indentation block. You will only need this if you need to call CUrestoreLogBlockState.

CUconcatPath

This routine constructs a file name from individual directory names, adding the appropriate directory delimiter characters for the host system. It takes any number of arguments, each of which may be either a string or a list of strings. Each individual string, whether an individual argument or part of a list, must specify one directory. The last string may (but need not) specify a file name. On Windows NT, the first string must be a single character (drive letter).

Declaration

string CUconcatPath (varargs of CUstringOrList luStrings);

Inputs

luStrings
Each argument may be a string or a list of strings. Each individual string specifies a directory.

Outputs

Returns
A string containing the concatenation of all the directory strings, with directory delimiters between them.

Example of Usage

HFILE file = FileOpen(CUconcatPath(glsMC_INPUT_DATA_DIR, "MyInputFile"), FM_READ);

CUdebugPrint

Use this routine to print debugging statements to the results file. It works just like Print, except that the first argument must a string containing the subsystem prefix, e.g. "BIN", "PRJ", "REC", "EDL", etc. For debugging statements in a script, use "script". Do not conditionalize calls to CUdebugPrint; the test for whether or not to actually print anything is built into the routine.

You can enable debugging statements by adding strings to the variable glsCUdebugPrint in MClocal.inc. This variable contains a list of subsystem prefix strings. When CUdebugPrint is called, it checks to see if its sSubsystemPrefix parameter appears in glsCUdebugPrint. If it does, the debugging statement is printed; otherwise, it is not. You can also specify "all" in glsCUdebugPrint to enable all debugging statements.

Declaration

void CUdebugPrint(string sSubsystemPrefix, varargs of anytype);

Inputs

sSubsystemPrefix
The upper-case name prefix for the subsystem that's calling CUdebugPrint, e.g. "BIN", "PRJ", "REC", "EDL", etc., or "script" if it's for a script.

Outputs

(none)

Example of Usage

window BINopenBin (string sName)
{
    window w;
    CUdebugPrint("BIN", "BINopenBin(" + sName + ")");

    // ... open the bin and assign "w" to be the bin window

    CUdebugPrint("BIN", "    return " + [string] w);
    return w;
}

CUdisambiguateTC

If you have a testcase that will be called multiple times to test different things, you should call this routine from inside your testcase. It logs information to the results file which is used to disambiguate different invocations of a single testcase, and to identify when the same test has been performed by different invocations of the same test script.

In most cases, you can simply pass all the parameters for your testcase to CUdisambiguateTC. Note, however, that sometimes a parameter may change when, in fact, the test is the same. An example of this is bin mob IDs. Such parameters should not be passed to CUdisambiguateTC.

All the parameters passed to CUdisambiguateTC are converted to text strings and concatenated into a single string. The length of this concatenated string must not exceed 255 characters.

You may call CUdisambiguateTC at most once in any testcase. Calling it more than once within the same testcase is illegal. You can call it anywhere in the testcase, but you should call it near the top of the testcase so that it won't be skipped over because of exceptions raised during the actual test execution.

Declaration

void CUdisambiguateTC (varargs of anytype)

Inputs

One or more parameters of any type may be provided. At least one parameter must be provided.

Outputs

(none)

Example of Usage

testcase tcMyTestcase (integer iArg1, string sArg2)
{
    CUdisambiguateTC(iArg1, sArg2);

    // ... body of testcase ...
}

CUendFeatureTest

You should call this function in your script to mark the end of a section that tests a particular feature. Every call to CUbeginFeatureTest must have a matching call to CUendFeatureTest later in your script. This routine implicitly sets the test phase to eCU_TEST_CLEANUP.

See also Product Features - Identification & Management .

Declaration

void CUendFeatureTest (CUfeatureOrList uFeature);

Inputs

uFeature
This must match the feature or feature list in the corresponding call to CUbeginFeatureTest. This is to ensure that you don't forget to match up your calls to CUbeginFeatureTest and CUendFeatureTest.

Outputs

None.

CUendLogBlock

Closes an indentation block in the results file. You should use this instead of calling the built-in 4Test function ResCloseList directly. Every call to CUbeginLogBlock must have a matching call to CUendLogBlock later in your code.

Declaration

void CUendLogBlock (string sDescription);

Inputs

sDescription
This must match the description string in the corresponding call to CUbeginLogBlock. This is to ensure that you don't forget to match up your calls to CUbeginLogBlock and CUendLogBlock.

Outputs

None.

CUensurePathExists

This routine ensures that a path exists by creating each directory in the path if it doesn't already exist.

Declaration

void CUensurePathExists (list of string lsPath);

Inputs

lsPath
A pathname, specified as one directory per string, without delimiters.

Outputs

None

Example of Usage

CUensurePathExists(glsMC_OUTPUT_DATA_DIR + { "MySubsysDir", "MyTestDir" });

CUfeatureToString

This routine returns a string containing the name of a given feature. This is the same string that appears in the results file, and is the "official" name of the feature.

Declaration

string CUfeatureToString(CUfeature uFeature);

Inputs

uFeature
The feature to be converted to a string.

Outputs

Returns
A string containing the name of the given feature.

CUgetCallStack

This routine returns the current call stack, not including the CUgetCallStack routine itself. The first item in the returned list identifies the code that called CUgetCallStack; the last item in the list is main().

This routine is intended for error reporting.

Declaration

list of CALL CUgetCallStack();

Inputs

(none)

Outputs

Returns
The current call stack.

CUgetDateTimeString

(Formerly MCgetDateTimeString; arguments are the same.)

Returns a string that contains the current date and time. The string has the format: "YYMMDD.HHMMSS". For example, at 1:23:45 pm on 5 January 1996, this routine will return the string "960105.132345".

You should use this routine to create file names for output files when you want a new output file to be created every time your test runs (instead of overwriting the same output file). The string is formatted so that when such file names are sorted alphabetically, they will also be sorted chronologically.

Declaration

string CUgetDateTimeString ();

Inputs

(none)

Outputs

Returns
A string containing the current date & time.

Example of Usage

// construct path for directory containing cut lists
list of string lsFilePath = glsMC_OUTPUT_DATA_DIR;
ListAppend(lsFilePath, "Cut Lists");

// make sure the directory exists
if (! SYS_DirExists(CUconcatPath(lsFilePath))
    SYS_MakeDir(CUconcatPath(lsFilePath));

// construct path for a new cut list file
ListAppend(lsFilePath, CUgetDateTimeString());
string sFileName = CUconcatPath(lsFilePath);

// use the file name to save a cut list in
...

CUgetLogBlockState

Returns the current log block state, so that it can be later restored with a call to CUrestoreLogBlockState.

Declaration

CUlogBlockState CUgetLogBlockState ( );

Inputs

(none)

Outputs

Returns
A magic value that identifies this indentation block.

CUintegerToString

Converts an integer to string, using a specified radix and, optionally, specified digits.

Declaration

string CUintegerToString (integer iValue, integer iRadix, string sDigits optional);

Inputs

iValue
The value to be converted to a string.
iValue
The radix (base) to use in the conversion. Must be greater than 1 and less than or equal to the length of the digits string.
iDigits
A string containing the digits to use in the conversion. If specified, this string must contain at least as many digits as the given radix. If not specified, the default digits are "0"-"9", "A"-"Z".

Outputs

Returns
A string containing the given value, represented in the given radix.

CUisDefined

Determines whether the variable of a given name exists, and optionally returns its value (if it exists).

Declaration

boolean CUisDefined (string sName, out anytype aValue optional);

Inputs

sName
The name of the variable.

Outputs

Returns
TRUE if a variable of the given name exists, FALSE if it does not.
aValue
The value of the variable, if the variable exists, otherwise the output variable remains unchanged.

CUisInRect

(Formerly MCisInRect; arguments are the same.)

Determines whether the point specified by the X and Y coordinates lies within the given rectangle.

Declaration

boolean CUisInRect (int iX, int iY, RECT rRect);

Inputs

iX
The x coordinate of the point.
iY
The y coordinate of the point.
rRect
The rectangle.

Outputs

Returns
TRUE if the point lies inside the rectangle, FALSE if it lies outside.

CUlogBlockNesting

This routine logs the current block nesting context to the results file. This is particularly useful for error reporting, so that the results file can display the nesting block context next to the error, removing the need to scroll back through the results file to determine the context.

Declaration

void CUlogBlockNesting ( )

Inputs

(none)

Outputs

(none)

CUlogCallStack

This routine logs the given call stack to the results file, omitting one or more levels. This routine is intended for error reporting.

Declaration

void CUlogCallStack ( list of CALL luCalls, integer iLevelsToSkip optional);

Inputs

luCalls
The call stack to print in the results file. This will normally be obtained from ExceptCalls or CUgetCallStack.
iLevelsToSkip
If specified, this is the number of stack levels to skip.

Outputs

(none)

CUlogError

This is a wrapper for the built-in 4Test function LogError. You should always call CUlogError instead of calling LogError directly.

This routine places a standard prefix in front of the error message string, something like "ERROR:". You should not explicitly place such a prefix in your error message string. It also logs the current call stack.

Declaration

void CUlogError(string sErrorMessage);

Inputs

sErrorMessage
The error message. Do not begin the message with something like "ERROR"; CUlogError does that for you.

Outputs

(none)

CUlogException

You should normally never have to use this function. It is used to report exceptions, and exceptions are normally reported automatically by the recovery system. You should only call this if you write code that catches an exception and doesn't reraise it.

This is a wrapper for the built-in 4Test function ExceptLog. You should always call CUlogException instead of calling ExceptLog directly.

Declaration

void CUlogException(string sAdditionalInfo optional);

Inputs

sAdditionalInfo
If specified, this string will be appended to the exception string in the error message printed to the log file.

Outputs

(none)

Example of Usage

void AttemptTheImpossible()
{
    do
    {
        ... some code that attempts the impossible ...
    }
    except
    {
        if (ExceptNum() == X_SOMETHING_WENT_WRONG)
        {
            CUlogException("attempting the impossible");

            ... cleanup code ...

        }
        else reraise;  // never handle all exceptions indiscriminately!
    }
}

CUloggingOptionEnabled

Use this routine to determine whether a particular logging option is enabled. These options are set by the constant glsCU_LOGGING_OPTIONS in MClocal.inc.

Declaration

boolean CUloggingOptionEnabled (CUloggingOption eOption);

Inputs

eOption
The option you want to test for.

Outputs

Returns
TRUE if the given option is enabled, or FALSE if it is not.

CUlogGuiAction

This routine should be called in lower-level methods that manipulate the application, so that the results file can contain information about what the script did to the application. Test scripts should never call this routine; it is intended only for use by the infrastructure.

Declaration

void CUlogGuiAction(string sAction, window w);

Inputs

sAction
This should begin with a present-tense verb such as "click", "type", "select", or "close", and end in a preposition such as "in", "on", "to", or "from". If the verb takes both a direct and an indirect object, make sure that the one that isn't the window is included in the action string. For example, when reporting the selection of a menu item from a popup menu, include the name (or number) of the item in the action string.
w
The window that the action is being performed on. When calling CUlogGuiAction from a method, the window will almost always be "this". CUlogGuiAction automatically reports the window's parents.

Outputs

(none)

Example of Usage

// a method of QChildWin
void TypeKeys (string sKeys, number nDelay optional)
{
    CUlogGuiAction("type """ + sKeys + """ into", this);
    ChildWin::TypeKeys(sKeys, nDelay);
}

LogHack

This routine provides no great functionality, but it does provide a standard way of documenting within our code that we have implemented a "hack."

If you implement code that you consider to be a "hack", precede the hack with a call to this function, supplying your name (required), the current date (required), and any other info you might want to provide (optional) all as a part of the single string parameter that this function takes. And then precede all of that with sufficient comments to explain the hack to anyone who might need to undo or fix the hack or otherwise maintain, debug or understand the code in the future.

Declaration

void LogHack (string sYourNameAndTheDate);

Inputs

sYourNameAndTheDate
This required parameter can be any arbitrary string provided that the string includes at least your name, and the current date. It is optional (but recommended) to include additional descriptive information (e.g. "for problem hitting <#Enter> in NT").
The purpose of this call is to give us an easy way later on to locate code that we didn't like writing.
In order to then satisty the eventual need to fix this code, please provide copious additional comments explaining the hack.

Outputs

(none)

Comments

This function will write a warning to the log file. The warning will be easy to find in the log file, because it is prefixed with "HACK: " by the routine, and is shown in a different color by virtue of the fact that it's a warning.

We (the lords of the infrastructure) may from time to time temporarily modify this routine to cause different behavior.

Hacks (instances of this routine being called) may also be found by text-searching the script source tree.

CUlogOutputFileName

PROPOSAL - NOT AVAILABLE YET!

Use this routine to report a file which is part of your test results, but separate from the standard QAP results file. This routine will format its output in such a way that the tools that process a results file will be able to find your other file.

Declaration

void CUlogOutputFileName(string sFileName, string sDescription optional);

Inputs

sFileName
A fully qualified path name for the file, in the proper format for the local test system. Do not use relative paths, or assume current working drives or directories.
sDescription
A brief description of the output file. A detailed description of your output files should always appear in the script's documentation.

Outputs

(none)

CUlogScreenShot

This routine takes a screen shot and logs the name of the screen shot file to the results file. This routine is mainly intended for error reporting. The screen shot files are placed in the directory specified by glsCU_SCREEN_SHOT_DIR.

Declaration

void CUlogScreenShot();

Inputs

(none)

Outputs

(none)

CUlogTestPhase

You should call this routine to indicate what phase of testing you are about to perform. Each feature block can have its own set of test phases. You do not have to specify all test phases, but you must observe the proper order:
  1. eCU_TEST_SETUP
  2. eCU_TEST_EXECUTE
  3. eCU_TEST_VERIFY
  4. eCU_TEST_CLEANUP
eCU_TEST_RESULTS can appear anywhere after eCU_TEST_EXECUTE.

For more information, see the discussion in the Recovery System about defining testcases.

New Rules

The execution and verification phases can only occur inside a testcase.
CUbeginFeatureTest implicitly sets the test phase to eCU_TEST_SETUP.
CUendFeatureTest implicitly sets the test phase to eCU_TEST_CLEANUP.
When a testcase begins execution, the test phase is implicitly set to eCU_TEST_SETUP.
When a testcase finishes execution, the test phase is implicitly set to eCU_TEST_CLEANUP.
A testcase must set the phase to eCU_TEST_EXECUTE at some point during its execution (unless it terminates early because an exception was raised).

In general, you should only need to call this routine inside a testcase to set the phase to eCU_TEST_EXECUTE or eCU_TEST_VERIFY.

Declaration

void CUlogTestPhase(CUtestPhase ePhase);

Inputs

ePhase
The test phase.

Outputs

(none)

CUlogWarning

This is a wrapper for the built-in 4Test function LogWarning. You should always call CUlogWarning instead of calling LogWarning directly.

This routine places a standard prefix in front of the warning message string, something like "WARNING:". You should not explicitly place such a prefix in your warning message string. It also logs the current call stack.

Declaration

void CUlogWarning(string sWarningMessage);

Inputs

sWarningMessage
The warning message. Do not begin the message with something like "WARNING"; CUlogWarning does that for you.

Outputs

(none)

CUmapList

(Formerly MCmapList; arguments are the same.)

Maps an element of one list onto another list by looking up an element in one list and returning the corresponding element in another list. Both lists must contain the same number of elements. If the element is not found in the list, an exception is raised.

This function is intended for use in methods that convert between enums and strings (see example below).

Declaration

anytype CUmapList (list of anytype list1, anytype element1, list of anytype list2);

Inputs

list1
The list in which element1 appears.
element1
An element of list1.
list2
The list from which an element will be returned.

Outputs

Returns
The element in list2 whose position correponds to the position in list1 of element1.

Example of Usage

type CPRcolor is enum { eCPR_COLOR_MONOCHROME, eCPR_COLOR_REDUCED, eCPR_COLOR_FULL };

private list of CPRcolor leColors = 
    { eCPR_COLOR_MONOCHROME, eCPR_COLOR_REDUCED, eCPR_COLOR_FULL };
private list of string lsColors =
    { "Monochrome", "Reduced Chroma", "Full Chroma" };

window QChildWin gwCPRwindow
{
    // ...

    AMacPopupMenu    Color   { tag = "" };

    // ...

    void SetColor (CPRcolor eColor)
    {
        this.Color.Select(CUmapList(leColors, eColor, lsColors));
    }

    CPRcolor GetColor ()
    {
        return CUmapList(lsColors, this.Color.GetText(), leColors);
    }
}

CUmapTemplateToList

Matches a template (or abbreviation) string to one item in a list of string, returning the matched item, or (optionally) the corresponding item in another list, as in CUmapList.

A template is made up of regular characters and wildcard characters. The wildcard characters are asterisk ("*") and question mark. An asterisk matches zero or more characters, and a question mark matches exactly one character.

Declaration

anytype CUmapTemplateToList (list of string list1, string element1, list of anytype list2 optional);

Inputs

list1
The list in which the template (abbreviation) element1 appears.
element1
A template (abbreviation) matching an item in list1.
list2
Optional list from which an element may be returned. If this list is not provided, the matched (non-template) item from list1 is returned.

Outputs

Returns
The element in list1 matching the provided template, or the corresponding element of list2 if provided.

An exception is raised if there is no match for the template ("not found") or if there are multiple matches ("not unique").

Example of Usage

list of string lsFruits = {"Apples", "Bananas", "Pears"};

sFound = CUmapTemplateToList(lsFruits, "B*");
eFruit = CUmapTemplateToList(lsFruits, "B*", leFruitEnums);
sFound is now assigned the value "Bananas", and eFruit is assigned a value from the corresponding enumerated type.

CUobsoleteRoutineWarning

Use this routine when it is necessary to rename a subroutine or method that is part of the infrastructure. You will maintain the old routine for a period of time, in order to give people a chance to convert to the new routine. The old routine should call CUobsoleteRoutineWarning and then call the new routine.

This routine logs an error message to the results file. The error message includes the name of the old routine, the name of the new routine, and the source file name and line number where the old routine was called from. All of this information is generated automatically, except for the new routine name, which you must provide. This routine returns normally, allowing the script to proceed.

Script writers should never need to call this routine.

Declaration

void CUobsoleteRoutineWarning (string sNewRoutineName);

Inputs

sNewRoutineName
The name of the new subroutine.

Outputs

(none)

Example of Usage

boolean MCisInRect (int iX, int iY, RECT r)
{
    CUobsoleteRoutineWarning("CUisInRect");
    return CUisInRect(iX, iY, r);
}

CUregisterSourceFile

This routine must be called once in every 4Test source file, at the file level (that is, not inside a subroutine). It registers the name of the source file in order to keep track of what source (include) files are used with a particular script.

Declaration

integer CUregisterSourceFile (list of string lsSourceTreePath, list of string lsFilePath);

Inputs

lsSourceTreePath
A list of strings that define a complete path to the 4Test source tree, with one directory in each string. This is typically a variable defined in a local configuration file, such as glsMC_QAP_DIR.
lsSourceTreePath
A list of strings that define a partial path to the source file, relative to the source tree, with one directory in each string. This is typically a list containing two strings: the subsystem directory and the file name.

Outputs

Returns
Garbage. The return value is provided only so that the routine can be called at the file level; QAP only allows subroutine calls at the file level as part of a variable initialization.

Example of Usage

private integer _junk_ = CUregisterSourceFile(glsMC_QAP_DIR, { "Shared", "CommonUtils.inc" });

CUcopyDirectoryAndContents

This routine copies a directory and its contents to a different location. The contents of the directory are recursively copied to the new location.

Declaration

void CUcopyDirectoryAndContents (string sOriginalPath, string sDestinationPath);

Inputs

sOriginalPath
A string which is the complete path to the directory to copy (including the directory itself). It should contain the proper separators for the platform. This can be accomplished by creating the path using CUconcatPath to create the path string.
sDestinationPath
A string which is the complete path to the location in which to copy the new directory (including the name of the directory being created). It should contain the proper separators for the platform. This can be accomplished by creating the path using CUconcatPath to create the path string.

Outputs

NONE

Example of Usage

CUcopyDirectoryAndContents("MyDrive\MyFolder", "MyDrive\MyNewFolder");

_CUdeleteDirectoryAndContents

This routine deletes a directory and its contents.
It should be used cautiously because it will permanently delete whatever directory is specified.
The contents of the directory are recursively deleted.

Declaration

void _CUdeleteDirectoryAndContents (string sPath);

Inputs

sPath
A string which is the complete path to the directory to delete (including the directory itself). It should contain the proper separators for the platform. This can be accomplished by creating the path using CUconcatPath to create the path string.

Outputs

NONE

Example of Usage

_CUdeleteDirectoryAndContents("MyDrive\MyDirectoryToDelete");

CUrestoreLogBlockState

Restores the indentation block level to a particular level. The level to restore is specified by a value returned by CUbeginLogBlock or CUgetLogBlockState. Use this function during exception handling to restore the block level. If you don't, your indentation levels may get messed up. Note that TestcaseEnter does this for you automatically.

Declaration

void CUrestoreLogBlockState (CUlogBlockState uState);

Inputs

uState
The description string that will appear in the log file.

Outputs

None.

Example of Usage

CUlogBlockState uMyLogState = CUbeginLogBlock("my block");

do
{
    TrySomethingThatMightFail();
}
except
{
    if (ExceptNum() != SOMETHING_I_CAN_HANDLE)
        reraise;
    CUrestoreLogBlockState(uMyLogState);
    HandleMyException();
}

CUendLogBlock("my block");

CUsetupError

Raises an exception . When the exception is displayed in the results file, it will say something like "Script Setup Error"to indicate that the person executing the test script did not properly set up the system so that the test could run. This routine should only be used when the script set up is not correct, such as no test data was provided, the proper hardware is not installed, or the contents of MClocal.inc are incorrect. It is different from other assertions in that it indicates an error made by the user of the script, rather than the script writer.

Declaration

void CUlogError(string sErrorMessage);

Inputs

sErrorMessage
The error message. Do not begin the message with something like "ERROR"; CUlogError does that for you.

Outputs

(none)

CUstringIsEnumVal

Searches the values of the given enum type for an enum name that matches the given string. If a match is found, it returns TRUE. Otherwise, it returns FALSE.

Declaration

boolean CUstringIsEnumVal (string s, DATATYPE enumType);

Inputs

s
The string you are searching for in the enum type.
enumType
The enum type in which you are looking for an enum name that matches the given string.

Outputs

Returns TRUE if a match is found in the given enum type.

Example of Usage

type MyEnumType is enum { enum1, enum2, enum3 }
//if a match is found, convert(cast) the string to the enum
if(CUstringIsEnumVal("myString", MyEnumType))
{
	MyEnumType eMyEnum;
	eMyEnum = [MyEnumType]myString;	
}

CUtestcaseFeature

You can call this routine from inside a testcase to indicate what feature the testcase is testing. The feature specified is relative to any currently open feature blocks (see CUbeginFeatureTest). Calling this routine is optional, if and only if the testcase is called from within a feature block. Calling this routine more than once within the same testcase is illegal. You can call it anywhere in the testcase, but you should call it near the top of the testcase so that it won't be skipped over because of exceptions raised during the actual test execution.

See also Product Features - Identification & Management .

Declaration

void CUtestcaseFeature (CUfeatureOrList uFeature);

Inputs

uFeature
The feature about to be tested. If a list of features is provided, each feature in the list narrows the function area.

Outputs

(none)

This page is maintained by (REMOVED).
Last updated 4 May 2000 (els).