Version 2.1.3
Last updated: May 4, 2005
SERVICE <Name> LIBRARY JSTAF EXECUTE <Service Jar File Name> [PARMS LOGNAME <logname>]
<Name> is the name by which the SXE service will be known on this machine.
<Service Jar File Name> is the fully-qualified name of the STAFSXE jar file.
<Logname> is an optional parameter to specify the name of the log to use when logging via the STAF LOG service. If not specified the name SXELOG will be used.
service sxe LIBRARY JSTAF EXECUTE C:/staf/services/STAFSXE.jar PARMS LOGNAME mylog
If this variable is set to 'none', no logging will be performed by the SXE service. If set to 'file' a log entry will be made when starting execution of a file and also will log a PASS or FAIL after the file completes. Note that if a file is executed in a loop, logging will occur for each iteration of the file. If this variables is set to 'command', the above file logging will occur as well as start and PASS or FAIL logging for each command executed in the file. This variable is checked at each logging attempt. Therefore, the log level may be dynamically changed, even during file execution.
This variable sets the target for elapsed time for the testcase. The format for the time is <hours:minutes:seconds.milliseconds>. This variable must be set from inside the file passed to the SXE EXECUTE command via the STAF VAR service. The call to the VAR service should not specify GLOBAL or HANDLE. WARNING: If this variable exists in the global variable pool the results of the elapsed time checking could be unpredictable. See below for a description of the elapsed time checking.
This variable sets the tolerance for the elapsed time target for the testcase. The number specified is a percentage. This variable must be set from inside the file passed to the SXE EXECUTE command via the STAF VAR service. The call to the VAR service should not specify GLOBAL or HANDLE. WARNING: If this variable exists in the global variable pool the results of the elapsed time checking could be unpredictable. See below for a description of the elapsed time checking.
If both of the variables ElapsedTarget and ElapsedTolerance are set, with valid values, from within the file passed to the SXE EXECUTE command, Elapsed Time Checking will be enabled. This indicates that after SXE has successfully completed executing all the commands in the specified file, it will check to see if the actual elapsed time is greater than the ElapsedTarget + (ElapsedTarget * ElapsedTolerance%). If it is, an ElapsedTargetExceeded return code will be returned, otherwise success will be returned.
Executes all the STAF commands specified in a file. Each file will be given a STAF handle and all commands will be executed using this STAF handle. The fully qualified filename is passed to STAF during handle registration. NOTE: Due to the workings of the current version of STAF any handle variables set in these files will remain valid during later executions of the same file. This problem should be fixed in STAF 3.0.
When SXE is given a file to execute, it will execute each command in the file sequentially. Proceeding to the next command after the previous command returns. Should a command return a non-zero return code, SXE execution will halt and the return code and result buffer from the failing command will be returned.
EXECUTE FILE <File> [LOOP <number of loops> | MINRUNTIME <hh:mm>]
File Specifies the file which contains a list of STAF commands to execute.
The file specified may contain a list of STAF commands in the following format:
<machine> <service> <request>
where <machine> is the machine to receive the STAF command, <service> is the STAF service to receive the command, and <request> is the actual request to send to the service. Blank lines in the file are ignored. If the first non white-space character of a line is '#', that line will be treated as a comment. For example to set a handle variable:
<number of loops> Specifies the number of times that the file should be executed. FOREVER may be specified to indicate an infinite loop. If this parameter is not specified, the file will be executed once.
<hh:mm> Specifies the minimum amount of time that the test should execute for. If at the end of an iteration, the entire execution time for this test is greater than or equal to the minimum runtime, the test will end. Otherwise, a new iteration of the test will begin.
NOTE: SXE will set a handle variable of {sxeloop} and it will contain the number of the current loop iteration.
NOTE: The parameters LOOP and MINRUNTIME are mutually exclusive.
Minimum security level of 3 required to do an execute.
The file should contain a series of lines each containing a single STAF command in the format:
machine request
Here is a sample file:
machineA process start command notepad wait
machineB process start command clock
machineC event generate type xyz subtype abc
All return codes from EXECUTE are documented in "SXE Error Code Reference". NOTE: If EXECUTE encountered an internal error or if the ElapsedTarget is exceeded, SXE will return one of these codes. If one of the commands being executed in the file should return a non-zero return code, SXE will return the return code from the failing command along with information about the command in the result buffer.
The result buffer will contain the number of loops and commands executed if all commands were successful. The format is: <loops>#<commands>
Where:
<loops> indicates the total number of loops executed
<commands> indicates the total commands executed per loop
If a command fails EXECUTE will return information in the following format:
<loop number>#<line number>#<command number>:[<command>]:<STAF rc>:<STAF result>
Where:
<loop number> specifies that the command failed during the nth loop through the specified file
<line number> is the absolute line number of the command in the file passed to SXE
<command number> indicates that the failing command was the nth command executed
<command> is the actual command passed to STAF
<STAF rc> is the return code from the failing STAF command
<STAF response> is the result buffer from the STAFResult of the failing command
Examples:
If the file successfully completed 5 loops and the file contained 50 STAF commands, the result buffer would contain:
5#50
If the 5th command in the file on the 10th line in the file executed on localmachine.austin.ibm.com, is: "LOCAL FS COPY FILE c:\foo\test.txt TOMACHINE testmachine" and failed due to a trust problem during the first iteration of the file, the result buffer would contain:
1#10#5:[LOCAL FS COPY FILE c:\foo\test.txt TOMACHINE testmachine]:25:localmachine.austin.ibm.com
In addition to the common STAF return codes,
the following SXE
return codes are defined:
Table 1. SXE Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4001 | File Open Error | SXE could not open the file specified. |
| 4002 | I/O Error Occurred | An I/O error occurred while reading the file. |
| 4003 | Error Registering STAFHandle for File | A STAFHandle is registered for every file submitted to the execute command. This error indicates that the STAFHandle registration failed. |
| 4004 | Elapsed Target Exceeded | The time specified by ElapsedTarget and ElapsedTolerance was exceeded when this file was executed. |
| 4005 | Error Generating Elapsed Target and/or Elapsed Tolerance values | Check the assigned values of STAF/Service/SXE/ElapsedTarget and STAF/Service/SXE/ElapsedTolerance. |