STAX Function Definitions

STAF

Submits a request to STAF. It's a shortcut for the <stafcmd> element.

This function takes a list of arguments
Name	Description	Required	Default
location	The name of the machine of which you wish to make a request	Yes	N/A
service	The name of the STAF service to which you are submitting a request	Yes	N/A
request	The actual request string that you wish to submit to the STAF service	Yes	N/A

Returns:

The STAF request's RC and STAFResult in a list.

Examples:

1. Here's a simple example that calls the STAF function with a request to obtain the version of STAF that's currently running on the local system:

     <call function="STAF">['local', 'MISC', 'VERSION']</call>

   If successful, STAXResult could look like:

     [0, '2.4.2']

   If not successful because the machine isn't available, STAXResult could look like:

     [ 16, 'getInAddrByName: 11001' ]

2. Here's another example that calls the STAF function with a request to resolve a STAF variable on a machine. This example shows how you can save STAXResult into two variables (e.g. rc and result) immediately following the function call, instead of referencing STAXResult[0] and STAXResult[1]. This example also uses the STAXUtilCheckSuccess function to check if the STAF request was successful and to log a pass or fail message and send it to the STAX Monitor.

     <call function="STAF">[machName, 'VAR', 'RESOLVE {STAF/Version}']</call>
   
     <script>[rc, result] = STAXResult</script>
     
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'Failed with RC=%s STAFResult=%s' % (rc, result),
         'passMsg': 'STAF Version on %s is %s' % (machName, result),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

STAFProcess

Submits a STAF request to start a process in a separate shell (using the default shell command). It's a shortcut for the <process> element when you only need to specify the command to be started in a separate shell.

This function takes a list of arguments
Name	Description	Required	Default
location	The name of the machine of which you wish to make a request	Yes	N/A
command	The name of the command you want to start in a separate shell	Yes	N/A

Returns:

Returns the process's RC and STAFResult in a list.

If the process ran successfully and returns a 0 to indicate this, STAXResult would look like:

  [0, '']

  [ 16, 'getInAddrByName: 11001' ]

Examples:

1. Here's a simple example that calls the STAFProcess function to run shell script '/tests/test1.sh' on machine 'machA'.

     <call function="'STAFProcess'">['machA', '/tests/test1.sh']</call>

2. Here's another example that calls the STAFProcess function to run a complex shell command on a machine. This example shows how you can save STAXResult into two variables (e.g. rc and result) immediately following the function call, instead of referencing STAXResult[0] and STAXResult[1]. This example also uses the STAXUtilCheckSuccess function to check if the STAF process request was successful and to log a pass or fail message and send it to the STAX Monitor.

     <call function="'STAFProcess'">
       [ machName,
         'cd %s; tar cvfp - %s | (cd %s; tar xvfp -)' % (Source,tarFile,Target) ] 
     </call>
   
     <script>[rc, result] = STAXResult</script>
     
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'Failed with RC=%s STAFResult=%s' % (rc, result),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

STAFProcessUsing

Submits a STAF request to start a process using a map to define values for the process element's sub-elements. It's a shortcut for the <process> element when additional options need to be specified.

This function takes an argument map
Name	Description	Required	Default
location	The name of the machine of which you wish to make a request. It corresponds to the location element.	Yes	N/A
command	The name of the command you want to start in a separate shell. It corresponds to the command element.	Yes	N/A
commandmode	Specifies whether to execute the command via a separate shell or not. It must evaluate to 'shell' or 'default'. It corresponds to the command element's mode attribute.	No	'default'
commandshell	The shell to use when starting the command via a separate shell. It overrides the default shell. It is only used if command mode is set to 'shell'. It corresponds to the command element's shell attribute.	No	''
name	The name that the STAX Monitor uses to refer to the process element. If not specified it defaults to Process<number>, where <number> is a unique number for each process executed in a job. It corresponds to the name attribute for the process element.	No	None
parms	Parameters to pass to the command (shortcut for parms element)	No	None
workdir	The directory from which the command should be executed. If you do not specify this element, the command will be started from whatever directory STAFProc is currently in. It corresponds to the workdir element.	No	None
title	Program Title for the process. If not specified, the title will be the text that is displayed on the title bar of the application. It corresponds to the title element.	No	None
workload	Name of the workload for which this process is a member. It corresponds to the workload element.	No	None
vars	STAF Variables that go into the process-specific STAF variable pool. The format for each variable is: 'varname=value'. So, a list containing three variables could look like: ['var1=value1', 'var2=value2', 'var3=value3'] Specifying only one variable could look like either: ['var1=value1'] or 'var1=value1' It corresponds to the vars element.	No	None
envs	Environment variables that will be set for the process. Environment variable names may be mixed case, however, most programs assume environment variable names will be uppercase, so, in most cases, ensure that your environment variable names are uppercase. The format for each variable is: 'varname=value'. So, a list containing three variables could look like: ['ENV_VAR1=value1', 'ENV_VAR2=value2', 'ENV_VAR3=value3'] Specifying only one variable could look like either: ['ENV_VAR1=value1'] or 'ENV_VAR1=value1' It corresponds to the envs element.	No	None
useprocessvars	Specifies that STAF variable references should try to be resolved from the STAF variable pool associated with the process being started first. If the STAF variable is not found in this pool, the STAF global variable pool should then be searched. Specify any nonzero number or nonempty object (e.g. 1, 'yes'). It corresponds to the useprocessvars element.	No	None
stopusing	Specifies the method by which this process will be STOPed, if not overridden on the STOP command. It corresponds to the stopusing element.	No	None
console	Specifies if the process should get a new console window or share the STAFProc console. The value specified must evaluate via Python to 'new' or 'same'. This determines whether the the process should get a new console window (which is the default for Win32 systems) or if the process should share the STAFProc console (which is the default for Unix systems). It corresponds to the console element.	No	None
username	The user name under which the process should be started. It corresponds to the username element.	No	None
password	The password with which to authenticate the user specified with the username element. It corresponds to the password element.	No	None
disabledauth	Specifies the action to take if a username/password is specified but authentication has been disabled. The value specified must evaluate via Python to a string containing either 'error' or 'ignore'. Specifying 'error' says that an error should be returned. Specifying 'ignore' says that any username/password specified is ignored if authentication is disabled. This action overrides any default specified in the STAF cfg file. It corresponds to the disabledauth element.	No	None
stdin	The name of the file from which standard input will be read. It corresponds to the stdin element.	No	None
stdout	The name of the file to which standard output will be redirected. It corresponds to the stdout element.	No	None
stdoutmode	Specifies what to do if the file specified for stdout already exists. The value must evaluate via Python to 'replace' or 'append'. Specifying 'replace' means that the file will be replaced (the default). Specifying 'append' means that the process' standard output will be appended to the file. It corresponds to the stdout element's mode attribute.	No	'replace'
stderr	The name of the file to which standard error will be redirected. It corresponds to the stderr element.	No	None
stderrmode	Specifies what to do if the file specified for stderr already exists. The value must evaluate via Python to 'replace', 'append', or 'stdout'. Specifying 'replace' means the file will be replaced (the default). Specifying 'append' means the process' standard error will be appended to the file. Specifying 'stdout' means to write standard error to the stdout file. It corresponds to the stderr element's mode attribute.	No	'replace'
returnstdout	Specifies to return in STAXResult the contents of the file where standard output was redirected when the process completes. Specify any nonzero number or nonempty object (e.g. 1, 'yes'). It corresponds to the returnstdout element.	No	None
returnstderr	Specifies to return in STAXResult the contents of the file where standard error was redirected when the process completes. Specify any nonzero number or nonempty object (e.g. 1, 'yes'). It corresponds to the returnstderr element.	No	None
returnfiles	Specifies to return in STAXResult the contents of the specified file(s) when the process completes. The value must evaluate via Python to a string (containing a file name) or a list of strings (each containing a file name). It corresponds to the returnfiles element.	No	None
statichandlename	Specifies that a static handle should be created for this process. The value specified will be the registered name of the static handle. Using this option will also cause the environment variable STAF_STATIC_HANDLE to be set appropriately for the process. It corresponds to the statichandlename element.	No	None
other	Specifies any other STAF parameters that may arise in the future. Used to pass additional data to the STAF PROCESS START request. The value is evaluated via Python to a string. It corresponds to the other element.	No	None
processActionFunction	Specifies the name of a function to be called when a process has started. It corresponds to the process-action element, by letting you call a function as the task in the process-action element.	No	None
processActionParms	Specifies the parameters to pass to processActionFunction. It is only used if processActionFunction is specified.	No	None

Returns:

Returns the process's RC, STAFResult, and STAXResult in a list.

For example, if the process's RC=0, and it's STAFResult=None, and it's STAXResult=[[0, 'This is data written to stdout\n'], [0, 'No errors\n']], then the STAXResult set after calling this function is:

[0, None, [[0, 'This is data written to stdout\n'], [0, 'No errors\n']]]

[ 16, 'getInAddrByName: 11001', None ]

Examples:

1. This example calls function STAFProcessUsing passing a map of options for starting a process.

     <call function="'STAFProcessUsing'">
       {'location': machine, 'command': command, 'commandmode': 'shell',
        'stdout': stdoutfile, 'stderr': 'stdout' }
     </call>
   
     <script>[rc, result, returnedFileData] = STAXResult</script>

2. This example programatically builds up the options to use for starting a process in a map (dictionary) to be passed to this function. Then it saves the function's STAXResult into three variables (e.g. rc, result, and returnedFileData) immediately following the function call, instead of referencing them as STAXResult[0], STAXResult[1], and STAXResult[2]. This example also uses the STAXUtilCheckSuccess function to check if the STAF process request was successful and if it fails, to log a failure message.

     <script>
       processMap = {'location': 'machineA', 'command': '/tests/test1.sh',
                     'commandmode': 'shell'}
       if returnOutput:
         processMap['stdout'] = '/tests/test1.out'
         processMap['stderr'] = 'stdout'
         processMap['returnstdout'] = 1
     </script>                                                         
   
     <call function="'STAFProcessUsing'">processMap</call>
     
     <script>[rc, result, returnedFileData] = STAXResult</script>
     
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'Failed with RC=%s STAFResult=%s STAXResult=%s' %
                    (rc, result, returnedFileData) }
     </call>

STAXUtilLogAndMsg

Logs a message and sends the message to the STAX Monitor. It's a shortcut for specifying the <message> and <log> elements for the same message.

This function takes a list of arguments
Name	Description	Required	Default
message	The message you want to log in the STAX Job User log and to send to the STAX Monitor.	Yes	N/A
level	The level of the message to be logged in the STAX Job User log.	No	'info'

Returns:

Nothing. That is, STAXResult = None.

Example:

  <call function="'STAXUtilLogAndMsg'">'Here is my message'</call>

STAXUtilWaitForSTAF

Waits for STAF to become available (that is, for the STAFProc daemon to be running) on one or more machines. A maximum wait time can be specified, overriding the default maximum wait time of 5 minutes. If one or more machines are not available, and the maximum wait time has not been exceeded, delays 5 seconds and then retries. This function can be useful after rebooting one or more systems.

This function takes a list of arguments
Name	Description	Required	Default
machineList	A single machine or a list of machines for which you want to wait for STAF to become available	Yes	N/A
maxWaitTime	The maximum length of time in seconds you want to wait for STAF to become available on the specified machine(s). The default is 5 minutes (300 seconds).	No	300

Returns:

A list containing a return code and result.

If the machine(s) all have STAF available within the maximum wait time, returns a return code of 0 and None for the result. That is, STAXResult would be:

  [0, None]

If the maximum wait time is exceeded, returns a return code of 1 and a list of machines that are not available. For example, if machines 'machA' and 'machB' were not available, STAXResult would be:

  [1, ['machA', 'machB']]

If an invalid (non-integer) maxWaitTime value is specified, returns a return code of -1 and None for the result. That is, STAXResult would be:

  [-1, None]

Examples:

1. Here's an example that waits for STAF to become available on machA for the default time of 5 minutes:

     <call function="'STAXUtilWaitForSTAF'">'machA'</call>

2. Here's an example that waits for STAF to become available on three systems for a maximum of 60 seconds. If STAF is not available on all three systems within 60 seconds, a failure message is logged and sent to the STAX Monitor.

     <script>machList = [ 'machA', 'machB', 'machC' ]</script>
   
     <call function="'STAXUtilWaitForSTAF'">[ machList, 60 ]</call>
   
     <script>[rc, result] = STAXResult</script>
   
     <if expr="rc != 0">
       <call function="'STAXUtilLogAndMsg'">
         'STAXUtilWaitForSTAF failed. RC=%s Result=%s' % (rc, result)
       </call>
     </if>

STAXUtilCopyFiles

Copies files from a directory on a machine to a directory on the same or different machine. You can specify which files to copy from a directory using the name pattern, extension pattern, case sensitivity, and/or regular expression arguments.

The regular expression allows you to define complicated pattern matching rules to determine which files to copy.

Note that this function only copies files; no subdirectories will be copied.

For performance reasons, the files are copied in groups of up to 5 in parallel. If the toDirectory does not exist, it will be created. If any of the files being copied already exist on the toMachine, they will be replaced.

This function takes an argument map
Name	Description	Required	Default
machine	Name of the machine from which files are to be copied	Yes	N/A
directory	Name of the directory from which files are to be copied	Yes	N/A
toDirectory	Name of the directory to which files will be copied on the toMachine	Yes	N/A
toMachine	Name of the machine to which files are to be copied	Yes	N/A
name	A pattern used to match the name of child entries. Child entries whose name match this pattern will be copied. Note: This pattern recognizes two special characters, '*' and '?', where '*' matches any string of characters (including an empty string) and '?' matches any single character (the empty string does not match).	No	'*'
ext	A pattern used to match the extension of child entries. Child entries whose extension match this pattern will be copied. Note: This pattern recognizes two special characters, '*' and '?', where '*' matches any string of characters (including an empty string) and '?' matches any single character (the empty string does not match).	No	'*'
regularExpression	A regular expression uses to match the child entries. Child entries which match the regular expression will be copied. Regular expressions are strings that let you define complicated pattern matching. For example, '[ab].*|.out' specifies to copy all files whose names begin with a or b OR whose extensions end in out.	No	None
caseSensitive	Specifies the case sensitivity for the patterns specified by name and ext. 0 specifies that the patterns specified by name and ext are to be matched in a case insensitive manner. 1 specifies that the patterns specified by name and ext are to be matched in a case sensitive manager. The default is None which specifies that case sensitivity is determined by the operating system, where unix systems default to 1 (case sensitive) and all others default to 0 (case insensitive).	No	None

Returns:

Returns a list containing: a return code, the number of files copied, and an error list. The return code will be set to one of the following values:

• 0 - if all files were copied successfully
• 1 - if one or more files could not be copied
• 2 - if the toDirectory could not be created
• 3 - if the fromDirectory could not be listed

If the return code is zero, the error list is set to None.

If the return code is not zero, the error list will contain a list of errors that occurred while trying to copy the files. Each entry in the error list will be a sub-list that consists of the following:

• Name of the file that couldn't be copied (or the name of the directory that couldn't be listed or created),
• RC from the STAF request that failed,
• Result from the STAF request that failed.

For example, if all files were copied successfully and there were 25 files to copy, STAXResult would look like:

[0, 25, None]

If file /test/test14.out could not be opened, but 24 files were copied, STAXResult could look like:

[ 1, 24, [['/test/test14.out', 17, '/test/test14.out']] ]

Examples:

1. Copy files from directory /test on machine machA to directory /test/summary on machine machB, only copying files whose names begin with 'test' and whose extension is 'out'.

     <call function="'STAXUtilCopyFiles'">
       { 'machine': 'machA', 'directory': '/test', 
         'toMachine': 'machB', 'toDirectory': '/test/summary',
         'name': 'test*', 'ext': 'out' }
     </call>

2. Copy files from directory C:/test/test1 on machine machA to directory C:/test/test1 on machine machB, only copying files whose names begin with 'a' or 'b' OR whose extensions are 'out'.

   Also saves the function's STAXResult into three variables (e.g. rc, numFilesCopied, and errorList) immediately following the function call, instead of referencing them as STAXResult[0], STAXResult[1], and STAXResult[2]. Uses the STAXUtilCheckSuccess function to check if all the files were copied successfully. If not, logs a failure message and sends it to the STAX Monitor.

     <call function="'STAXUtilCopyFiles'">
       { 'machine': 'machA', 'directory': 'C:/test/test1',
         'toMachine': 'machB', 'toDirectory': '/test1/summary',
         'regularExpression': '[ab].*|.out' }
     </call>
     
     <script>[rc, numFilesCopied, errorList] = STAXResult</script>
     
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'CopyFiles failed. RC: %s. Files copied: %s Error List: %s' %
                    (rc, numFilesCopied, errorList),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

STAXUtilListDirectory

Lists files in a directory on a machine. You can specify which files to list using the name pattern, extension pattern, case sensitivity, and/or regular expression arguments.

The regular expression allows you to define complicated pattern matching rules to determine which files to copy.

This function takes an argument map
Name	Description	Required	Default
machine	Name of the machine on which to list the directory contents	Yes	N/A
directory	Name of the directory whose contents are to to be listed	Yes	N/A
name	A pattern used to match the name of child entries. Only child entries whose name match this pattern will be copied. Note: The name and extension match patterns recognize two special characters, '*' and '?', where '*' matches any string of characters (including an empty string) and '?' matches any single character (the empty string does not match).	No	'*'
ext	A pattern used to match the extension of child entries. Only child entries whose extension match this pattern will be copied. Note: The name and extension match patterns recognize two special characters, '*' and '?', where '*' matches any string of characters (including an empty string) and '?' matches any single character (the empty string does not match).	No	'*'
caseSensitive	Specifies the case sensitivity for the patterns specified by name and ext. 0 specifies that the patterns specified by name and ext are to be matched in a case insensitive manner. 1 specifies that the patterns specified by name and ext are to be matched in a case sensitive manager. The default is None which specifies that case sensitivity is determined by the operating system, where unix systems default to 1 (case sensitive) and all others default to 0 (case insensitive).	No	None
regularExpression	A regular expression uses to match the child entries. Child entries which match the regular expression will be copied. Regular expressions are strings that let you define complicated pattern matching. For example, '[ab].*|.out' specifies to list all files whose names begin with a or b OR whose extensions end in out.	No	None

Returns:

Returns the RC from the FS LIST DIRECTORY request and the result.

If the RC is 0, the files in the directory were successfully listed and the result contains a Python list of the files.

If the RC is not 0, the FS LIST DIRECTORY request failed and the result contains the STAFResult from the request which may contain more information on why it failed.

Examples:

1. List the files in directory /tests on machA with an extension of out:

     <call function="'STAXUtilListDirectory'">
       { 'machine': 'machA', 'directory': '/tests', 'ext': 'out' }
     </call>

   If successful, STAXResult could be:

     [ 0, ['test1.out', 'test2.out', 'test3.out'] ]

   If not successful because directory /tests does not exist on machine machA, STAXResult would be:

     [48, 'FS LIST DIRECTORY /tests failed on machA. Result=/tests']

2. List the files in directory C:\test\test1 on machine machA whose names begin with 'a' or 'b' OR whose extensions are 'out'.

   Also saves the function's STAXResult into two variables (e.g. rc, result) immediately following the function call, instead of referencing them as STAXResult[0] and STAXResult[1]. Uses the STAXUtilCheckSuccess function to check if all the files were listed successfully. If not, logs a failure message and sends it to the STAX Monitor.

     <call function="'STAXUtilListDirectory'">
       { 'machine': 'machA', 'directory': 'C:/test/test1',
         'regularExpression': '[ab].*|.out' }
     </call>
     
     <script>[rc, result] = STAXResult</script>
     
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'List directory failed. RC=%s Result=%s' % (rc, result),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

STAXUtilCheckSuccess

Checks if a result indicates success or failure. If the result evaluates to a true value:

1. If a pass message is provided, it is logged in the STAX User Log and, optionally, sent to the STAX Monitor.
2. A testcase status of pass is recorded if the recordStatus evaluates to a true expression.

Otherwise, if the result evaluates to a false value:

1. If a failure message is provided, it is logged in the STAX User Log and, optionally, sent to the STAX Monitor.
2. A testcase status of fail is recorded if the recordStatus evaluates to a true expression.

This function takes an argument map
Name	Description	Required	Default
result	Specifies an expression or value to be evaluated. Success is indicated if it evaluates to a true value; Failure is indicated if it evaluates to a false value.	Yes	N/A
failMsg	A failure message to be logged if the result evaluates to treu	No	None
passMsg	A pass message to be logged if the result evaluates to true	No	None
sendToMonitor	Indicates whether to send the pass and/or failure message (if provided) to the STAX Monitor	No	None
recordStatus	Indicates whether to record a pass or fail for testcase status	No	None

Returns:

If the result evaluates to a true value, 0 is returned.
If the result evaluates to a false value, 1 is returned.

Examples:

1. Here's an example that says if RC is 0 or 48, then it's successful. Otherwise, it fails and logs a failure message.

     <call function="'STAXUtilCheckSuccess'">
       { 'result': RC in [0, 48],
         'failMsg': 'Failed with RC=%s STAFResult=%s' % (RC, STAFResult) }
     </call>

2. Here's an example that says if RC is 0, then it's successful and it logs the pass message and sends it to the STAX Monitor, and records a testcase pass status. Otherwise, it fails and it logs the failure message and sends it to the STAX Monitor and records a testcase fail status.

     <call function="'STAXUtilCheckSuccess'">
       { 'result': RC == 0,
         'failMsg': 'ProcessA failed with RC=%s' % RC,
         'passMsg': 'ProcessA was successful',
         'sendToMonitor': 1,
         'recordStatus': 1 }
     </call>

STAXUtilImportSTAFVars

Imports STAF variables on the specified machines, creating STAX variables from them.

If only one machine is specified, for each STAF variable name that is specified, a STAX variable with the specified name is created with the resolved contents of the STAF variable for the specified machine assigned to it.

If a list of machines is specified, for each STAF variable name that is specified, a STAX map is created with the specified name which contains an entry for each machine (key) with a value of the resolved contents of the STAF variable for that machine assigned.

This function's scope must be global, not local, in order to set the STAX variables so that they are accessible by the function caller. Note that any variables that are used directly in a STAXUtil "global" function are prefixed with STAXUtil to avoid name collisions.

This function takes a list of arguments
Name	Description	Required	Default
STAXUtilVarMap	A map containing STAF variable names to be converted to STAX variables. The key is the name of the STAF variable to convert and its value is the name of the STAX variable to create.	Yes	N/A
STAXUtilMachList	List of the machine(s) where the STAF variables to be converted reside.	Yes	N/A

Returns:

A list consisting of:

• Return code - 0 if all STAF variables were successfully converted to STAX variables or 1 if one or more errors occurred during the conversion.
• Error list - A list of the STAF variables which could not be converted (or None if all STAF variables were successfully converted). The list is actually a list of lists where each sublist contains the name of the STAF variable that could not be converted, the machine, the RC, and the STAFResult.

Examples:

1. Import two STAF variables on machine 'machA', creating STAX variables named mySTAFDir and mySTAFVersion. This example also shows how you can save STAXResult into two variables (e.g. rc and errorList) immediately following the function call, instead of referencing STAXResult[0] and STAXResult[1], and then check if all the STAF variables were successfully converted.

     <call function="'STAXUtilImportSTAFVars'">
       [
         {'STAF/Env/STAFDir': 'mySTAFDir', 'STAF/Version': 'mySTAFVersion'},
         'machA'    
       ]
     </call>
     
     <script>[rc, errorList] = STAXResult</script>
   
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'STAXUtilImportSTAFVars failed.  RC=%s ErrorList=%s' % \
                    (rc, errorList),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

   If successful, STAXResult would be:

     [0, None]

   and the resulting STAX variables could be:
   • mySTAFDir = 'C:\STAF'
   • mySTAFVersion = '2.4.2'

   If not successful because STAF variable STAF/Version does not exist: STAXResult would be:

     [ 1, [ ['STAF/Version', 'machA', 13, 'STAF/Version'] ] ]

2. Import two STAF variables on machines 'machA' and 'machB', creating STAX variables named mySTAFDir and mySTAFDir, where each is a map containing two entries, one for 'machA' and another for 'machB'.

     <call function="'STAXUtilImportSTAFVars'">
       [
         {'STAF/Env/STAFDir': 'mySTAFDir', 'STAF/Version': 'mySTAFVersion'},
         ['machA', 'machB']
       ]  
     </call>

   If successful, STAXResult would be:

     [0, None]

   and the resulting STAX variables could be:
   • mySTAFDir = { 'machA': 'C:\STAF', 'machB': '/usr/local/staf' }
   • mySTAFVersion = { 'machA': '2.4.2', 'machB': '2.4.2.2' }

   These STAX variables could be accessed as follows:

     mySTAFDir['machA']
     mySTAFDir['machB']
     mySTAFVersion['machA']
     mySTAFVersion['machB']

   If not successful because STAF variable STAF/Env/STAFDir does not exist and machine machineB does not exist, STAXResult would be:

     [ 1,
       [ ['STAF/Env/STAFDir', 'machA', 13, 'STAF/Env/STAFDir'],
         ['STAF/Env/STAFDir', 'machB', 13, 'STAF/Env/STAFDir'],
         ['STAF/Env/STAFDir', 'machB', 16, 'getInAddrByName: 11001'],
         ['STAF/Version', 'machB', 16, 'getInAddrByName: 11001']
     ] ]

STAXUtilImportSTAFConfigVars

Imports STAF Configuration variables on the specified machine, creating a STAX variable map containing their values. The following is a list of the names of the keys in the STAX variable map returned and the STAF Config variables whose values are contained in each key::

• 'OSMajorVersion': STAF/Config/OS/MajorVersion
• 'OSMinorVersion': STAF/Config/OS/MinorVersion
• 'OSName': STAF/Config/OS/Name
• 'OSRevision': STAF/Config/OS/Revision
• 'FileSep': STAF/Config/Sep/File
• 'LineSep': STAF/Config/Sep/Line
• 'PathSep': STAF/Config/Sep/Path

This function takes a list of arguments
Name	Description	Required	Default
machName	Machine from which to resolve STAF variables	Yes	N/A

Returns:

A list consisting of:

• Return code - 0 if all STAF Config variables were successfully converted to STAX variables or 1 if one or more errors occurred during the conversion.
• Config Map: If the return code is 0, contains a map containing the values of the STAX Configuration variables. If the return code is not 0, it's set to None.
• Error list - If the return code is not 0, contains a list of the STAF variables which could not be converted (or None if the return code is 0). The list is actually a list of lists where each sublist contains the name of the STAF variable that could not be converted, the machine, the RC, and the STAFResult.

Example:

Import the STAF Configuration variables on machine 'machA' creating a STAX variable map containing their values. This example also shows how you can save STAXResult into three variables (e.g. rc, the name of a map containing the STAF Configuration variable values, and an errorList) immediately following the function call, instead of referencing STAXResult[0], STAXResult[1], STAXResult[2]. Then it checks if all the STAF variables were successfully converted and stored in the map and shows how the the values in the map can be accessed.

  <call function="'STAXUtilImportSTAFConfigVars'">'machA'</call>

  <script>[rc, configMap, errorList] = STAXResult</script>

  <call function="'STAXUtilCheckSuccess'">
    { 'result': rc == 0,
      'failMsg': 'STAXUtilImportSTAFConfigVars failed.  RC=%s ErrorList=%s' % \
                 (rc, errorList),
      'sendToMonitor': 1, 'recordStatus': 0 }
  </call>

  <if expr="rc == 0"> 
    <sequence>

      <!-- Now you can use the configMap as needed.  For example: -->

      <message>'Config info for machine %s:' % machName</message>
      <message>'  OS Name:  %s' % configMap["OSName"]</message>
      <message>'  OS Major Version:  %s' % configMap["OSMajorVersion"]</message>
      <message>'  OS Minor Version:  %s' % configMap["OSMinorVersion"]</message>
      <message>'  OS Revision :  %s' % configMap["OSRevision"]</message>
      <message>'  File Separator :  %s' % configMap["FileSep"]</message>
      <message>'  Path Separator :  %s' % configMap["PathSep"]</message>
      <message>'  Line Separator :  %s' % configMap["LineSep"]</message>

    </sequence>
  </if>

  [0, {'OSRevision': '2195', 'OSMinorVersion': '0', 'OSName': 'Win2000', 'OSMajorVersion': '5',
   'LineSep': '\r\n', 'PathSep': ';', 'FileSep': '\\'}, None]

If not successful because STAF variable STAF/Config/OS/Revision does not exist on machA: STAXResult would be:

  [1, None, [['STAF/Config/OS/Revision', 'machA', 13, 'STAF/Config/OS/Revision']]]

STAXUtilExportSTAFVars

Exports STAX variables, creating STAF variables from them on the specified machines.

For each STAX variable name that is specified, a STAF variable with the specified name is created for the specified machines.

This function takes a list of arguments
Name	Description	Required	Default
varMap	A map containing STAX variable names to be converted to STAF variables. The key is the name of the STAX variable to convert and its value is the name of the STAF variable to create.	Yes	N/A
machList	List of the machine(s) where the STAF variables are to be created.	Yes	N/A

Returns:

If all STAX variables were successfully converted to STAF variables on the specified machines, returns a return code of 0.

If one or more errors occurred during conversion, returns a return code of 1 and a result which contains a list of the STAX variables which could not be converted. The list is actually list of lists, where each sublist contains the name of the STAX variable, the machine, the RC, and the STAFResult.

Example:

Export two STAX variables, and convert them into STAF variables named myProject/testDir and myProject/testProject on machines 'machA' and 'machB'.

  <call function="'STAXUtilExportSTAFVars'">
    [ 
      {'testDir': 'myProject/testDir', 'testProject': 'myProject/testProject'},
      ['machA', 'machB' ]
    ] 
  </call>

If not successful because STAX variable testDir does not exist and machine machineB does not exist, STAXResult would be:

  [ 1,
    [ ['testDir', 'machA', 1, 'KeyError: testDir'],
      ['testDir', 'machB', 1, 'KeyError: testDir'],
      ['testDir', 'machB', 16, 'getInAddrByName: 11001'],
      ['testProject', 'machB', 16, 'getInAddrByName: 11001']
  ] ]

STAXUtilQueryAllTests

For each STAX variable name that is specified, a STAF variable with the specified name is created for the specified machines. Query the results for all testcases in the currently running job, accumulating the total number of testcases, passes, and fails recorded so far as well as a map of all the testcases and their passes, fails, elapsed time, and number of starts.

This function does not allow any arguments

Returns:

Returns the following in a list:

• Return code (0 if the query is successful; 1 if the query fails),
• Result (blank if the query is successful; otherwise, it contains information about the error),
• List containing the total number of testcases, the total number of passes, and the total number of fails (an empty list if fails),
• Testcase results map containing an entry for each testcase (an empty map if fails). The map's key is testcase name and its value is a list of the number of passes, number of fails, elapsed time, and number of starts.

For example, if the query of testcase results was successful and there were 2 testcases, TestA and TestB, where Test A had 4 passes, 1 fail, ran for 5 minutes and 23 seconds, and was started once and Test B had 1 pass, 0 fails, ran for 26 hours 5 minutes and 45 seconds and was started 5 times, and "Log TC Elapsed Time" and "Log TC Num Starts" are enabled for the job, the following would be returned:

  [0, '', [2, 5, 1], {'TestA': [4, 1, '00:05:23', 1], 'TestB': [1, 0, '26:05:45', 5]}]

  [0, '', [2, 5, 1], {'TestA': [4, 1, None, None], 'TestB': [1, 0, None, None]}]

[1, 'Format is not Testcase Name;NumPasses;NumFails. Line=TestA00' % line, [], {}]

Example:

Here's an example that queries the results of all testcases run so far in the current job. If the query is successful, it checks if there have been any testcase failures logged so far. If so, it logs a message and sends it to the STAX Monitor. If the query fails, it logs a failure message and sends it to the STAX Monitor.

  <call function="'STAXUtilQueryAllTests'"/>
  
  <script>[rc, result, totals, testcases] = STAXResult</script>
  
  <if expr="rc == 0">
    <sequence>
      <script>[totalTests, totalPasses, totalFails] = totals</script>
      <if expr="totalFails > 0">
        <call function="'STAXUtilLogAndMsg'">
          'Total Testcases: %s, Total Passes: %s, Total Fails: %s\nTestcases: %s' % \
            (totalTests, totalPasses, totalFails, testcases)
        </call>
      </if>  
    </sequence>
    <else>
      <call function="'STAXUtilLogAndMsg'">
        'STAXUtilQueryAllTests failed. RC=%s Result=%s' % (rc, result)
      </call>
    </else>
  </if>

STAXUtilQueryTest

Query the results for a single testcase in the currently running job.

This function takes a single argument
Name	testname
Description	Name of the testcase to get the results for, so far. The default is the currently running testcase.
Required	No
Default	STAXCurrentTestcase

Returns:

Returns the following in a list:

• Return code (0 if the query is successful; if not successful, set to the return code from the query request or 1 if an error occurs parsing the results from the query),
• Result (blank if the query is successful; otherwise, it contains information about the error),
• List containing the number of passes, the number of fails, the elapsed time, and the number of starts for the testcase (or an empty list if the query fails),

For example, if the query of a testcase is successful and it had 4 passes, 1 fail, ran for 1 minute and 23 seconds, and was started 2 times, the following would be returned:

  [ 0, '', [4, 1, '00:01:23', 2] ]

  [ 48, 'Testcase does not exist', [] ]

Examples:

1. Here's an example that queries the result of the current testcase. If the query is successful, it logs the pass message and sends it to the STAX Monitor. If the query fails, it logs the failure message and sends it to the STAX Monitor.

     <call function="'STAXUtilQueryTest'"/>
     
     <script>[rc, result, totals] = STAXResult</script>
   
     <call function="'STAXUtilCheckSuccess'">
       { 'result': rc == 0,
         'failMsg': 'STAXUtilQueryTest failed.  RC=%s Result=%s' % (rc, result),
         'passMsg': 'Testcase: %s, Passes: %s, Fails: %s' % \
                    (STAXCurrentTestcase, totals[0], totals[1]),
         'sendToMonitor': 1, 'recordStatus': 0 }
     </call>

2. Here's an example that queries the result of testcase 'FSTests.Test1'. If the query is successful, it checks if there have been any fail results recorded for this testcase. If so, it logs the current testcase result information and sends it to the STAX Monitor.

     <script>testName = 'FSTests.Test1'</script>      
           
     <call function="'STAXUtilQueryTest'">testNamelt;/call>
     
     <script>[rc, result, totals] = STAXResult</script>
     
     <if expr="rc == 0">
       <sequence>
         <script>[passes, fails, elapsedTime, numStarts] = totals</script>
         <if expr="fails > 0">
           <call function="'STAXUtilLogAndMsg'">
             'Testcase: %s, Passes: %s, Fails: %s, ElapsedTime: %s, NumStarts: %s' % \
             (testName, passes, fails, elapsedTime, numStarts)
           </call>
         </if>  
       </sequence>
     </if>