STAX Service User's Guide

June 26, 2008

Document Owners: Sharon Lucas, David Bender
eMail Addresses: lucass@us.ibm.com, bdavid@us.ibm.com

Table of Contents

Overview

Concepts

Using XML to Define STAX Jobs

Using Python for Expression Evaluation

Element Syntax and Usage

System Requirements

Installation and Configuration

Request Syntax

STAX Monitoring

STAX Logging

STAX Variables

STAXGlobal Class

STAX Python Interfaces

STAX File Caching

STAX Extensions

Generating STAX Function Documentation

Debugging

Events Generated by STAX that Provide Job Status

Support Information

Appendix A: STAX XML Document Examples

Appendix B: STAX Error Code Reference

Appendix C: STAX Document Type Definition (DTD)

Appendix D: STAX Extensions Document Type Definition (DTD)

Appendix E: References

Appendix F: Jython and CPython Differences

Appendix G: Licenses and Acknowledgements

Overview

STAX accepts job definitions, in the form of XML documents. Fundamentally, these job definitions allow you to specify the processes and STAF commands necessary to perform the job. STAX provides a wealth of expressive functionality on top of this, making it easy to implement, manage, track, and monitor your jobs.

STAX uses the Python scripting language for variable and expression evaluation. The Python code is executed by Jython, a version of Python written entirely in Java. This allows STAX to take advantage of the powerful and easy-to-use features of Python.

The sections that follow describe the basic concepts behind STAX, explain the STAX XML language used to define your jobs, and detail the commands externalized by the STAX service. Read on to find out more about the exciting new world of STAX.
 

Concepts

STAX Elements

Processes and Commands

• A process element really defines the execution information for a STAF PROCESS START command. A process element specifies a command to be executed and the machine where it should run. For example, the command could specify to run a Java application or a Python file which is one of your testcases. A process element may contain many optional elements (which corrrespond to optional options that you can specify for a STAF PROCESS START command). For example, the parms, workdir, env, stdin, stdout, and stderr elements are some of the optional elements that can be specified within a process element. Note that you may specify an "if" attribute for each of these optional elements which provides a convenient shortcut to deal with many variations of optional process elements that, otherwise, would have to be specified using the if/elseif logic elements and multiple different process elements.

• A stafcmd element defines execution information for other STAF commands. A stafcmd element specifies the STAF service and request to be executed (e.g. RESPOOL REQUEST POOL, FS COPY FILE) and the machine where it should be run.

Processes and stafcmds may be put into sequential and/or parallel wrappers which can be nested.

Expression Evaluation via Python

For example, instead of hardcoding the name of the machines where processes and commands are executed during the job, a Python variable can be assigned the name of the machine and specified for the location element. Python variables also be provided at the time the job is requested to be executed. A Python variable may also be assigned a list of machine names.

After STAX processes some elements (e.g. process and stafcmd), the return code and result (if applicable) are accessible via STAX variables. These variables can be referenced by other STAX elements (e.g. via the if element's expression attribute) to determine logic flow within the job.

Groups

Loops

STAX-Threads

Whenever a new STAX-Thread is created, existing variables are cloned from the parent STAX-Thread. To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section. STAX elements that can create STAX-Threads include the following: <parallel>, <paralleliterate>, <process-action>, <job-action>, and <function> elements with a local scope.

Wrappers

Functions

Sub-Jobs

Logic Flow

Exceptions and Signals

Monitoring STAX Jobs

Logging

The STAX Service also maintains an individual job log for each submitted job.  These job-specific logs record information such as testcase status and job execution tracing. If the "log" element is used within the STAX Job Definition, then a user log is also created for the submitted job.

Queues

Alternatively, if you want your STAX job to use a queue on the STAX service side to send and receive messages, you can create your own STAF handle and use it's queue. Refer to Sample STAX Job 3 - Creating a STAF Handle and Using it's Queue for an example of how to create a STAF handle within a STAX job and use it's queue to get messages.
 

Using XML to Define STAX Jobs

STAX uses XML (Extensible Markup Language) to describe STAX job definitions. XML is a language defined by the World Wide Web Consortium (W3C), the body that sets the standards for the Web. It is called extensible because it is not a fixed format like HTML (a single, predefined markup language). Instead, XML is actually a 'metalanguage' -- a language for describing other languages -- which lets you design your own customized markup languages for limitless different types of documents. This section reviews some XML fundamentals. Refer to the "References" section for where to get more information about XML.

Both markup and text in an XML document are case-sensitive. All XML processing instructions start with <? and end with ?>. XML comments start with <!-- and end with -->. In XML, tags always start with < and end with >. The names that can be used for a tag are defined by the DTD (Document Type Definition).

XML documents are made up of XML elements. Much like in HTML, you create XML elements with an opening tag, such as <stax>, followed by the element content (if any), such as text or other elements, and ending with the matching closing tag that starts with </, such as </stax>. It's necessary to enclose the entire document, except for processing instructions, in one element, called the root element -- that's the <stax> element here:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
   .
   .
   .
</stax>

Empty Elements

<nop/>

Attributes

If the attribute value contains both single and double quotes, you can use the XML-defined entity &apos; for a single quote and &quot; for double quotes.

An example of a defaultcall element with a function attribute is:

<defaultcall function="MainFunction"/>

Creating a STAX XML document

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
  <defaultcall function="FunctionA"/>

  <function name="FunctionA">
      ...
  </function>

  <function name="FunctionB">
      ...
  </function>

  <function name="FunctionC">
      ...
  </function>
</stax>

The function element can contain a single task element as defined by the STAX DTD. Here, I added a process element to FunctionA, a stafcmd element to FunctionB, and a log element to functionC. A process element can contain other elements. In this case I added location, command, and parms. A stafcmd element can contain other elements. In this case I added location, service, and request.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>
  <defaultcall function="FunctionA"/>

  <function name="FunctionA">
      <process>
        <location>'local'</location>
        <command>'java'</command>
        <parms>'com.ibm.staf.service.stax.TestProcess 2 4 0'
      </process>
  </function>

  <function name="FunctionB">
      <stafcmd>
        <location>'local'</location>
        <service>'misc'</service>
        <request>'version'</request>
      </stafcmd>
  </function>

  <function name="FunctionC">
      <log>'This function logs this message'</log>
  </function>
</stax>

Document Type Definition (DTD)

For example, the STAX DTD allows you to describe a STAF Command which has a name attribute and contains location, service, and request elements. The relevant part of the STAX DTD contains:

            <!ELEMENT stafcmd   (location, service, request)>
            <!ATTLIST stafcmd
                      name      CDATA    #IMPLIED
            >
            <!ELEMENT location  (#PCDATA)>
            <!ELEMENT service   (#PCDATA)>
            <!ELEMENT request   (#PCDATA)>

            <stafcmd name="'Delay'">
              <location>'local'</location>
              <service>'delay'</service>
              <request>'delay 5000'</request>
            </stafcmd>

Refer to the References section for where to get more information about the XML Parser for Java.

You can use your favorite text editor to create a STAX XML document, or you can use an XML editor such as Cooktop. If you use an XML editor, you'll probably want to get the STAX DTD file so that the XML editor can use it to validate the XML syntax. The stax.dtd file is not provided with the STAX service because its contents can vary because you can extend it by registering STAX service extensions. You can get the stax.dtd file by running the following from a command prompt on your STAX service machine:

  set STAF_QUIET_MODE=1               (or if on Unix:  export STAF_QUIET_MODE=1)
  STAF local STAX GET DTD > stax.dtd
  set STAF_QUIET_MODE=                (or if on Unix:  unset STAF_QUIET_MODE)

Using Python for Expression Evaluation

STAX uses the Python for variable and expression evaluation. STAX uses Jython to execute the Python code. Jython is an implementation of the Python scripting language written in 100% pure Java that runs under any compliant Java Virtual Machine (JVM). Using Jython, you can write Python code that interacts with any Java code.

STAX variable names must follow the Python variable naming conventions. In Python, variable names come into existence when you assign values to them, but there are a few rules to follow when picking names for variables.

• Syntax: (underscore or letter) + (any number of letters, digits or underscores)
Variable names must start with an underscore or letter, and be followed by any number of letters, digits, or underscores. _machine, machine, and Mach_1 are legal names, but 1_Mach, mach$, and @#! are not.
• Case matters: MACHNAME is not the same as machname
Python always pays attention to case, both in names you create and in reserved words. For instance, X and x refer to two different variable names.
• Python reserved words are off limits
You cannot define variable names to be the same as words that mean special things in the Python language. Following are reserved words in Python: and, assert, break, class, continue, def, del, elif, else, except, exec, finally, for, from global, if, import, in, is, lambda, not, or, pass, print, raise, return, try, while.

Note: Python lets you use the names of Python built-in functions as variable names. However, we recommend that you don't use the name of a Python built-in function as a variable name because you may want to use the Python built-in function at some point in your STAX job. Following are names of Python built-in functions: abs, basestring, bool, callable, chr, classmethod, cmp, compile, complex, delattr, dict, dir, divmod, enumerate, eval, execfile, file, filter, float, getattr, globals, hasattr, hash, help, hex, id, input, int, isinstance, issubclass, iter, len, locals, long, map, max, min, object, oct, open, ord, pow, property, range, raw_input, reduce, reload, repr, round, setattr, slice, staticmethod, str, sum, super, tuple, type, unichr, unicode, vars, xrange, zip.

• STAX reserved words are off limits
You should not define variable names to be the same as words that mean special things to the STAX service. Following are reserved words in STAX:
• RC
• STAFResult
• any word beginning with STAX (e.g. STAXJobName, STAXThreadID)
• any word beginning with STAF (e.g. STAFResult, STAFRC)

For example, the following two lines do exactly the same thing in a STAX XML document.  They assign a string constant (literal) "CoolTest" to the value of a variable named testName.

<script>testName = "CoolTest1"</script>
<script>testName = 'CoolTest1'</script>

<script>testName = CoolTest1</script>

For elements and attributes whose values are evaluated via Python, we need to distinguish between literals and variables.

For example, the following request element's value contains a string constant which is concatenated with the value of a variable named machName.  So, if the value of variable machName is 'testA.austin.ibm.com', after being evaluated by Python, the request element's value would be:  'RELEASE POOL ClientMachPool ENTRY testA.austin.ibm.com'.

<request>'RELEASE POOL ClientMachPool ENTRY ' + machName</request>

<request>'RELEASE POOL ClientMachPool ENTRY %s' % (machName)</request>

Also, note that the following two lines do exactly the same thing in a STAX XML document.  They assign a string constant (literal) "VerifyRC" to the function attribute's value.

<call function="'VerifyRC'"/>
<call function='"VerifyRC"'/>

<call function="VerifyRC"/>

<if expr="RC &lt; 0">

<script>
  import re

  # Look for <pass> anywhere in the string.
  # Note have to use &lt; to represent a < in the pattern.
  matchstr = r'.*?&lt;pass>.*?'

  matchFlag = re.match(matchstr, STAFResult)
</script>

If you are already a CPython programmer, or are hoping to use CPython code under Jython, refer to the "Jython and CPython Differences" section for information about differences in the two implementations of Python.
 

Element Syntax and Usage

The first line in an XML document should start with an XML declaration. This indicates the document is written in XML and specifies the XML version, the language encoding for the document, and indicates that the document refers to an external DTD (standalone="no").

The second line in an XML document should be the document type declaration. This is used to indicate the DTD used for the document. It defines the name of the root element (stax), and the DTD to be used. STAX checks the syntax of XML documents using a validating XML parser to verify that the document complies with the DTD. Note that DTDs are all about specifying the structure and syntax of XML documents (not their content).

So, the first two lines in a STAX XML document should look like:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

To ease the description of the elements, some elements will be grouped as follows so that they can be referenced as a group and will be shown in bold italics:

   Reference       Elements

   task              process | stafcmd | nop |
                     sequence | parallel | paralleliterate |
                     call | call-with-list | call-with-map | return | import |
                     if | loop | iterate | break | continue |
                     try | throw | rethrow |
                     signalhandler | raise |
                     hold | release | terminate |
                     testcase | tcstatus | script |
                     block | timer | log | message

• Elements and attribute names in an XML document are case sensitive. That is, element <sequence> is different from <Sequence> and <SEQUENCE>.
• Only sequence, parallel and stax elements can contain multiple task elements.
• Names for elements (e.g. function names, block names, etc.) should not begin with STAX as these names are reserved for future extensions and enhancements.

Also, some examples of the usage of elements use "..." for brevity to represent that additional XML would be included in place of the "...".

Root Element

stax

Usage:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="FunctionA"/>
  <script>machName = "test1.austin.ibm.com"</script>

  <function name="FunctionA">
    ...
  </function>

  <function name="FunctionB">
    ...
  </function>
  ...

</stax>

Python Code Execution

All script elements contained in the root stax element are initialized at the beginning of the job, as each is encountered in sequential order, regardless of their placement within the stax element, and are accessible throughout the job (like global variables).  All script elements contained in elements other than the stax element (e.g. such as the sequence element) are assigned as each is encountered and are accessible within their scope and are inherited from parent STAX-Threads.

Whenever a new STAX-Thread is created, existing variables are cloned from the parent STAX-Thread. To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section. STAX elements that can create STAX-Threads include the following: parallel, paralleliterate, process-action, job-action, and function elements with a local scope.

script: Run Python Code

Usage:

<script>testName = "CoolTest1"</script>

<script>machName = STAFResult</script>

<script>machList = []</script>
<script>clientPool = 'ClientMachinePool'</script>
<loop var="i" from="1" to="10">
  <sequence>
    <stafcmd>
      <location>'server1.austin.ibm.com'</location>
      <service>'RESPOOL'</service>
      <request>'REQUEST POOL %s' % (clientPool)</request>
    </stafcmd>
    <script>machList.append(STAFResult)</script>
  </sequence>
</loop>

<script>unallocMachList = ['MachA','MachB','MachC','MachD']</script>
<script>allocMachList = ['AllocMachA','AllocMachB']</script>
<script>allMachList = unallocMachList + allocMachList</script>

<script>from random import random; r=random()*100</script>

<script>
  NotifyProfile = 'Jane Smith'
  Message = 'STAX Job ID %s failed.' % (STAXJobID)

  from com.ibm.staf import STAFUtil

  Request = ('NOTIFY PROFILE %s LEVEL NORMAL MESSAGE %s' %
            (STAFUtil.wrapData(NotifyProfile), STAFUtil.wrapData(Message)))
</script>

<message>NotifyRequest</message>

NOTIFY PROFILE :10:Jane Smith LEVEL NORMAL MESSAGE :21:STAX Job ID 6 failed.

<script>
  # Define Server class
  class Server:
    def __init__(self, hostname, dir):
      self.hostname = hostname
      self.dir      = dir
    def __repr__(self):
      return "<Server: hostname=%s, directory=%s>" % (self.hostname, self.dir)
    def getHostname(self):
      return self.hostname
    def getDir(self):
      return self.dir

  # Create an array of 3 Server objects
  serverList = [
                 Server('myServer.austin.ibm.com', 'C:/install'),
                 Server('serverA.portland.ibm.com', 'D:/install'),
                 Server('linuxServer.austin.ibm.com', '/usr/local/install')
               ]
</script>

<iterate var="server" in="serverList" indexvar="i">
  <log>
    'Server #%s: hostname=%s, directory=%s' % (i+1, server.getHostname(), server.getDir())
  </log>
</iterate>

Actions

process: Run a process

After a process has completed (or if it could not be started) the following variables are set and can be referenced by the job:

• RC - the return code from the process. It is numeric. If it's the actual return code from the process, it is a Python Long numeric type (e.g. 0L, 25L). If an error occurred starting the process, it is a Python Integer numeric type.
• STAFResult - the STAF result from starting the process. If the process failed to start successfully, it contains any error messages from starting the process in a Python string type. If the process started successfully, it is set to special Python object None.
• STAXResult - contains any files specified by returnstdout, returnstderr, and/or returnfile(s). If no files are returned, STAXResult is set to special Python object None. If one or more files are returned, the format of STAXResult is a list as follows:

  [ [<File 1 rc>, <File 1 data>], [<File 2 rc>, <File 2 data> ], ... ]

  Each entry in the list represents a returned file and consists of a 2-element list as follows:
  1. <File n rc> is a number containing the STAF return code indicating the success or failure of retrieving the file's contents
  2. <File n data> is a string containing the file's contents

  Files will be returned in the order of standard output, then standard error, then any files specified with the returnfile(s) element(s).

  For example, assume that the standard output of a process was simply "This is stdout data", and that the standard error of a process was "This is stderr data", and that you asked for both of these to be returned. STAXResult would look like the following.

  [ [0, 'This is stdout data'], [0, 'This is stderr data'] ]

• name - This element is optional. It is the name that the STAX Monitor uses to refer to the <process> element. It defaults to Process<number>, where <number> is a unique number for each process executed in a job.

The process element contains two required elements (location and command) with many optional elements. The location element must be specified first, followed by the command element. The rest of the elements are optional.

Note that the process elements are equivalent to the options allowed for the STAF Process Service's START request (except where noted), so see the STAF User's Guide for more information.

Required process elements:

• location - Location specifies the machine where the process should be run. This element is required.
• command - This element is required.

This element has the following optional attributes:

• mode - specifies whether the command should be executed as though you were at a shell prompt. The value must evaluate via Python to one of the following:
  • 'default' - specifies that the command should not be started via a separate shell. This is the default.
  • 'shell' - specifies that the command should be started via a separate shell. This allows complex commands involving pipelines to be readily executed.
• shell - specifies the shell to use when starting the process via a separate shell. This attribute is used only if the command's mode is set to 'shell'. The value overrides any shell defaults specified in the STAF configuration file. The value is evaluated via Python to a string.

Optional process elements:

Here are some important notes about optional process elements:

1. If specified, these optional process elements must be specified in the order listed below (with some variations). Refer to the "STAX Document Type Definition (DTD)" section to see the DTD for the process element and to see the variations in process element order that are allowed.

2. Each of these optional elements may specify an if attribute. The if attribute must evaluate via Python to a true or false value. If it does not evaluate to a true value, the element is ignored. The default value for the if attribute is 1, a true value. Note that in Python, true means any nonzero number or nonempty object; false means not true, such as a zero number, an empty object, or None. Comparisons and equality tests return 1 or 0 (true or false).

   Using the if attribute provides a convenient shortcut to deal with many variations of optional process elements that, otherwise, would have to be specified using the if/elseif elements and multiple different process elements.

The process element may contain any of the following optional elements in the order listed (with some variations):

• parms - specifies any parameters that you wish to pass to the command. The value is evaluated via Python to a string. This element is optional.
• workdir - specifies 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. The value is evaluated via Python to a string. This element is optional.
• title - specifies the program title of the process. Unless overridden by the process, the title will be the text that is displayed on the title bar of the application. The value is evaluated via Python to a string. This element is optional.
• workload - specifies the name of the workload for which this process is a member. This may be useful in conjunction with other process elements. The value is evaluated via Python to a string. This element is optional.
• vars (or var) - specifies STAF variables that go into the process specific STAF variable pool. The value must evaluate via Python to a string or a list of strings. Multiple vars elements may be specified for a process. The format for each variable is: 'varname=value' So, a list containing 3 variables could look like: ['var1=value1', 'var2=value2', 'var3=value3']. Specifying only one variable could look like either: ['var1=value1'] or 'var1=value1'. There can be 0 or more occurrences of this element.
• envs (or env) - specifies environment variables that will be set for the process. Environment variables 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 value must evaluate via Python to a string or a list of strings. Multiple envs elements may be specified for a process. The format for each variable is: 'varname=value' So, a list containing 3 variables could look like: ['ENV_VAR_1=value1', 'ENV_VAR_2=value2', 'ENV_VAR_3=value3']. Specifying only one variable could look like either: ['ENV_VAR_1=value1'] or 'ENV_VAR_1=value1'. There can be 0 or more occurrences of this element.
• 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. This element is optional and is an empty element.
• username - specifies the username under which the process should be started. The value is evaluated via Python to a string. This element is optional.
• password - specifies the password with which to authenticate the user specified with the username element. The value is evaluated via Python to a string. This element is optional.
• disabledauth - allows you to specify the action to take if a username/password is specified but authentication has been disabled. This element is optional and is an empty element.

  This element has the following required attribute (in addition to the if attribute):

  • action - Must evaluate via Python to a string containing either:
    • 'error' - specifies that an error should be returned.
    • 'ignore' - specifies that any username/password specified is ignored if authentication is desabled.
    This action overrides any default specified in the STAF configuration file.

• stdin - specifies the name of the file from which standard input will be read. The value is evaluated via Python to a string. This element is optional.
• stdout - specifies the name of the file to which standard output will be redirected. The value is evaluated via Python to a string. This element is optional.

This element has the following required attribute (in addition to the if attribute):

• mode - specifies what to do if the file already exists. The value must evaluate via Python to one of the following:
  • 'replace' - specifies that the file will be replaced. This is the default.
  • 'append' - specifies that the process' standard output will be appended to the file.
• stderr - specifies the file to which standard error will be redirected. The value is evaluated via Python to a string. This element is optional.

This element has the following attribute (in addition to the if attribute):

• mode - specifies what to do if the file already exists or to redirect standard error to the same file as standard output. The value must evaluate via Python to one of the following:
  • 'replace' - specifies that the file will be replaced. This is the default.
  • 'append' - specifies that the process' standard error will be appended to the file.
  • 'stdout' - specifies that standard error will be redirected to the same file to which standard output is being redirected. If a file name is specified, it is ignored.
• returnstdout - specifies to return in STAXResult the contents of the file where standard output was redirected when the process completes. This element is optional and is an empty element.
• returnstderr - specifies to return in STAXResult the contents of the file where standard error was redirected when the process completes. This element is optional and is an empty element.
• returnfiles (or returnfile) - 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). There can be 0 or more occurrences of this element.
• stopusing - allows you to specify the method by which this process will be STOPed, if not overridden on the STOP command. The value is evaluated via Python to a string. This element is optional.
• console - allows you to specify if the process should get a new console window or share the STAFProc console. This element is optional and is an empty element.

  This element has the following required attribute (in addition to the if attribute):

  • use - Must evaluate via Python to a string containing either:
    • 'new' - specifies that the process should get a new console window. This option only has effect on Windows systems. This is the default for Windows systems.
    • 'same' - specifies that the process should share the STAFProc console. This option only has effect on Windows systems. This is the default for Unix systems.

• focus - allows you to specify the focus that is to be given to any new windows opened when starting a process on a Windows system. The window(s) it effects depends on whether you are using the 'default' or the 'shell' command mode. If the process is started using the default command mode, then the specified focus specified is given to any new windows opened by the specified command. Otherwise, if the process is started using the shell command mode, then the specified focus is given only to the new shell command window opened, not to any windows opened by the specified command. This element only has effect on Windows systems and requires STAF V3.1.4 or later on the machine where the process is run. This element is optional and is an empty element.

  This element has the following required attribute (in addition to the optional if attribute):

  • mode - Must evaluate via Python to a string containing one of the following values:
    • 'background' - indicates to display a window in the background (not give it focus) in its most recent size and position. This is the default mode.
    • 'foreground' - indicates to display a window in the foreground (give it focus) in its most recent size and position.
    • 'minimized' - indicates to display a window as minimized.

  Note: This element was added in STAX V3.1.3.

• statichandlename - specifies that a static handle should be created for this process. The value is evaluated via Python to a string. It 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. This element is optional.
• other - specifies any other STAF parameters that may arise in the future. It is used to pass additional data to the STAF PROCESS START request. The value is evaluated via Python to a string. This element is optional.
• process-action - specifies a task which will be executed after the process has started. This task will be executed in parallel with the process via a new STAX-Thread. The task will be able to use the variable STAXProcessHandle to obtain the process' handle in order to interact with the process. If the process completes before the task completes, the process will remain in a non-complete state until the task completes. If the process cannot be started, the process-action task is not executed. This element is optional, but if specified must be the last element in the <process> element.

  Note: To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section.

• WAIT
• ASYNC
• NOTIFY ONEND

Notes:

1. See the timer element section for special considerations regarding accessing stdout/stderr data when using a <timer> element to terminate a process that runs continously. An example is also provided in the timer's "Usage" section.

2. You can use the <stdout> and/or <stderr> elements to stream a process's standard output and standard error, respectively, into a specified file. The contents of the file won't be returned to the user (e.g. via the STAXResult variable if using the <returnstdout> and/or <returnstderr> elements) until the process has completed. But, you could look at the contents of the stdout/stderr file while the process is still running by using a <parallel> or <process-action> element to do this in parallel with the process running.

3. After you obtain the content of a file created by the <stdout> or <stderr> element, if you no longer need the file, you can delete it using a <stafcmd> element to run the FS service's DELETE ENTRY command. Or, if you didn't need the file deleted immediately, you could create the stdout/stderr file in the {STAF/DataDir}/tmp directory. All contents of the {STAF/DataDir}/tmp directory are deleted when STAFProc is restarted.

Usage:

<sequence>

  <process name="'TestProcess'">
    <location>'local'</location>
    <command>'java'</command>
    <parms>'com.ibm.staf.service.stax.TestProcess 5 1 0'</parms>
    <title>'Test Process'</title>
  </process>

  <if expr="RC != 0">
    <raise signal="'NonZeroRCError'"/>
  </if>

</sequence>

<sequence>

  <timer duration="'30s'">
    <loop until="RC == 0">
      <process name="'Ping'">
        <location>'local'</location>
        <command mode="'shell'">'ping -n 1 -w 1 %s' % machName</command>
      </process>
    </loop>
  </timer>

  <if expr="RC != 0">
    <message>'Ping of machine %s failed' % machName</message>
  </if>

</sequence>

<script>
  machName = 'local'
  opSys = 'Win32'
  className = 'com.ibm.staf.service.stax.TestProcess'
  commonEnvVarList = ['COMMON_ENV_VAR_1=value1','COMMON_ENV_VAR_2=value2']
</script>

<process name="'aProcess'">
  <location>machName</location>
  <command>'java'</command>

  <parms if="opSys != 'Linux'">
    '%s 2 15 100' % className
  </parms>

  <title>'Title example for process with many elements'</title>

  <vars if="opSys == 'Win32'">
    ['tempPath=C:/temp', 'winRunPath=C:/temp/processa']
  </vars>

  <vars if="opSys == 'Linux'">
    ['tempPath=/test/temp']
  </vars>

  <var>
    'commonMachName=%s' % (machName)
  </var>

  <envs if="opSys == 'Win32'">
    ['TEMP_DIR=C:/temp']
  </envs>

  <envs>commonEnvVarList</envs>

  <useprocessvars if="opSys == 'Win32'"/>

  <disabledauth if="opSys == 'Win32'" action="'ignore'"/>

  <stdout mode="'replace'">
    'c:/temp/aProcess.out'
  </stdout>

  <stderr mode="'append'">
    'c:/temp/aProcess.err'
  </stderr>

  <console if="opSys == 'Win32'" use="'same'"/>

  <focus if="opSys == 'Win32'" mode="'minimized'"/>

</process>

<sequence>

  <process>
    <location>machName</location>
    <command>cmd</command>
    <stdout>'C:/temp.out'</stdout>
    <stderr mode="'stdout'"/>
    <returnstdout/>
    <returnfiles>['C:/process1.inf', 'C:/process2.inf']</returnfiles>
  </process>

  <if expr="RC != 0">
    <log level="'error'">
      'Process failed with RC=%s, Result=%s' % (RC, STAFResult)
    </log>

    <elseif expr="STAXResult != None">
      <iterate var="fileInfo" in="STAXResult" indexvar="i">
        <if expr="fileInfo[0] == 0">
          <sequence>
            <log level="'info'">fileInfo[1]</log>
          </sequence>
          <else>
            <log level="'error'">
              'Retrieval of file %s contents failed with RC=%s' % (i, fileInfo[0])
            </log>
          </else>
        </if>
      </iterate>
    </elseif>

    <else>
      <log level="'info'">'STAXResult is None'</log>
    </else>

  </if>

</sequence>

<process name="'Grep_and_awk_numClustNodes'">
  <location>machName</location>
  <command mode="'shell'">
    "/bin/grep 'Node Count = '  /tests/cli.out | awk '{print $8}'"
  </command>
  <stdout mode="'replace'" >'tests/awk.out'</stdout>
  <stderr mode="'stdout'"/>
  <returnstdout/>
</process>

<process name="'copyFiles'">
  <location>machName</location>
  <command mode="'shell' shell="'D:/Cygwin/bin/bash -c %C'">
    'cp -fr D:/tests/test1/*.java D:/output/test1'
  </command>
  <stdout mode="'replace'" >'D:/temp/copy.out'</stdout>
  <stderr mode="'stdout'"/>
  <returnstdout/>
</process>

<script>
  machName = 'local'
  className = 'com.ibm.staf.service.stax.TestProcess'
  msg = 'Data being sent to the Process Queue after it starts executing'
</script>

<process name="'aProcess'">
  <location>machName</location>
  <command>'java'</command>
  <parms>className</command
  <process-action>
    <sequence>
      <stafcmd>
        <location>machName</location>
        <service>'QUEUE'</service>
        <request>'QUEUE HANDLE %s %s' % (STAXProcessHandle, msg)</request>
      </stafcmd>
    </sequence>
  </process-action>
  </process>

stafcmd: Run a STAF Command

Note: If you want to start a process and wait for it to complete (e.g. if you want to submit a START request to the PROCESS service and wait for the process to complete), you should use the process element instead of the stafcmd element.

After the STAF command has completed, the following variables are set and can be referenced by the job:

• RC - the return code from the STAF command. It is an integer.
• STAFResult - the result from the STAF command. It can be a string, or, if the result is marshalled, it is the root object of the marshalled result which could be a Python List or a Python Dictionary (aka Map).
• STAFResultContext - the STAF marshalling context object for the result from the STAF command. It is an object of type org.python.core.PyInstance. The STAFMarshallingContext class provides a container for map class definitions and an object that uses (or is defined in terms of) them. Its string representation is equivalent to the "verbose format" (the hierarchical nested format) provided by the STAF executable.

The stafcmd element has one attribute:

• name - This element is optional. It is the name that the STAX Monitor uses to refer to the <stafcmd> element. It defaults to STAFCommand<number>, where <number> is a unique number for each STAF command executed in a job.

The stafcmd element contains the following required elements. These elements must be specified in the order listed here:

• location - It specifies the machine where the STAF command should be run. This element is required.
• service - It specifies the name of the service to which you are submitting a request. This element is required.
• request - It specifies the actual request string that you wish to submit to the service. This element is required.

Usage:

<sequence>

  <script>resPoolServer = "server1.austin.ibm.com"</script>
  <script>clientPool = "clientMachinePool"</script>

  <stafcmd name="'Respool Request Pool'">
    <location>resPoolServer</location>
    <service>'RESPOOL'</service>
    <request>'REQUEST POOL %s' % (clientPool)</request>
  </stafcmd>

  <if expr="RC == STAFRC.STAFOk">
    <script>machName = STAFResult</script>
    <else>
      <log message="1">'RC=%s STAFResult=%s' % (RC, STAFResult)</log>
    </else>
  </if>

</sequence>

If you want to submit a START request to the PROCESS service and wait for the process to complete, you should use the process element, not the stafcmd element. However, if you want to submit a START request to the PROCESS service and not wait for it to complete (e.g. start the process asynchronously) before continuing to the next element in the STAX job, then you can use the stafcmd element. Here's an example of starting notepad on a Windows machine:

<sequence>

  <stafcmd name="'Start Notepad'">
    <location>'client1.company.com'</location>
    <service>'PROCESS'</service>
    <request>'START COMMAND notepad'</request>
  </stafcmd>

  <if expr="RC != STAFRC.STAFOk">
    <log message="1">
      'Starting Notepad failed with RC=%s STAFResult=%s' % (RC, STAFResult)
    </log>
  </if>

</sequence>

In the following example of a stafcmd element, a "SEND MESSAGE" request is submitted to the Email service on machine server1.company.com to send message "STAX Job ID 6 failed" to Jane Smith@company.com.

Note that STAFUtil's wrapData() method is used to turn strings containing spaces into the colon-length-colon form needed for submitting a SEND MESSAGE request to the Email service. Java class STAFUtil needs to be imported from com.ibm.staf in order to use its wrapData() method.

<sequence>

  <script>
    from com.ibm.staf import STAFUtil

    emailServiceMachine = 'server1.company.com'
    message = 'STAX Job ID %s failed.' % (STAXJobID)
    subject = 'STAX Job Failed'
    address = 'JaneSmith@company.com'
    request = 'SEND MESSAGE %s' % (STAFUtil.wrapData(message))
    request += ' SUBJECT %s' % (STAFUtil.wrapData(subject))
    request += ' TO %s' % (address)
  </script>

  <stafcmd>
    <location>emailServiceMachine</location>
    <service>'Email'</service>
    <request>request</request>
  </stafcmd>

  <if expr="RC != 0">
    <log message="1">
      'Email request failed with RC=%s STAFResult=%s' % (RC, STAFResult)
    </log>
  </if>

</sequence>

In the following example of a stafcmd element which executes a FS QUERY ENTRY request on the local machine. A FS QUERY ENTRY request returns a PyDictionary (aka Map) if successful containing information about the file such as its name, type, size, and timestamp that it was last modified. Log the file information in a verbose format by specifying the STAFResultContext variable:

<sequence>

  <stafcmd>
    <location>'local'</location>
    <service>'FS'</service>
    <request>'QUERY ENTRY C:/tmp/testA.exe'</request>
  </stafcmd>

  <if expr="RC == STAFRC.Ok">
    <log message="1">STAFResultContext</log>
    <else>
      <log message="1">'FS QUERY failed with RC=%s STAFResult=%s' % (RC, STAFResult)</log>
    </else> 
  </if>

</sequence>

The message logged in verbose mode could look like:

{
  Name              : C:/tmp/testA.exe
  Type              : F
  Upper 32-bit Size : 0
  Lower 32-bit Size : 12505
  Modified Date-Time: 20030506-19:14:40
}

In the following example of a stafcmd element which executes a FS LIST DIRECTORY LONG DETAILS request on the local machine. A FS LIST DIRECTORY LONG DETAILS request returns a PyList of PyDictionary (aka Map) if successful, where each PyDictionary represents an entry in the specified directory and has keys such as 'name', 'lowerSize', 'type', and 'lastModifiedTimestamp'. It then checks for entries in the directory which are files with a size > 500000 bytes and logs a message containing the names of all the files meeting this criteria, along with their size and the timestamp that they were last modified.

<sequence>

  <stafcmd>
    <location>'local'</location>
    <service>'FS'</service>
    <request>'LIST DIRECTORY C:/tmp LONG DETAILS'</request>
  </stafcmd>

  <script>
    msg = ''

    if RC == STAFRC.Ok:
      for entryMap in STAFResult:
        # Check if the entry is a file whose size is greater than 500000 bytes
        if entryMap['type'] == 'F' and int(entryMap['lowerSize']) > 500000:
          # Print the name, size, and last Modified Timestamp for the entry:
          msg += 'Name: %s, Size: %s, Timestamp: %s\n' % \
               (entryMap['name'], entryMap['lowerSize'], entryMap['lastModifiedTimestamp'])
    else:
      msg = 'FS LIST ENTRY failed with RC=%s Result=%s' % (RC, STAFResult)
  </script>
 
  <log message="1">msg</log>

</sequence>

The message logged could look like:

Name: en_platformsdk_win2003.exe, Size: 340488704, Timestamp: 20040512-18:07:52
Name: project-docs.tar, Size: 1239040, Timestamp: 20040517-11:57:10

job: Execute a STAX Sub-Job

Notes:

• A sub-job will appear as a separate job.
• Terminating a parent job will terminate any sub-jobs as well.
• Holding/releasing a parent job will not hold/release its sub-jobs.

After a sub-job has completed (or if it could not be started) the following variables are set and can be referenced by the job:

• RC - the return code from submitting the request to execute the sub-job. It is an integer.
• STAFResult - the STAF result from submitting the request to execute the sub-job. If the sub-job failed to start successfully, it contains any error messages from trying the execute the sub-job. It is a string.
• STAXSubJobID - the job ID of the sub-job. If the sub-job was not successfully submitted for execution (e.g. due to a command parsing error, an XML parsing error, etc.), it is set to 0. It is an integer.
• STAXResult - contains the result returned by the starting function of the sub-job. If nothing is returned (due to a problem submitting the request to execute the sub-job, or an error running the sub-job, or if an empty <return> element or if no <return> element is specified in the starting function), STAXResult is set to special Python object None.

• STAXSubJobStatus - contains the completion status of the sub-job. The sub-job completion status is a string that will be set to one of the following values:
  • 'Normal' if the sub-job ended normally
  • 'Terminated' if the sub-job was terminated (this means if the 'main' block was terminated)
  • 'Abnormal' if the sub-job ended abnormally. A couple of examples of a sub-job ending abnormally are when at least one unhandled inherited condition remains on the condition stack when the sub-job completes. This can occur when a break or continue condition remains on the condition stack because there was no outer loop or iterate element, or when an exception is thrown but there's no catch element for it. This state takes precedence if the sub-job is also terminated.
  • 'Unknown' if the sub-job was not successfully submitted for execution (e.g. due to an XML parsing error, etc).

The job element has the following optional attributes:

• name - Specifies the name of the sub-job that is used to identify the sub-job. This attribute is equivalent to the JOBNAME option for a STAX EXECUTE command.
• clearlogs - specifies whether to delete the STAX Job and Job User logs before the sub-job is executed to ensure that only this sub-job's contents are in the log. This attribute is equivalent to the CLEARLOGS option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Clear Logs".
  • 'enabled' - specifies to clear its job logs
  • 'disabled' - specifies to not clear its job logs
  • otherwise, if it evaluates to a true value, the job logs are cleared; if it evaluates to a false value, the job logs are not cleared.
• monitor - If it evaluates to true, it specifies that the job should automatically be monitored by the STAX Monitor (when the current job is already being monitored by the STAX Monitor). Note that "Automatically monitor recommended sub-jobs" must be selected in the STAX Job Monitor properties in order for it to be used. The default value is 0, a false value.
• logtcelapsedtime - specifies whether to log the elapsed time for testcases in the summary records at the end of a STAX Job log and in the LIST TESTCASES output for the sub-job. This attribute is equivalent to the LOGTCELAPSEDTIME option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Log TC Elapsed Time".
  • 'enabled' - specifies to log the elapsed time for testcases
  • 'disabled' - specifies to not log the elapsed time for testcases
  • otherwise, if it evaluates to a true value, the elapsed time for testcases is logged; if it evaluates to a false value, the elapsed time for testcases is not logged.
• logtcnumstarts - specifies whether to log the number of starts for testcases in the summary records at the end of a STAX Job log and in the LIST TESTCASES output for the sub-job. This attribute is equivalent to the LOGTCNUMSTARTS option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Log TC Num Starts".
  • 'enabled' - specifies to log the number of starts for testcases
  • 'disabled' - specifies to not log the number of starts for testcases
  • otherwise, if it evaluates to a true value, the number of starts for testcases is logged; if it evaluates to a false value, the number of starts for testcases is not logged.
• logtcstartstop - specifies whether to log 'start' and 'stop' level records for testcases in the STAX Job log. This attribute is equivalent to the LOGTCSTARTSTOP option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Log TC Start/Stop".
  • 'enabled' - specifies to log the 'start' and 'stop' records for testcases
  • 'disabled' - specifies to not log the 'start' and 'stop' records for testcases
  • otherwise, if it evaluates to a true value, the 'start' and 'stop' records for testcases are logged; if it evaluates to a false value, the 'start' and 'stop' records for testcases are not logged
• pythonoutput - specifies where Python stdout/stderr should be redirected (e.g. if you use the print statement in a <script> element in the sub-job). This attribute is equivalent to the PYTHONOUTPUT option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Python Output".
  • 'jobuserlog' - specifies to redirect Python stdout/stderr to the STAX Job User Log
  • 'message' - specifies to redirect Python stdout/stderr to the Messages panel in the STAX Monitor.
  • 'jobuserlogandmsg' - specifies to redirect Python stdout/stderr to the STAX Job User Log and to the Messages panel in the STAX Monitor.
  • 'jvmlog' - specifies to redirect Python stdout/stderr to the JVM Log for the STAX service.
  • otherwise, if it evaluates to something else, an error will occur when the job is submitted for execution and the RC variable will be set to 47 (Invalid value) with additional information in the STAFResult variable.
• pythonloglevel - specifies the STAF log level to use when Python stdout is redirected to the STAX Job User Log (so it only has an effect if pythonloglevel is set to 'jobuserlog' or 'jobuserlogandmsg'). This attribute is equivalent to the PYTHONLOGLEVEL option for a STAX EXECUTE command. The value must evaluate via Python to one of the following (not case-sensitive):
  • 'parent' - specifies to use the same value that was specified for the parent job. This is the default.
  • 'default' - specifies to use the default STAX service setting for "Python Log Level".
  • One of the STAF logging levels: 'fatal', 'error', 'warning', 'info', 'trace', 'trace2', 'trace3', 'debug', 'debug2', 'debug3', 'start', 'stop', 'pass', 'fail', 'status', 'user1', 'user2', 'user3', 'user4', 'user5', 'user6', 'user7', or 'user8'.
  • otherwise, if it evaluates to something else, an error will occur when the job is submitted for execution and and the RC variable will be set to 47 (Invalid value) with additional information in the STAFResult variable.

The job element contains the following elements in the order listed (with some variations). Refer to the "STAX Document Type Definition (DTD)" section to see the DTD for the job element.

Note that these elements are equivalent to the options allowed for the EXECUTE request (except where noted), so refer to the "EXECUTE" section for more information.

The job element must contain either a job-file or job-data element as follows:

• job-file - Specifies the fully qualified name of a file containing the XML document for the sub-job to be executed. The job-file element is equivalent to the FILE option for an EXECUTE request. This element has the following optional attribute:
  • machine - specifies the name of the machine where the XML document is located. If not specified, it defaults to Python variable STAXJobXMLMachine. The machine attribute is equivalent to the MACHINE option for an EXECUTE request.

• job-data - Specifies a string containing the XML document contents for the job to be executed. This element is equivalent to the DATA option for an EXECUTE request. This element has the following optional attribute:
  • eval - specifies whether the data is to be evaluated by Python in the parent job. This value must evaluate via Python to a true or false value. For example, if the job-data value is dynamically generated and assigned to a Python variable, rather then just containing the literal XML value, you would need to set the eval attribute to true (e.g. eval="1"). The default is false (eval="0").

The job element has the following optional elements. Each of these optional elements may specify an if attribute. The if attribute must evaluate via Python to a true or false value. If it does not evaluate to a true value, the element is ignored. The default value for the if attribute is 1, a true value. Note that in Python, true means any nonzero number or nonempty object; false means not true, such as a zero number, an empty object, or None. Comparisons and equality tests return 1 or 0 (true or false).

• job-function - specifies the name of the function element to call to start the job, overriding the defaultcall element, if specified, in the XML document. It must specify the name of a function element specified in the XML document. This element is equivalent to the FUNCTION option for an EXECUTE request. The value is evaluated via Python to a string. This element is optional.
• job-function-args - specifies arguments to pass to the function element called to start the job, overriding any arguments for the defaultcall element, if specified, in the XML document. This element is equivalent to the ARGS option for an EXECUTE request. This element is optional and has the following optional attribute:
  • eval - specifies whether the value is to be evaluated by Python in the parent job. The default is false (eval="0").

• job-script - specifies Python code to be executed. This element is equivalent to the SCRIPT option for an EXECUTE request. Multiple job-script elements may be specified for a job. This element has the following optional attribute:
  • eval - specifies whether the value is to be evaluated by Python in the parent job. The default is false (eval="0").

• job-scriptfile (or job-scriptfiles) - specifies the fully qualified name of a file containing Python code to be executed, or a list of file names containing Python code to be executed. The value must evaluate via Python to a string or a list of strings. This element is equivalent to the SCRIPTFILE option for a STAX EXECUTE command.

  Specifying only one script file could look like either:

  'C:/stax/scriptfiles/scriptfile1.py'   or    ['C:/stax/scriptfiles/scriptfile1.py']
  

  Specifying a list containing three script files could look like:

  ['C:/stax/scriptfiles/scriptfile1.py', 'C:/stax/scriptfiles/scriptfile2.py', 'C:/stax/scriptfiles/scriptfile3.py']
  

  The job-scriptfile element has the following optional attribute:
  • machine - specifies the name of the machine where the script file(s) are located. If not specified, it defaults to Python variable STAXJobScriptFileMachine. This attribute is equivalent to the SCRIPTFILEMACHINE option for an EXECUTE request.
• job-action - specifies a task which will be executed after the sub-job has started execution. This task will be executed in parallel with the sub-job via a new STAX-Thread. The task will be able to use the variable STAXSubJobID to obtain the sub-job's job ID in order to interact with the sub-job, if desired. If the sub-job completes before the task completes, the sub-job will remain in a non-complete state until the task completes. If the sub-job cannot start execution, the job-action task is not executed. This element is optional, but if specified, it must be the last element in the <job> element.

  Note: To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section.

• WAIT
• HOLD
• TEST

Usage:

  <job name="'Job 2'" monitor="1">
    <job-file>'C:/stax/xml/myJob2.xml'</job-file>
  </job>

  EXECUTE FILE /tests/testB.xml MACHINE myMachine JOBNAME "Test B" CLEARLOGS
          FUNCTION Main ARGS "[1, 'server1']" SCRIPTFILEMACHINE myMachine
          SCRIPTFILE /tests/testB1.py SCRIPTFILE /tests/testB2.py
          SCRIPT "MachineList = ['machA', 'machB'] SCRIPT "maxTime = '1h'"
          WAIT RETURNRESULT

<job name="'Test B'" clearlogs="'Enabled'">
  <job-file machine="'myMachine'">'/tests/testB.xml'</job-file>
  <job-function>'Main'</job-function>
  <job-function-args>[1, 'server1']</job-function-args>
  <job-scriptfiles machine="'myMachine'">['/tests/testB1.py', '/tests/testB2.py']</job-scriptfiles>
  <job-script>machineList = ['machA', 'machB']<job-script>
  <job-script>maxTime = '1h'</job-script>
  <job-action>
    <log>'Started sub-job %s' % (STAXSubJobID)</log>
  </job-action>
</job>

<if expr="RC == 0">
  <log message="1">
    'Sub-job %s completed.  Status: %s  Result: %s' % (STAXSubJobID, STAXSubJobStatus, STAXResult)
  </log>
  <else>
    <log message="1" level="'Error'">
      'Sub-job could not be started. RC: %s  Result: %s' % (RC, STAFResult)
    </log>
  </else>
</if>

  EXECUTE FILE C:/tests/Scenario01.xml MACHINE myMachine JOBNAME "Scenario 01"
          CLEARLOGS Enabled LOGTCELAPSEDTIME Enabled LOGTCNUMSTARTS Enabled
          LOGTCSTARTSTOP Enabled PYTHONOUTPUT JobUserLogAndMsg PYTHONLOGLEVEL User1

<job name="'Scenario 01'" clearlogs="'Enabled'"
     logtcelapsedtime="'Enabled'" logtcnumstarts="'Enabled'" logtcstartstop="'Enabled'"
     pythonoutput="'JobUserLogAndMsg'" pythonloglevel="'User'">
  <job-file machine="'myMachine'">'C:/tests/Scenario01.xml'</job-file>
</job>

nop: Perform No Operation

Usage:

<if expr="RC == 0">
  <nop/>
  <else>
    <call function="'ErrorRoutine'"/>
  </else>
</if>

Sequential Execution

sequence: Run Tasks In Sequence

Usage:

<sequence>

  <script>server1 = "machine1.test.austin.ibm.com"</script>

  <stafcmd>
    ...
  </stafcmd>

  <process> 
    ...  
  </process>

  <call function="'VerifyRC'"/>

</sequence>

Parallel Execution

parallel: Run Tasks In Parallel

Note: To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section.

Usage:

<parallel>

  <stafcmd>
    ...
  </stafcmd>

  <process> 
    ...  
  </process>

  <call function="'VerifyRC'"/>

</parallel>

paralleliterate: Run a Task for Each Entry in a List in Parallel

The paralleliterate element contains a single task element.  The paralleliterate element performs the task for each value in a list. The iterations of the contained task element are executed in parallel (unlike the iterate element whose tasks are performed serially).  Each iteration will be executed on a separate STAX-Thread and existing variables are cloned for each thread.  The paralleliterate element is considered to be complete when all its iterations of the task element have completed.

Note: To create a global variable that can be accessed across STAX-Threads, use the STAXGlobal class described in "STAXGlobal Class" section.

The paralleliterate element has the following attributes:

• var - is the name of the variable which will contain the current item in the list/tuple being iterated. It is a literal and is required.
• in - is the list to be iterated. It is evaluated via Python and must evaluate to be a list or tuple. It is required. Note that the list may be assigned in many ways. Here are some examples of in attribute assignments:
• the name of the variable that is a list or tuple: in="machList"
• a literal list: in="['machA','machB','machC']"
• a literal tuple: in="('testA','testB')"
• a slice of a list/tuple: in="machList[1:]"
• a concatenation of lists/tuples: in="machList1 + ['machD','machE']"
• indexvar - is the name of a variable which will contain the index of the current item in the list/tuple being iterated. It is a literal and is optional. Note that the index for the first element in the list/tuple is 0.

Usage:

<script>machList = ['machA','machB','machC','machD']</script>
<paralleliterate var="machName" in="machList">
  <process>
    <location>machName</location>
    <command>'ProcessA'</command>
  </process>
</paralleliterate>

<script>
  machineList = ['machA', 'machB', 'machC' ]
  gPingFailList = STAXGlobal([])
</script>

<paralleliterate var="machName" in="machineList">
  <sequence>

    <stafcmd>
      <location>machName</location>
      <service>'PING'</service>
      <request>'PING'</request>
    </stafcmd>

    <if expr="RC != 0">
      <script>gPingFailList.append(machName)</script>
    </if>

  </sequence>
</paralleliterate>

<if expr="len(gPingFailList) != 0">
  <message>
    'Could not ping the following machines: %s' % (gPingFailList.get())
  </message>
</if>

Functions

function: Define a Named Task

• <function> creates a function object and assigns it to a name
  The function element creates a function object and assigns it to a name. The function name becomes a reference to the function object. There are really two sides to the function picture: a definition (the function element that creates a function) and a call (a call element that tells the STAX Job to run the function).

• <return> sends a result object back to the caller
  When a function is called, the caller stops until the function finishes its work and returns control to the caller. Functions that compute a value send it back to the caller with a return element. The return element can send back any sort of object, including multiple values.

• Scope determines how variables are to be assigned
  By default, all variables assigned in a function are global to the job's current STAX-Thread. However, you can assign a local scope to a function such that all names assigned in a function are local to that function and exist only while the function runs. Functions defined with a local scope provide a nested namespace, which contains a copy of variables in the caller's scope and which localizes any new variables created or changes to existing variables.

• STAXGlobal class provides the ability to create truly global variables
  An exception to the above scoping rules are variables that are instances of the STAXGlobal class. A STAXGlobal class is a Python class which STAX provides as a wrapper to provide for the creation of truly global variables, even across STAX-Threads and when used in functions declared with a local scope. See the STAXGlobal Class section for more information on how to create and use STAXGlobal variables.

The function element defines a named task and contains a single task element.  A function element may only be defined within the root stax element.

The first function called when a job is started is determined by the defaultcall element or by the FUNCTION parameter of an EXECUTE request. Functions are called within a job definition file using the call, call-with-list, or call-with-map elements.

The function element has the following attributes:

• name - is the name of the function. It is required. No two function elements may have the same name. It is a literal. It cannot contain a variable as it is not evaluated via Python. It must be a proper XML name which means it must start with a letter, an underscore, or a colon. The next characters may be letters, digits, underscores, hyphens, periods, and colons (but no whitespace).

• requires - is used with the <import> element and specifies other functions, separated by a space, in the same job that must be imported along with the specified function. This allows the function's users to only import the function itself, without having to worry about any other functions it may call. This attribute is optional.

• scope - specifies the scope of the function. It is a literal and, if specified, must be set to either global or local. It is optional and the default is global.
  • global - the function uses the same namespace so that the effects of variables defined/changed inside the function are global (within the same STAX-Thread).

  • local - the function provides a nested namespace which localizes the variables it uses. All variables assigned in a function are local to that function and exist only while the function runs. Variables previously defined in other functions with a global scope are still visible, however, any changes to these variables or new variables created are not visible to the caller after the function completes, unless the variable is an instance of the STAXGlobal class. Changes to STAXGlobal variables persist after a function completes.

The function element can also optionally contain the following elements, in the order listed, before the task element:

• function-prolog element - Contains a textual description of the function that can be used when transforming a STAX XML document to a Function Description document in HTML. This information will be placed before the function argument table in the Function Description document in HTML. This element replaces the deprecated function-description element.

  Note: This information is not used by STAX in any way and is completely ignored. In particular, this value is never passed to the Python interpreter, and thus, it should be a literal, not a quoted string. If you want to use standard HTML markup such as <p>, <b>, and <ol> in the description, then enclose the text in a CDATA section.

• function-epilog element - Contains a textual description of the function that can be used when transforming a STAX XML document to a Function Description document in HTML. This information will be placed after the function argument table in the Function Description document in HTML.

  Note: This information is not used by STAX in any way and is completely ignored. In particular, this value is never passed to the Python interpreter, and thus, it should be a literal, not a quoted string. If you want to use standard HTML markup such as <p>, <b>, and <ol> in the description, then enclose the text in a CDATA section.

• One of the following elements can be specified to define formal function arguments. Defining arguments can help prevent unintended namespace collisions and allows STAX to detect argument validation errors when calling functions at runtime.
  • function-no-args - is an empty element that specifies that the function does not allow any arguments to be passed to it.

  • function-single-arg - contains either a <function-required-arg>, <function-optional-arg>, or a <function-arg-def> element.

  • function-list-args - specifies a list of arguments. This element can contain zero or more <function-required-arg> elements, followed by zero or more <function-optional-arg elements (but must contain at least one of these arguments), followed by an optional <function-other-args> element, or it can contain one or more <function-arg-def> elements. Note, the order of the arguments is important. All <function-required-args> must precede all <function-optional-args>, and the <function-other-args> element must be last (if present).

  • function-map-args - specifies a map of arguments (recorded as name/value pairs). This element can contain any combination of one or more <function-required-arg> and <function-optional-arg> elements, followed by an optional <function-other-args> element, or it can contain one or more <function-arg-def> elements.. Note that the order of the <function-required-arg> and <function-optional-arg> elements is not relevant, unless an argument's default value specifies another argument's value. However, the <function-other-args> element must be specified last (if present).

  If more arguments are passed to the function when called than are defined (assuming a <function-other-args> element, or a <function-arg def> with a "type" attribute set to "other", is not specified) or if not all required arguments are passed to the function when called, a STAXFunctionArgValidate signal is raised to indicate the failure and the function is not executed.

• function-required-arg - defines an argument that must be passed when calling a function. It may optionally contain a description for the argument. This element has the following attribute:
  • name - is the name of the argument as it will appear inside the function. It is a literal and is required.

• function-optional-arg - defines an argument that may optionally be passed when calling a function. It may optionally contain a description for the argument. This element has the following attributes:
  • name - is the name of the argument as it will appear inside the function. It is a literal and is required.
  • default - is the default value for the argument. Its value is evaluated via Python. It is optional, and defaults to the special Python object None. If an optional argument is not provided when calling a function, its default value is used.

• function-other-args - defines the name of a list (if defined within a <function-list-args> element) or a map (if defined within a <function-map-args> element) which will contain any additional arguments passed when calling a function. If additional arguments are not provided when calling a function, its value is either an empty list or an empty map, depending on whether it was defined within a <function-list-args> element or a <function-map-args> element, respectively. It may optionally contain a description for the argument. The <function-other-args> element has the following attribute:
  • name - is the name of the argument list or map as it will appear inside the function. It is a literal and is required.

• function-arg-def - defines an argument which can contain private data, as well as other user-defined properties. This element has the following attributes:
  • name - is the name of the argument as it will appear inside the function. It is a literal and is required.
  • type - is the type of the argument. It is a literal and is optional. The allowed values are "required", "optional", and "other". The default value is "required".
  • default - is the default value for the argument. Its value is evaluated via Python. It is optional, and defaults to the special Python object None. If an optional argument is not provided when calling a function, its default value is used.
  Note: When using <function-arg-def> elements to define arguments within a <function-list-args> element, the order of the arguments is important. All arguments with type "required" must precede all arguments with type "optional", and the argument with type "other" must be specified last (if present).
  Note: When using <function-arg-def> elements to define arguments within a <function-maps-args> element, the order of the arguments with types "required" and "optional" is not relevant, unless an argument's default value specifies another argument's value. However, the argument with type "other" must be specified last (if present).

A function that does not define its arguments is implicitly defined as:

<function-single-arg>
  <function-optional-arg name="STAXArg" default="None"/>
<function-single-arg>

The function-arg-def element can also optionally contain the following elements, in the order listed:

• function-arg-description element - Contains a description of the argument. This information, along with the values of the function-prolog element (or the deprecated function-description element) and the function-epilog element, can be used in conjunction with an XSLT stylesheet to generate a nicely formatted HTML file documentating functions and their associated arguments specified in a STAX job. Refer to the "Generating STAX Function Documentation" section for more information on how to generate HTML documentation for your STAX functions.

• function-arg-private element - Indicates that the argument contains private data. This element is optional and is an empty element.

• function-arg-property element - Allows you to specify properties for the argument. You may have multiple <function-arg-property> elements.

The function-arg-property element has the following required attributes:

• name - is the name of the property.

• value - is the value of the property.

The function-arg-property element can also optionally contain the following elements, in the order listed:

• function-arg-property-description element - Contains a description of the argument property. This information, along with the attributes of the function-property-data element can be used in conjunction with an XSLT stylesheet to generate a nicely formatted HTML file documentating function arguments and their associated properties specified in a STAX job. Refer to the "Generating STAX Function Documentation" section for more information on how to generate HTML documentation for your STAX functions.

• function-arg-property-data element - Contains data associated with the argument property. You may have multiple <function-arg-property-data> elements. A <function-arg-property> element can contain nested <function-arg-property-data> elements, which can be self-nested. This allows you to define an enumerated list of values for a function argument.

The function-arg-property-data element has the following required attributes:

• type - is the type of the property data.

• value - is the value of the property data.

Usage:

Goal: Define a simple function containing a sequence element (which can then contain any number of other elements).

<function name="FunctionA">
  <sequence>
    ...
  </sequence>
</function>

<function name="FunctionB" requires="FunctionC FunctionD">
  <sequence>
    ...
    <call function="'FunctionC'"/>
    ...
    <call function="'FunctionD'"/>
    ...
  </sequence>
</function>

Before Bar: localVar=[1, 2], globalVar=[1, 2]
After  Bar: localVar=[1, 2], globalVar=[1, 2, 3]

<stax>

  <script>
    localVar = [1, 2]
    globalVar = STAXGlobal([1, 2])
  </script>

  <defaultcall function="Main"/>

  <function name="Main" scope="local">

    <sequence>

      <message>
        'Before Bar: localVar=%s, globalVar=%s' % (localVar, globalVar)
      </message>

      <call function="'Bar'"/>

      <message>
        'After  Bar: localVar=%s, globalVar=%s' % (localVar, globalVar)
      </message>

    </sequence>

  </function>

  <function name="Bar" scope="local">

    <script>
      localVar.append(3)
      globalVar.append(3)
    </script>

  </function>

</stax>

  <function name="NoArgsFunction">
    <function-no-args/>

    <sequence>
      ...
    </sequence>

  </function>

  <function name="OneRequiredArgFunction" scope="local">

    <function-single-arg>
      <function-required-arg name="duration"/>
    </function-single-arg>

    <timer duration="duration">
      <loop>
        ...
      </loop>
    </timer>

  </function>

  This function could be called in any of the following ways with the same result:

  <call function="'OneRequiredArgFunction'">'24h'</call>

  <call-with-list function="'OneRequiredArgFunction'">
    <call-list-arg>'24h'</call-list-arg>
  </call-with-list>

  <function name="Check-STAFCmd-RC" scope="local">

    <function-prolog>
      Checks if a STAFCmd was successful and updates testcase status
    </function-prolog>

    <function-map-args>

      <function-required-arg name="returnCode">
        Return Code from a STAF Command
      </function-required-arg>

      <function-required-arg name="result">
        Result from a STAF Command
      </function-required-arg>

      <function-optional-arg name="msg" default="''">
        Message to display if an error occurs
      </function-optional-arg>

    </function-map-args>

    <if expr="RC == 0">
      <tcstatus result="'pass'"/>
      <else>
        <tcstatus result="'fail'">
          '%s; RC=%s, Result=%s' % (msg, returnCode, result)
        </tcstatus>
      </else>
    </if>

  </function>

  This function could be called in any of the following ways with the same result:

  <call function="'Check-STAFCmd-RC'">
    { 'returnCode': RC, 'result': STAFResult, 'msg': 'This is the error message' }
  </call>

  <call-with-map function="'Check-STAFCmd-RC'">
    <call-map-arg name="'result'">STAFResult</call-map-arg>
    <call-map-arg name="'returnCode'">RC</call-map-arg>
    <call-map-arg name="'msg'">'This is the error message'<call-map-arg>
  </call-with-map>

<function name="RunTests" scope="local">

    <function-list-args>
      <function-required-arg name="machName"/>
      <function-other-args name="testList"/>
    </function-list-args>

    <sequence>

      <script>
        testsRun = STAXGlobal([0])   # Number of tests run
      </script>

      <paralleliterate var="testName" in="testList">

        <sequence>

          <process>
            <location>machName</location>
            <command mode="'shell'">testName</command>
          </process>

          <script>testsRun[0] += 1</script>

        </sequence>

      </paralleliterate>

      <message>'Ran %s tests' % testsRun[0]</message>

    </sequence>

  </function>

  This function could be called in any of the following ways with the same result:

  <call function="'RunTests'">
    'local', 'ping machineA', 'dir C:\ > C:\out'
  </call>

  <call function="'RunTests'">
    [ 'local', 'ping machineA', 'dir C:\ > C:\out' ]
  </call>

  <call-with-list function="'RunTests'">
    <call-list-arg>'local'</call-list-arg>
    <call-list-arg>'ping machineA'</call-list-arg>
    <call-list-arg>'dir C:\ > C:\out'<call-list-arg>
  </call-with-list>

  <function name="STAXUtilLogAndMsg" scope="local">

    <function-prolog>
      <![CDATA[
      <p>
        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.
      </p>
      ]]>
    </function-prolog>

    <function-epilog>
      <![CDATA[
      <h4>Returns:</h4>
      <p>Nothing.  That is, STAXResult = None.</p>
      <h4>Example:</h4>
      <pre>
  <call function="'STAXUtilLogAndMsg'">'Here is my message'</call></pre>
      ]]>
    </function-epilog>

    <function-list-args>

      <function-required-arg name="message">
        The message you want to log in the STAX Job User log and to send to
        the STAX Monitor.
      </function-required-arg>

      <function-optional-arg name="level" default="'info'">
        The level of the message to be logged in the STAX Job User log.
      </function-optional-arg>

    </function-list-args>

    <sequence>

      <message>message</message>

      <log level="level">message</log>

    </sequence>

  </function>

  <function name="RunCommand">
  
    <function-map-args>
      
      <function-arg-def name="command">
        <function-arg-description>
           A command to execute
        </function-arg-description>
      </function-arg-def>

      <function-arg-def name="user" type="optional" default="'anonymous'">
        <function-arg-description>
          The user id to run the command under
        </function-arg-description>
      </function-arg-def>

      <function-arg-def name="password" type="optional">
        <function-arg-description>
          The password for the user id
        </function-arg-description>
        <function-arg-private/>
      </function-arg-def>

      <function-arg-def name="numTimes" type="optional" default="1">
        <function-arg-description>
          The number of times to run the command
        </function-arg-description>
        <function-arg-property name="type" value="int"/>
      </function-arg-def>