Test Script Services

prevnext

Measurement Services


Use the measurement functions to set timers and environment variables and to get the value of internal variables. Timers allow you to gauge how much time is required to complete specific activities under varying load conditions. Environment variables allow for the setting and passing of information to virtual testers during script playback. Internal variables store information used by the TestManager to initialize and reset virtual tester parameters during script playback.


Summary

The following table lists the measurement functions.

Function Description
TSSCommandEnd() Logs an end-command event.
TSSCommandStart() Logs a start-command event.
TSSEnvironmentOp() Sets an environment variable.
TSSGetTime() Gets the elapsed time of a run.
TSSInternalVarGet() Gets the value of an internal variable.
TSSThink() Sets a think-time delay.
TSSTimerStart() Marks the start of a block of actions to be timed.
TSSTimerStop() Marks the end of a block of timed actions.


TSSCommandEnd()

Marks the end of a timed command.


Syntax

s32 TSSCommandEnd(s16 result, char *description, s32 starttime, 
s32 endtime, char *logdata, s32 propertyCount, NamedValue 
*property)

Element Description
result Specifies the notification preference regarding the result of the call. Can be one of the following:
  • TSS_LOG_RESULT_NONE (default: no notification)

  • TSS_LOG_RESULT_PASS

  • TSS_LOG_RESULT_FAIL

  • TSS_LOG_RESULT_WARN

  • TSS_LOG_RESULT_STOPPED

  • TSS_LOG_RESULT_INFO

  • TSS_LOG_RESULT_COMPLETED

  • TSS_LOG_RESULT_UNEVALUATED.

0 specifies the default.
description Contains the string to be displayed in the event of failure.
starttime An integer indicating a time stamp to override the time stamp set by TSSCommandStart(). To use the time stamp set by TSSCommandStart(), specify as 0.
endtime An integer indicating a time stamp to override the current time. To use the current time, specify as 0.
logdata Text to be logged describing the ended command.
propertyCount Specifies the number of rows in the property array.
property An array containing property name/value pairs, where property[n].name is the property name and property[n].value is its value.


Return Value

This function exits with one of the following results:


Comments

The command name and label entered with TSSCommandStart() are logged, and the run state is restored to the value that existed before the TSSCommandStart() call.

An event and any data associated with it are logged only if the specified result preference matches associated settings in the EVAR_LogData_control or EVAR_LogEvent_control environment variables. Alternatively, the logging preference can be set with the EVAR_Log_level and EVAR_Record_level environment variables. The TSS_LOG_RESULT_STOPPED, TSS_LOG_RESULT_COMPLETED, and TSS_LOG_RESULT_UNEVALUATED preferences are intended for internal use.

The NamedValue data type is defined as follows:

typedef struct {
	 	 	 char *Name;
	 	 	 char *Value;
} NamedValue;

Example

This example marks the end of the timed activity specified by the previous TSSCommandStart() call.

s32 retVal = TSSCommandEnd(TSS_LOG_RESULT_PASS,"Command timer failed", 
0, 0,"Login command completed", NULL);

See Also

TSSCommandStart(), TSSLogCommand()


TSSCommandStart()

Starts a timed command.


Syntax

s32 TSSCommandStart (char *label, char *name, RunState state)

Element Description
label The name of the timer to be started and logged, or NULL for an unlabeled timer.
name The name of the command to time.
state The run state to log with the timed command. See the run state table starting on page 92. You can enter 0 (MST_UNDEF) if you're uninterested in the run state.


Return Value

This function exits with one of the following results:


Comments

A command is a user-defined name appearing in the log of a test run. By placing TSSCommandStart() and TSSCommandEnd() calls around a block of lines in a script, you can log the time required to complete the actions in the block.

During script playback, TestManager displays progress for different virtual testers. What is displayed for a group of actions associated by TSSCommandStart() depends on the run state argument. Run states are listed in the run state table starting on page 92.

TSSCommandStart() increments IV_cmdcnt, sets the name, label, and run state for TestManager, and sets the beginning time stamp for the log entry. TSSCommandEnd() restores the TestManager run state to the run state that was in effect immediately before TSSCommandStart().


Example

This example starts timing the period associated with the string Login.

s32 retVal = TSSCommandStart("initTimer","Login",MST_WAITRESP);

See Also

TSSCommandEnd(), TSSLogCommand()


TSSEnvironmentOp()

Sets a virtual tester environment variable.


Syntax

s32 TSSEnvironmentOp(EvarKey envVar, EvarOp envOp, EvarValue 
*envVal)

Element Description
envVar The environment variable to operate on. See Arguments of TSSEnvironmentOp()for a list and description of environment variable constants.
envOp The operation to perform. See Arguments of TSSEnvironmentOp() for a list and description of the operation constants..
envVal The value operated on as specified by envOp to produce the new value for envVar.


Return Value

This function exits with one of the following results:


Comments

Environment variables define and control the environment of virtual testers. Using environment variables allows you to test different assumptions or runtime scenarios without re-writing your test scripts. For example, you can use environment variables to specify:

See Arguments of TSSEnvironmentOp() for a list and description of the values that can be used for argument envVar.

Environment control options allow a script to control a virtual tester's environment by operating on the environment variables. Every environment variable has, instead of a single value, a group of values: a default value, a saved value, and a current value.

See the table on page 280 for the values that can be used for argument envOp.

EvarOP is defined as follows:

typedef enum EvarOP EvarOP;
enum EvarOP {
	 EVOP_eval,
	 EVOP_pop,
	 EVOP_push,
	 EVOP_reset,
	 EVOP_restore,
	 EVOP_save,
	 EVOP_set,
	 EVOP_END
};

EvarKey is defined as follows:

typedef enum EvarKey EvarKey;
enum EvarKey {
	 EVAR_Think_avg = 0,
	 EVAR_Think_sd,
	 EVAR_Think_dist,
	 EVAR_Think_def,
	 EVAR_Think_max,
	 EVAR_Think_dly_scale,
	 EVAR_Think_cpu_threshold,
	 EVAR_Think_cpu_dly_scale,
	 EVAR_Initial_dly_max,
	 EVAR_Delay_dly_scale,
	 EVAR_Log_level,
	 EVAR_Record_level,
	 EVAR_Suspend_check,
	 EVAR_LogEvent_control
	 EVAR_LogData_control
	 EVAR_TSSDisable
	 EVAR_END
};

EvarValue is defined as follows:

typedef union EvarValue EvarValue;
union EvarValue {
s32     envInt;
char    *envStr;
s32     envSet;
};

where:


Example

This example gets the current value of EVAR_Think_dist. For a more extensive illustration of environment variable manipulation, see Example: Attaching to a TestManager Listener Port.

char *cur_dist;
s32 retval = TSSEnvironmentOp (EVAR_Think_dist, EVOP_eval, cur_dist);

TSSGetTime()

Gets the elapsed time since the beginning of a suite run.


Syntax

s32 TSSGetTime(void)

Return Value

On success, this function returns the number of milliseconds elapsed in a suite run. The function exits with one of the following results:


Comments

For execution within TestManager, this call retrieves the time elapsed since the start time shared by all virtual testers in all test scripts in a suite.

For a test script executed outside TestManager, the time returned is the milliseconds elapsed since the call to TSSSession.Connect(), or since the value of CTXT_timeZero set by TSSContext().


Example

This example stores the elapsed time in etime.

s32 etime = TSSGetTime();

TSSInternalVarGet()

Gets the value of an internal variable.


Syntax

s32 TSSInternalVarGet(IVKey internVar, IVValue *ivVal)

Element Description
internVar The internal variable to operate on. See Arguments of TSSInternalVarGet() for a list and description of the internal variable constants.
ivVal OUTPUT. The returned value of the specifiedinternVar.


Return Value

This function returns one of the following values:


Comments

Internal variables contain detailed information that is logged during script playback and used for performance analysis reporting. This function allows you to customize logging and reporting detail.

The data type IVKey is defined as follows:

typedef enum IVKey IVKey;
enum IVKey {
	 IV_fcs_ts,
	 IV_lcs_ts,
	 IV_fcr_ts,
	 IV_lcr_ts,
	 IV_lineno,
	 IV_cmdcnt,
	 IV_uid,
	 IV_ncxmit,
	 IV_ncrecv,
	 IV_ncnull,
	 IV_nusers,
	 IV_nkxmit,
	 IV_nrows,
	 IV_ncols,
	 IV_row,
	 IV_col,
	 IV_fs_ts,
	 IV_ls_ts,
	 IV_fr_ts,
	 IV_lr_ts,
	 IV_nxmit,
	 IV_nrecv,
	 IV_button_no,
	 IV_fuxe_ts,
	 IV_luxe_ts,
	 IV_uxe_cnt,
	 IV_ig_fs_ts,
	 IV_ig_ls_ts,
	 IV_ig_eot_ts,
	 IV_prev_ig_fs_ts,
	 IV_prev_ig_ls_ts,
	 IV_npixels_act,
	 IV_npixels_exp,
	 IV_npixels_diff,
	 IV_xwin_diff_level,
	 IV_screen,
	 IV_error,
	 IV_total_rows,
	 IV_statement_id,
	 IV_error_logs,
	 IV_cursor_id,
	 IV_fc_ts,
	 IV_lc_ts,
	 IV_total_nrecv,
	 IV_error_type,
	 IV_tux_tpurcode,
	 IV_command,
	 IV_response,
	 IV_source_file,
	 IV_task_file,
	 IV_cmd_id,
	 IV_mcommand,
	 IV_alltext,
	 IV_error_text,
	 IV_column_headers,
	 IV_total_response,
	 IV_script,
	 IV_version,
	 IV_user_group,
	 IV_host,
	 IV_refURI,
	 IV_END
};

The IVValue data type is defined as follows:

typedef union IVValue IVValue;
union IVValue {
s32     ivInt;
char    *ivStr;
};

where ivInt is used for integer internal variables and ivStr for string internal variables.


Example

This example stores the current value of the IV_error internal variable in IVVal.

s32 retVal = TSSInternalVarGet(IV_error,IVVal);

TSSThink()

Puts a time delay in a script that emulates a pause for thinking.


Syntax

s32 TSSThink(s32 thinkAverage)

Element Description
thinkAverage If specified as 0 , the number of milliseconds stored in the Think_avg environment variable is used as the basis of the calculation. Otherwise, the calculation is based on the value specified.


Return Value

This function exits with one of the following results:


Comments

A think-time delay is a pause inserted in a performance test script in order to emulate the behavior of actual application users.

For a description of environment variables, see TSSEnvironmentOp().


Example

This example calculates a pause based on the value stored in the environment variable Think_avg and inserts the pause into the script.

s32 retVal = TSSThink(0);

See Also

TSSThinkTime()


TSSTimerStart()

Marks the start of a block of actions to be timed.


Syntax

s32 TSSTimerStart(char *label, s32 timeStamp)

Element Description
label The name of the timer to be inserted into the log. If specified as NULL, an unlabeled timer is created. Only one unlabeled timer is supported at a time.
timeStamp An integer specifying a time stamp to override the current time. If specified as 0, the current time is logged.


Return Value

This function exits with one of the following results:

  • TSS_OK. Success.

  • TSS_NOSERVER. No previous successful call to TSSConnect().

  • TSS_ABORT. Pending abort resulting from a user request to stop a suite run.


Comments

This call associates a starting time stamp with label for later reference by TSSTimerStop(). The TestManager reporting system uses captured timing information for performance analysis reports.

Starting an unlabeled timer sets a start time for an event that you want to subdivide into timed intervals. See the example for TSSTimerStop(). You can get a similar result using named timers, but there will be a slight difference in the timing calculation due to the overhead of starting a timer.


Example

This example times actions designated event1, logging the current time.

TSSTimerStart("event1",0);
/* action to be timed */
TSSTimerStop("event1",0);

See Also

TSSTimerStop()


TSSTimerStop()

Marks the end of a block of timed actions.


Syntax

s32 TSSTimerStop(char *label, s32 timeStamp, u32 rmFlag)

Element Description
label The name to be logged.
timeStamp An integer indicating the time stamp to log. If specified as 0, the current time is used.
rmFlag Specify as 0to stop the timer without removing it; otherwise, specify as nonzero. A timer that is not removed can be stopped multiple times in order to measure intervals of this timed event.


Return Value

This function exits with one of the following results:

  • TSS_OK. Success.

  • TSS_NOSERVER. No previous successful call to TSSConnect().

  • TSS_INVALID. The timer label is invalid, or there is no unlabeled timer to stop.

  • TSS_ABORT. Pending abort resulting from a user request to stop a suite run.


Comments

Normally, this call associates an ending time stamp with a label specified with TSSTimerStart(). If the specifiedlabel was not set by a previous TSSTimerStart() but an unlabeled timer exists, this call logs an event using the specified label and the start time specified for the unlabeled timer with TSSTimerStart(). If rmFlag is specified as 0, multiple invocations of TSSTimerStop() are allowed against a single TSSTimerStart(). This usage (see the example) allows you to subdivide a timed event into separate timed intervals.


Example

This example stops an unlabeled timer without removing it. In the log, event1 and event2 will record the time elapsed since the TSSTimerStart() call.

TSSTimerStart(NULL,0);
/* action to be timed */
TSSTimerStop("event1",0,0);
/* another action to be timed */
TSSTimerStop("event2",0,0);

See Also

TSSTimerStart()

prevnext


Rational TestManager Extensibility Reference Rational Software Corporation
Copyright (c) 2003, Rational Software Corporation http://www.rational.com
support@rational.com
info@rational.com