STAF eXecution Engine (SXE) Service User's Guide

Version 3.0.3

Last updated: December 1, 2009

Overview

Installation and Configuration

Variables

Request Syntax

EXECUTE

LIST

VERSION

HELP

SXE Error Code Reference

Service Logging

Overview

The STAF eXecution Engine (SXE) service is an external STAF service, written in Java, that is intended to allow the user to sequentially execute any number of STAF commands. The SXE service reads a file containing STAF commands and executes them in the order which they appear in the file.

The purpose of the SXE service is to provide a simple STAF service to execute a list of STAF commands specified in a file.

Installation and Configuration

This service requires:

STAF Version 3.0.0 or later
Java 1.2 or later

Install the SXE service by downloading the SXEV303.tar/zip file from Get STAF Services and extracting its contents to a local directory (e.g. C:\STAF\services or /usr/local/staf/services). The STAFSXE.jar file is the service jar file needed when registering the SXE service.

The SXE service is written in Java and since it is an external service, it must be registered with the SERVICE configuration statement in the STAF configuration file. The syntax is:

SERVICE <Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>
               [OPTION <Name[=Value]>]... [PARMS LOGNAME <Logname>]

where:

SERVICE specifies the name by which the SXE service will be known on this machine.

EXECUTE specifies the fully qualified name of the STAFSXE.jar file. On Windows systems, this might be C:\STAF\services\sxe\STAFSXE.jar. On Unix systems, this might be /usr/local/staf/services/sxe/STAFSXE.jar. Or, you could specify {STAF/Config/STAFRoot}/services/sxe/STAFSXE.jar which would work on any operating system.
OPTION specifes a configuration option that will be passed on to the JSTAF Java service proxy library. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See the STAF User's Guide for more information on options for the JSTAF Java service proxy library.
LOGNAME is an optional parameter that specifies the name of the service log to use when service logging is performed via the STAF LOG service. It defaults to SXELOG if not specified.

Examples

SERVICE SXE LIBRARY JSTAF EXECUTE C:/staf/services/sxe/STAFSXE.jar

SERVICE SXE LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/sxe/STAFSXE.jar \
            PARMS LOGNAME SXEServiceLog

Or, you can dynamically add the SXE service using the SERVICE service's ADD SERVICE request.

In most cases, the way that you would use this service is that you would designate a system as the SXE Server. That system would have STAF installed, plus the SXE service with the SERVICE configuration statement in the configuration file that is shown above. Assuming that the machine name for the SXE server is server1, an example of the command line interface to execute a file would be:

  STAF server1 SXE EXECUTE FILE C:/tests/sxeTest.txt

Variables

The following variables may be defined for the SXE service and will affect the behavior of the SXE service:

STAF/Service/SXE/LogLevel: Specifies the level (amount) of logging to be performed

STAF/Service/SXE/ElapsedTarget: Sets the target for elapsed time for the testcase

STAF/Service/SXE/ElapsedTolerance: Sets the tolerance for the elapsed time target for the testcase

STAF/Service/SXE/LogLevel
This variable may be set to None, File, or Command. By default, it is set to None. If this variable is set to:
- None - no logging will be performed by the SXE service.
- 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.
- 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.
Examples:
```
SET SYSTEM VAR STAF/Service/SXE/LogLevel=None
SET SYSTEM VAR STAF/Service/SXE/LogLevel=File
SET SYSTEM VAR STAF/Service/SXE/LogLevel=Command
```
STAF/Service/SXE/ElapsedTarget
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 SYSTEM, SHARED or HANDLE.
Example:
```
local VAR SET VAR STAF/Service/SXE/ElapsedTarget=0:30:0.0
```
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.
STAF/Service/SXE/ElapsedTolerance
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 SYSTEM, SHARED or HANDLE.
Example:
```
local VAR SET VAR STAF/Service/SXE/ElapsedTolerance=25
```
Warning: If this variable exists in the system or shared variable pool, the results of the elapsed time checking could be unpredictable.
See below for a description of the elapsed time checking.

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:

ElapsedTarget + (ElapsedTarget * ElapsedTolerance%)

If it is, an ElapsedTargetExceeded return code will be returned. Otherwise, RC 0 will be returned indicating success.

Request Syntax

The SXE service provides the following requests:

EXECUTE - Executes all the STAF comands specified in a file.
VERSION - Returns the version of the SXE service
HELP - Displays a list of requests for the SXE service and how to use them.

EXECUTE

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.

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 RC 4001 (Execution Error) will be returned and the result buffer from will contain additional information about the failing command.

Syntax

EXECUTE FILE <File> [LOOP <Number of loops> | MINRUNTIME <hh:mm>]

FILE specifies the fully-qualified name of a file which contains a list of STAF commands to execute.

LOOP specifies the number of times that the file should be executed. FOREVER may be specified to indicate an infinite loop. If this option is not specified, the file will be executed once.

MINRUNTIME specifies the minimum amount of time that the test should execute. It's format is hh:mm. 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.

Notes:

SXE will set a handle variable named sxeloop and it will contain the number of the current loop iteration.
The parameters LOOP and MINRUNTIME are mutually exclusive.

Security

Minimum security level of 3 required to submit an EXECUTE request.

File format

The file specified for an EXECUTE request should contain be a text file, where each line in the file should contain a single STAF command in the following format:

<Endpoint> <Service> <Request>

where:

<Endpoint> is the endpoint for the machine to receive the STAF command
<Service> is the STAF service to receive the command
<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.

Here is a sample file:

local PING    PING
local MISC    VERSION
local PROCESS START COMMAND notepad

Here is another sample file that enables elapsed time checking by setting variables STAF/Service/SXE/ElapsedTarget and STAF/Service/SXE/ElapsedTolerance within the file.

# Run TestA and TestB and do elapsed time checking

local           VAR     SET VAR STAF/Service/SXE/ElapsedTarget=0:30:0.0
local           VAR     SET VAR STAF/Service/SXE/ElapsedTolerance=20
local           FS      COPY DIRECTORY C:/tests TOMACHINE client1.ibm.com
client1.ibm.com PROCESS START COMMAND C:/tests/testA.exe WAIT
client1.ibm.com FS      COPY FILE C:/tests/testA.res TOFILE C:/results/testA.res
client1.ibm.com PROCESS START COMMAND C:/tests/testB.exe WAIT
client1.ibm.com FS      COPY FILE C:/tests/testB.res TOFILE C:/results/testB.res
client3.ibm.com EVENT   GENERATE TYPE myTests SUBTYPE complete

Return Codes

All return codes from EXECUTE are documented in "SXE Error Code Reference".

Results

Upon successful return, the result buffer will contain a marshalled <Map:STAF/Service/SXE/ExecutionResults> representing the execution results. The map is defined as follows:

Definition of map class STAF/Service/SXE/ExecutionResults

Description: This map class represents the execution results.

Key Name Display Name Type Format / Value

loops Loops Executed <String>
commands Commands Per Loop <String>

Notes:

The "Loops Executed" value is set to the total number of loops executed.
The "Commands Per Loop" value is set to the total number of commands executed per loop.

Definition of map class STAF/Service/SXE/ExecutionResults
loops	Loops Executed	`<String>`
commands	Commands Per Loop	`<String>`
Notes: The "Loops Executed" value is set to the total number of loops executed. The "Commands Per Loop" value is set to the total number of commands executed per loop.

If unsuccessful, a non-zero RC will be returned and the result buffer will contain a marshalled <Map:STAF/Service/SXE/ErrorInfo> representing more information about the error. The map is defined as follows:

Definition of map class STAF/Service/SXE/ErrorInfo

Description: This map class represents error information.

Key Name Display Name Type Format / Value

loopNum Loop Number <String>
lineNum Line Number <String> | <None>
commandNum Command Number <String> | <None>
command Command <String> | <None>
rc RC <String>
result Result <String>

Notes:

The "Loop Number" value is set to the loop number during which a command in the file failed, or <None> if not applicable.
The "Line Number" value is set to the absolute line number of the command in the file passed to SXE that failed, or <None> if not applicable.
The "Command Number" value is set to the number of the command that failed, or <None> if not applicable.
The "Command" value is set to the actual command that failed, or <None> if not applicable.
The "RC" value is set to the return code of the failing STAF command.
The "Result" value is set to the result buffer of the failing STAF command.

Definition of map class STAF/Service/SXE/ErrorInfo
loopNum	Loop Number	`<String>`
lineNum	Line Number	`<String> \| <None>`
commandNum	Command Number	`<String> \| <None>`
command	Command	`<String> \| <None>`
rc	RC	`<String>`
result	Result	`<String>`
Notes: The "Loop Number" value is set to the loop number during which a command in the file failed, or <None> if not applicable. The "Line Number" value is set to the absolute line number of the command in the file passed to SXE that failed, or <None> if not applicable. The "Command Number" value is set to the number of the command that failed, or <None> if not applicable. The "Command" value is set to the actual command that failed, or <None> if not applicable. The "RC" value is set to the return code of the failing STAF command. The "Result" value is set to the result buffer of the failing STAF command.

Examples:

Goal: Execute a SXE file named C:\tests\myTest.txt that contains 3 STAF commands once.
EXECUTE FILE C:\tests\myTests.txt
Output: If the request is submitted from the command line and the commands in the file are executed successful, the result, in default format, could look like:
```
Loops Executed   : 1
Commands Per Loop: 3
```
Goal: Execute a SXE file named C:\tests\webTest.txt that contains 50 STAF commands and execute it 5 times.
EXECUTE FILE C:\tests\webTest.txt LOOP 5
Output: If the request is submitted from the command line and the commands in the file are executed successful, the RC would be 0 and the result buffer would look like:
```
Loops Executed   : 5
Commands Per Loop: 50
```
Or, if during the 1st loop running the file, the 5th command in the file on the 10th line in the file executed failed and the 5th command is "local FS COPY FILE c:\foo\test.txt TOMACHINE testmachine" and it failed due to file c:\foo\test.txt not existing, the RC would be 4001 (Execution Error) and the result buffer would contain:
```
Loop Number   : 1
Line Number   : 10
Command Number: 5
Command       : LOCAL FS COPY FILE c:\foo\test.txt TOMACHINE testmachine
RC            : 48
Result        : c:\foo\test.txt
```
Goal: Execute a SXE file named C:\tests\stressTest.txt and continue executing it for at least 4 hours.
EXECUTE FILE C:\tests\webTest.txt MINRUNTIME 4:00
Output: If the request is submitted from the command line and the commands in the file are executed successful, the result, in default format, could look like the following if the test contained 25 commands and ran 15 times:
```
Loops Executed   : 15
Commands Per Loop: 25
```

LIST

LIST allows you to list the current operational settings for the SXE service.

Syntax

LIST SETTINGS

Security

This request requires at least trust level 2.

Results

The result buffer for a LIST SETTINGS request will contain a marshalled <Map:STAF/Service/SXE/Settings> representing the operational settings for the SXE service. The map is defined as follows:

Definition of map class STAF/Service/SXE/Settings

Description: This map class represents the settings for the SXE service.

Key Name Display Name Type Format / Value

logName Log Name <String>

Notes:

The "Log Name" value is the name of the STAF log where the SXE service logs information. It's value can be overridden via the LOGONAME parameter when registering the SXE service.

Definition of map class STAF/Service/SXE/Settings
logName	Log Name	`<String>`
Notes: The "Log Name" value is the name of the STAF log where the SXE service logs information. It's value can be overridden via the `LOGONAME` parameter when registering the SXE service.

Examples

Goal: List the settings for the email service on machine server1.company.com:
STAF server1.company.com SXE LIST SETTINGS
Output: If the request is submitted from the command line, the result could look like:
```
Log Name: SXELOG
```

VERSION

VERSION displays the SXE Service version.

Syntax

VERSION

Security

This request requires at least trust level 1.

Results

The result is the version number of the SXE service.

Examples

Goal: Display the version of the SXE service on machine server1.company.com:
STAF server1.company.com SXE VERSION
Output:
```
3.0.3
```

HELP

HELP displays the request options and how to use them.

Syntax

HELP

Security

This request requires at least trust level 1.

Results

The result buffer contains the Help messages for the request options for the SXE service.

Examples

Goal: Display the syntax for the SXE service requests:

STAF local SXE HELP

Output:

SXE STAF Service

EXECUTE FILE  [LOOP  | MINRUNTIME ]
LIST    SETTINGS
VERSION
HELP

SXE Error Code Reference

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 Execution Error An error occurred during execution of the file.

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.

Error Code	Meaning	Comment
4001	Execution Error	An error occurred during execution of the file.
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.

Service Logging

If you have turned on service logging, the SXE service maintains a machine log as follows:

If variable STAF/Service/SXE/LogLevel is set to File:
- A "Start" entry is logged when starting execution of a file
- A "Stop" entry is logged when stopping execution of a file
- A "Pass" or "Fail" entry is logged after the file completes with pass or fail information recorded.
Note that if a file is executed in a loop, logging will occur for each iteration of the file.
If variable STAF/Service/SXE/LogLevel is set to Command:
- The above file logging will occur
- An "Info" entry is logged at the beginning of each command executed in the file.
- After each command has been executed, if the command completed successfully with RC 0, an "Info" entry is logged containing any result returned by the command. Otherwise, if the command failed, an "Error" entry is logged containing more information about the error.

If variable STAF/Service/SXE/LogLevel does not exist or is set to None, no logging will be performed by the SXE service. This variable is checked at each logging attempt. Therefore, the log level may be dynamically changed, even during file execution.

The logname for the SXE service is SXELOG unless overridden using the LOGNAME parameter when registering the service.

Here is an example of what a SXE service log on machine server1.austin.ibm.com could look like if STAF/Service/SXE/LogLevel is set to File (shown via a request from the command line in the verbose format):

C:\>STAF server1 LOG QUERY MACHINE server1.austin.ibm.com LOGNAME SXELOG
Response
--------
[
  {
    Date-Time: 20050128-14:08:31
    Level    : Start
    Message  : {
      Loop Number: 1
      Time       : 14:8:31.444
    }
  }
  {
    Date-Time: 20050128-14:08:32
    Level    : Stop
    Message  : {
      Loop Number: 1
      Time       : 14:8:32.515
    }
  }
  {
    Date-Time: 20050128-14:08:32
    Level    : Pass
    Message  : {
      Loop Number              : 1
      Elapsed Time             : 0:0:1.071
      Elapsed Target           :
      Elapsed Tolerance Percent: 0
    }
  }
]

Here is an example of what a SXE service log on machine server1.austin.ibm.com could look like if STAF/Service/SXE/LogLevel is set to Command (shown via a request from the command line in the verbose format):

C:\>STAF server1 LOG QUERY MACHINE server1.austin.ibm.com LOGNAME SXELOG
Response
--------
[
  {
    Date-Time: 20050128-14:10:47
    Level    : Start
    Message  : {
      Loop Number: 1
      Time       : 14:10:47.399
    }
  }
  {
    Date-Time: 20050128-14:10:47
    Level    : Info
    Message  : {
      Action : Begin
      Command: client1 ping ping
      Result : 
    }
  }
  {
    Date-Time: 20050128-14:10:47
    Level    : Info
    Message  : {
      Action : End
      Command: client1 ping ping
      Result : PONG
    }
  }
  {
    Date-Time: 20050128-14:10:47
    Level    : Info
    Message  : {
      Action : Begin
      Command: local delay delay 1000
      Result : 
    }
  }
  {
    Date-Time: 20050128-14:10:48
    Level    : Info
    Message  : {
      Action : End
      Command: local delay delay 1000
      Result :
    }
  }
  {
    Date-Time: 20050128-14:10:48
    Level    : Stop
    Message  : {
      Loop Number: 1
      Time       : 14:10:48.521
    }
  }
  {
    Date-Time: 20050128-14:10:48
    Level    : Pass
    Message  : {
      Loop Number              : 1
      Elapsed Time             : 0:0:1.122
      Elapsed Target           :
      Elapsed Tolerance Percent: 0
    }
  }
]

Definition of map class STAF/Service/SXE/ExecutionResults
Description: This map class represents the execution results.
Key Name	Display Name	Type	Format / Value
loops	Loops Executed	`<String>`
commands	Commands Per Loop	`<String>`
Notes: The "Loops Executed" value is set to the total number of loops executed. The "Commands Per Loop" value is set to the total number of commands executed per loop.