Test Script Services Reference

prevnext

Utility Commands


Use the utility commands to perform actions common to many test scripts.


Summary

The following table lists the utility commands.

Command Description
ApplicationPid Gets the process ID of an application.
ApplicationStart Starts an application.
ApplicationWait Waits for an application to terminate.
Delay Delays the specified number of milliseconds.
ErrorDetail Retrieves error information about a failure.
GetComputerConfiguration
AttributeList
Gets the list of computer configuration attributes and their values.
GetComputerConfiguration
AttributeValue
Gets the value of a computer configuration attribute.
GetPath Gets a pathname.
GetScriptOption Gets the value of a script playback option.
GetTestCaseConfiguration
Attribute
Gets the value of a test case configuration attribute.
GetTestCaseConfiguration
AttributeList
Gets the list of test case configuration attributes and their values.
GetTestCaseConfigurationName Gets the name of the configuration (if any) associated with the current test case.
GetTestCaseName Gets the name of the test case in use.
GetTestToolOption Gets a test case tool option.
JavaApplicationStart Starts a Java application.
NegExp Gets the next negative exponentially distributed random number with the specified mean.
Rand Gets the next random number.
SeedRand Seeds the random number generator.
StdErrPrint Prints a message to the virtual tester's error file.
StdOutPrint Prints a message to the virtual tester's output file.
Uniform Gets the next uniformly distributed random number in the specified range.
UniqueString Returns a unique text string.


ApplicationPid

Gets the process ID of an application.


Syntax

pid = `tsscmd ApplicationPid appHandle`

Element Description
appHandle The ID of the application whose PID you want to get. Returned by ApplicationStart or JavaApplicationStart.


Return Value

On success, this command returns the system process ID of the specified application. It exits with one of the following values :


Comments

This command works for applications started by ApplicationStart or JavaApplicationStart.

A successful invocation does not imply that the application whose PID is returned is still alive nor guarantee that the application is still running under this PID.


Example

This example returns the PID of application myApp.

myAppHandle = `tsscmd ApplicationStart myApp`
myAppPID = `tsscmd ApplicationPid myAppHandle`

See Also

ApplicationStart, ApplicationWait,JavaApplicationStart

ApplicationStart

Starts an application.


Syntax

handle = `tsscmd ApplicationStart [-workdir workingDir] 
appHandle`

Element Description
appHandle The pathname of the application to be started, which can include options and arguments. The file suffix can be omitted.
workingDir The directory in which to start the application. The current directory if not specified.


Return Value

On success, this command returns a handle for the started application. It exits with one of the following values:


Comments


Example

This example starts application myApp.

myAppHandle = `tsscmd ApplicationStart myApp`

See Also

ApplicationPid, ApplicationWait,JavaApplicationStart

ApplicationWait

Waits for an application to terminate.


Syntax

tsscmd ApplicationWait [-timeout msec] app

Element Description
app The application that you are waiting for. Returned by ApplicationStart or JavaApplicationStart.
exitStatus OUTPUT. If not NULL, the exit status of app.
msec The number of milliseconds to wait for app to terminate or 0 to return immediately.


Return Value

This command exits with one of the following results:


Comments

This command works for applications started by ApplicationStart or JavaApplicationStart.


Example

This example waits 600 milliseconds for application myApp to terminate.

myAppHandle = `tsscmd ApplicationStart myApp`
tsscmd ApplicationWait -timeout 600 myAppHandle

See Also

ApplicationPid, ApplicationStart,JavaApplicationStart

Delay

Delays script execution for the specified number of milliseconds.


Syntax

tsscmd Delay msecs

Element Description
msecs The number of milliseconds to delay script execution.


Return Value

This command exits with one of the following results:


Comments

The delay is scaled as indicated by the contents of the Delay_dly_scale environment variable. The accuracy of the time delayed is subject to operating system limitations.


Example

This example delays execution for 10 milliseconds.

tsscmd Delay 10

ErrorDetail

Retrieves error information about a failure.


Syntax

errorText=`tsscmd ErrorDetail`

Return Value

This command returns 0 if the previous command succeeded. If the previous command failed, ErrorDetail returns one of the error codes listed below and corresponding errorText.


Example

This example opens a datapool and, if there is an error, displays the associated error message text.

dpid = `tsscmd DatapoolOpen custdata`
errorText = `tsscmd ErrorDetail`

GetComputerConfigurationAttributeList

Gets the list of computer configuration attributes and their values.


Syntax

config = `tsscmd GetComputerConfigurationAttributeList 
[-single]`

Return Value

This command exits with one of the following results:


Comments

You create and maintain computer configuration attributes from TestManager. This command returns the current settings.

The computer configuration attribute list can be obtained in either of two formats:


Example

This example returns the current computer configuration attribute list.

config = `tsscmd GetComputerConfigurationAttributeList`

See Also

GetComputerConfigurationAttributeValue


GetComputerConfigurationAttributeValue

Gets the value of computer configuration attribute.


Syntax

value = `tsscmd GetComputerConfigurationAttributeValue name`

Element Description
name The name of the computer configuration attribute whose value is to be returned.


Return Value

On success, this command returns a handle for the started application. It exits with one of the following values.


Example

This example returns the value of the configuration attribute Operating System.

OSVal = `tsscmd GetComputerConfigurationAttributeValue "Operating 
System"`

See Also

GetComputerConfigurationAttributeList


GetPath

Gets the root path of a test asset.


Syntax

value = `tsscmd GetPath pathKey`

Element Description
pathKey Specifies one of these values:
  • SOURCE_PATH to get the root path of the test script source from which the currently executing test script was selected. On an agent, this is the root of the destination to which files are copied from the local computer.

  • ATTACHED_LOG_FILE_PATH to get the root of files attached to the log.


Return Value

On success, this command returns the root of the currently executing test script or of the files attached to the log. On failure, it returns nothing: call ErrorDetailfor information.


Comments

The root path returned by this command might be the exact location where an asset is stored, but it need not be. For example, in the fully-qualified pathname C:\Datastore\TestScripts, C: might be the root path and Datastore\TestScripts a pathname relative to the root path.

For test scripts run from TestManager, the returned root path is a value in shared memory for the current virtual tester at the time of the call. For test scripts run stand-alone (outside TestManager), the returned root path is a value set by Context.


Example

This example returns the root path of the source from which the currently executing test script was selected.

scriptPath = `tsscmd GetPath SOURCE_PATH`

See Also

Context, UniqueString


GetScriptOption

Gets the value of a test script playback option.


Syntax

optVal=`tsscmd GetScriptOption optionName`

Element Description
optionName The name of the script option whose value is returned.


Return Value

On success, this command returns the value of the specified script option, or NULL if the value specified is not used by the execution adapter. The command exits with one of the following results:


Comments

TestManager users can set the values of test script playback options. These may be options specifically supported by a Test Script Execution Adapter (TSEA), or arbitrarily named user-defined options. The common way to use test script options in a test script is to query an option's value with this call and branch according to its returned value.

The Command Line adapter supports these options: _TM_CMDLINE_WORKING_DIR, _TM_CMDLINE_LEFT_PARAM_DELIM, _TM_CMDLINE_RIGHT_PARAM_DELIM, _TM_CMDLINE_ESCAPE_CHAR, _TM_SHELLCMD_ARGS, _TM_PASSWORD, _TM_USERNAME, _TM_PROJECT_PATH, _TM_PROJECT_NAME. These options have initial values that can be changed from TestManager.


Example

This example gets the current working directory.

optVal = `tssscmd GetScriptOption _TM_CMDLINE_WORKING_DIR`

GetTestCaseConfigurationAttribute

Gets the value of the specified test case configuration attribute.


Syntax

config = `tsscmd GetTestCaseConfigurationAttribute [-single] 
name`

Element Description
name Specifies the name of the configuration attribute to be returned.


Return Value

On success, this command returns the value of the specified test case configuration attribute. It exits with one of the following results:


Comments

You create and maintain test case configuration attributes from TestManager. This command returns the value of the specified attribute for the current test case.

The test case configuration attribute value can be obtained in either of two formats:


Example

This example returns the value of the configuration attribute Operating System.

OSVal = `tsscmd GetTestCaseConfigurationAttribute "Operating System"`

See Also

GetTestCaseConfigurationAttributeList


GetTestCaseConfigurationAttributeList

Gets the list of test case configuration attributes and their values.


Syntax

config = `tsscmd GetTestCaseConfigurationAttributeList 
[-single]`

Return Value

This command exits with one of the following results:


Comments

You create and maintain test case configuration attributes from TestManager. This command returns the current settings for the current test case.

The test case configuration attribute value can be obtained in either of two formats:


Example

This example returns the current test case configuration attribute list.

config = `tsscmd GetTestCaseConfigurationAttributeList`

See Also

GetTestCaseConfigurationAttribute


GetTestCaseConfigurationName

Gets the name of the configuration (if any) associated with the current test case.


Syntax

config=`tsscmd GetTestCaseConfigurationName`

Return Value

On success, this command returns the name of the configuration associated with the test case in use. The command exits with one of the following results:


Comments

A test case specifies the pass criteria for something that needs to be tested. A configured test case is one that TestManager can execute and resolve as pass or fail.


Example

This example retrieves the name of a test case configuration.

tcConfig = `tsscmd GetTestCaseConfigurationName`

GetTestCaseName

Gets the name of the test case in use.


Syntax

testcase=`tsscmd GetTestCaseName`

Return Value

On success, this command returns the name of the current test case. The command exits with one of the following results:


Comments

Created from TestManager, a test case specifies the pass criteria for something that needs to be tested.


Example

This example stores the name of the test case in use in tcName.

tcName = `tsscmd GetTestCaseName`

GetTestToolOption

Gets the value of a test tool execution option.


Syntax

optVal=`tsscmd GetTestToolOption optionName`

Element Description
optionName The name of the test tool execution option whose value is returned.


Return Value

On success, this command returns the value of the specified test tool execution option. On failure, it returns nothing: call ErrorDetail for information.


Comments

If you develop adapters for a new test script type that support options, you can use this command to get the value of a specified option.


Example

This example returns the value of an option called persist.

optval = `tsscmd GetTestToolOption "persist"`

JavaApplicationStart

Starts a Java application.


Syntax

handle = `tsscmd JavaApplicationStart [-workdir workingDir] 
[-classpath classPath] [-jvm JVM] [-jvmoptions JVMOptions] 
app`

Element Description
app The pathname of the application to be started, which can include options and arguments. The file suffix can be omitted.
workingDir The directory in which to start the application.
classPath The Java classpath. The specified value replaces the current classpath.
JVM The pathname of Java Virtual Machine. If not specified, java.exe is used on Windows machines and java on UNIX agent platforms.
JVMOptions Any valid JVM options may be specified.


Return Value

On success, this command returns a handle for the started application. It exits with one of the following values.


Example

This example starts application myJavaApp.

myAppHandle = `tsscmd JavaApplicationStart myApp`

See Also

ApplicationPid, ApplicationStart, ApplicationWait

NegExp

Gets the next negative exponentially distributed random number with the specified mean.


Syntax

nnext=`tsscmd NegExp mean`

Element Description
mean The mean value for the distribution.


Return Value

This command returns the next negative exponentially distributed random number with the specified mean, or -1 if there is an error. The command exits with one of the following results:


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.


Example

This example seeds the generator and gets a random number with a mean of 10.

tsscmd SeedRand 10
next = `tsscmd NegExp 10`

See Also

Rand, SeedRand, Uniform

Rand

Gets the next random number.


Syntax

next=`tsscmd Rand`

Return Value

This command returns the next random number in the range 0 to 32767, or -1 if there is an error. The command exits with one of the following results:


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.


Example

This example gets the next random number.

next = `tsscmd Rand`

See Also

SeedRand, NegExp, Uniform

SeedRand

Seeds the random number generator.


Syntax

tsscmd SeedRand seed

Element Description
seed The base integer.


Return Value

This command exits with one of the following results:


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.

SeedRand uses the argument seed as a seed for a new sequence of random numbers to be returned by subsequent calls to the Rand routine. If SeedRand is then called with the same seed value, the sequence of random numbers is repeated. If Rand is called before any calls are made to SeedRand, the same sequence is generated as when SeedRand is first called with a seed value of 1.


Example

This example seeds the random number generator with the number 10:

tsscmd SeedRand 10

See Also

Rand, NegExp, Uniform

ePrint

Prints a message to the virtual tester's error file.


Syntax

tsscmd ePrint message

Element Description
message The string to print.


Return Value

This command exits with one of the following results:


Example

This example prints to the error file the message Login failed. The quotes are optional.

tsscmd ePrint "Login failed"

See Also

Print


Print

Prints a message to the virtual tester's output file.


Syntax

tsscmd Print message

Element Description
message The string to print.


Return Value

This command exits with one of the following results:


Example

This example prints the message Login successful. The quotes are optional.

tsscmd Print "Login successful"

See Also

ePrint


Uniform

Gets the next uniformly distributed random number.


Syntax

unext=`tsscmd Uniform low high`

Element Description
low The low end of the range.
high The high end of the range.


Return Value

This command returns the next uniformly distributed random number in the specified range, or -1 if there is an error. The command exits with one of the following results:


Comments

The behavior of the random number generator routines is affected by the settings of the Seed and Seed Flags options in a TestManager suite. By default, TestManager sets unique seeds for each virtual tester, so that each has a different random number sequence.

If the error return value -1 is a legitimate value for the specified range, then TSSErrorDetail exits with value 0.


Example

This example gets the next uniformly distributed random number between -10 and 10.

next = `tsscmd Uniform -10 10`

See Also

Rand, SeedRand, NegExp

UniqueString

Returns a unique text string.


Syntax

str =`tsscmd UniqueString`

Return Value

On success, this command returns a string guaranteed to be unique in the current test script or suite run. On failure, it returns NULL: call ErrorDetailfor information.


Comments

You can use this command to construct the name for a unique asset, such as a test script source file.


Example

This example returns a unique text string.

str = `tsscmd UniqueString`

prevnext


The Command Line Interface to Rational Test Script Services Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com