STAF V3 User's Guide

Software Testing Automation Framework (STAF) User's Guide
Version 3.4.18

30 Jun 2014


Table of Contents

1.0 Overview

  • 1.1 Requirements
  • 2.0 Concepts

  • 2.1 Handles
  • 2.2 Services
  • 2.3 Workloads
  • 2.4 Variables
  • 2.5 Security
  • 2.6 Queues
  • 2.7 Strings and Codepages
  • 3.0 Installation

    4.0 Configuration

  • 4.1 Comments
  • 4.2 Machine Nickname
  • 4.3 Network Interfaces
  • 4.4 Service Registration
  • 4.5 Service Loader Registration
  • 4.6 Authenticator Registration
  • 4.7 Operational parameters
  • 4.8 Variables
  • 4.9 Trust
  • 4.10 Start/Shutdown Notifications
  • 4.11 Tracing
  • 4.12 Configuration File Examples
  • 4.13 Tuning
  • 4.14 Data Directory Structure
  • 5.0 Commands

  • 5.1 STAFProc
  • 5.2 STAF
  • 6.0 API Reference

  • 6.1 Marshalling Structured Data
  • 6.2 C
  • 6.3 C++
  • 6.4 Rexx
  • 6.5 Java
  • 6.6 Perl
  • 6.7 Python
  • 6.8 Tcl
  • 7.0 Services overview

  • 7.1 General Service Syntax
  • 7.2 Option Value Formats
  • 7.3 Private Data
  • 7.4 Variable Resolution
  • 7.5 Service Result Definition
  • 7.6 Service Help
  • 7.7 Service list
  • 8.0 Service reference

  • 8.1 Config Service
  • 8.2 Delay Service
  • 8.3 Diagnostics (DIAG) Service
  • 8.4 Echo Service
  • 8.5 File System (FS) Service
  • 8.6 Handle Service
  • 8.7 Help Service
  • 8.8 LifeCycle Service
  • 8.9 Log Service
  • 8.10 Misc Service
  • 8.11 Monitor Service
  • 8.12 Ping Service
  • 8.13 Process Service
  • 8.14 Queue Service
  • 8.15 Resource Pool (ResPool) Service
  • 8.16 Semaphore (SEM) Service
  • 8.17 Service Service
  • 8.18 Shutdown Service
  • 8.19 Trace Service
  • 8.20 Trust Service
  • 8.21 Variable (VAR) Service
  • 8.22 Zip Service
  • 9.0 Log Utilities

  • 9.1 STAF Log Viewer Class
  • 9.2 JVM Log Viewer Class
  • 9.3 STAF Log Formatter Class
  • 9.4 Format Log Utility
  • Appendix A. API Return Codes

    Appendix B. Service Command Reference

    Appendix C. Samples Descriptions

    Appendix D. Code Samples and Snipets

  • D.1 Java
  • D.2 Rexx
  • D.3 C
  • D.4 C++
  • Index

    End Of Document


    1.0 Overview

    As its name indicates, STAF is a framework. It was designed to promote reuse and extensibility. It is intended to make software testing easier, and specifically to make it easier to automate software testing. This includes creating automated testcases, managing and automating the test environment, creating execution harnesses (i.e., applications which schedule and/or execute work on test systems), etc.

    STAF externalizes its capabilities through services. A service provides a focused set of functionality, such as, Logging, Process Invocation, etc. STAFProc is the process that runs on a machine, called a STAF Client, which accepts requests and routes them to the appropriate service. These requests may come from the local machine or from another STAF Client. Thus, STAF works in a peer environment, where machines may make requests of services on other machines.

    STAF was designed with the following points in mind.


    1.1 Requirements

    1.1.1 Operating System

    STAF is supported on the following operating systems


    2.0 Concepts


    2.1 Handles

    A handle is a unique identifier, representing a given process. This handle is used when submitting requests to STAF. This handle, combined with the machine name, uniquely identifies a particular process in the STAF Environment. It is this combination of machine/handle that allows services to track requests from multiple processes on different machines.

    In order to submit service requests to STAF, a process must have a handle. Thus, the first thing a process should do is register with STAF to obtain a handle. Other data tied to this handle is the following:

    Before a process exits it should unregister with STAF to free up any resources used by that handle.

    Note: Handle 1 is always allocated to the STAF Process itself. The name associated with this handle is STAF_Process.

    If STAFProc is shutdown on a machine (or the machine is rebooted), STAF handles for that machine are deleted.

    The SEM and RESPOOL services perform garbage collection for handles that have been deleted by default, unless you specified no garbage collection when requesting a mutex semaphore or resource pool entry. Performing garbage collection means that when a handle is deleted, any mutex semaphores or resource pool entries owned by the handle will be released and any pending requests submitted by the handle will be removed.


    2.2 Services

    Services are what provide all the capability in STAF. Services may be internal services, in which case, the executable code for the service resides within STAFProc. Services may also be external services, in which case, the executable code for the service resides outside of STAFProc, for example, in a Java routine.

    Services are known by their name, such as PROCESS or LOG. Internal services are always available and have a fixed name. External services must be registered, and the name by which they are known is specified when they are registered. If an external service is not registered with STAF, then the service is not available on that STAF Client.

    Services may also be delegated to another STAF Client. In this case, when a request is made for the service on the local STAF Client, it is automatically forwarded to the machine to which this service has been delegated. For example, a testcase may request the local machine to log some information via the LOG service. If the LOG service has been delegated to another machine, the LOG request will actually be handled by the machine to which logging has been delegated. In this way, all logs could be conveniently stored on one system, without the testcases needing to explicitly send their LOG requests to the common system. In a similar manner, if a service were only available on a specific operating system, then all testcases could assume that the service was available locally, when, in fact, the service was being delegated to the machine running the required operating system.

    Note: Internal services may not be delegated.

    External services and delegated services are both registered in the STAF Configuration File. External services also may be dynamically added (registered) or removed (unregistered and terminated) via the SERVICE service (see 8.17, "Service Service").

    Service loaders are external services whose purpose is to load services on-demand. They allow services to be loaded only when they have been requested, so they don't take up memory until needed. They also allow dynamic service registration when a request is made so that you don't have to change the STAF configuration file to register a service.

    When a request is encountered for a service that doesn't exist, STAF will call each service loader, in the order they were configured, until the service exists or we run out of service loaders. If we run out of service loaders, then the standard RC 2 (DoesNotExist) will be returned indicating that the service is not registered. Otherwise, the request will be sent to the newly added service. If a service is currently being attempted to be loaded by a service loader, any requests submitted to the service while it's being loaded will wait until the attempt to load the service has completed. If the service was loaded, the request will be sent to the newly added service. If the service wasn't loaded, RC 2 (DoesNotExist) will be returned indicating that the service is not registered.

    STAF ships two service loader services:

    1. A default service loader service called STAFDSLS which is written in C++ and can dynamically load the Log, Zip, Monitor, and ResPool C++ services. This service loader is configured automatically in the default STAF.cfg file. See section 4.5.2, "Default Service Loader Service (STAFDSLS)" for more information about the default service loader service.

    2. A HTTP service loader service called STAFHTTPSLS which is written in Java and can dynamically load any STAF services written in Java. It can download the jar file for a STAF Java service (or a zip file that contains the jar file) from a web server or from a file on the local machine. It uses a configuration file to determine what services it can load. This service loader service can reduce the maintenance for managing STAF Java services. See section 4.5.3, "HTTP Service Loader Service (STAFHTTPSLS)" for more information about the HTTP service loader service.

    Authenticators are special external services whose purpose is to authenticate users in order to provide user level trust, which can be used in addition (or instead of) machine level trust. An Authenticator is a special service that accepts an authenticate request. As a user, you cannot directly submit a request to an authenticator service. Authenticators are accessed indirectly via the Handle service.

    Authenticators can only be registered in the STAF configuration file -- they cannot be dynamically registered. One or more Authenticators can be registered. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter. If you want to authenticate across systems, you must register the Authenticator on each system using the same name (case-insensitive).


    2.3 Workloads

    A workload is a set of processes running on a set of machines. A workload may be as simple as a single process running on a single machine, or it may be as complex as multiple processes on multiple machines coordinating together to perform a larger complex task. STAF was designed to help the creation and automation of workloads of all sizes.


    2.4 Variables

    STAF provides a means to store and retrieve variables. These variables may be used for any purpose the tester desires, such as storing testcase configuration parameters. These variables provide two main capabilities to testcase writers. One, they provide a standard means by which to store configuration data, i.e., each tester doesn't have to figure out how to store and retrieve said configuration data. Two, these variables may be changed dynamically. For example, if a testcase queries the WebServer variable before sending a request off to the web server, and that web server goes down, the WebServer variable can be dynamically changed by the tester to refer to a different web server, and the testcase can continue execution. Note how STAF allows the variable's value to be changed outside of the scope of the running testcase, thus allowing the testcase to continue execution without needing to be stopped and restarted.

    STAF maintains a "system" variable pool that is common to all the processes on a given STAF Client. STAF also maintains a "shared" variable pool which is also system-wide, but which will be sent across the network and used in variable resolution on remote systems. In addition, each process/handle has its own variable pool. By default, the values of variables in a process' variable pool override the values of variables in the system and shared variable pools. However, the process may override this behavior when asking for the value of a variable. Basically, as part of every remote request, the originating handle and system shared variable pools are sent across the wire. These pools are stored only for the duration of the request for use in variable resolution.

    The following system variables are predefined:

    2.4.1 The Basics of Variable References

    To substitute a variable's value, write the name of the variable in curly braces: "{STAF/Config/OS/Name}" is a valid reference to the variable STAF/Config/OS/Name. Assuming STAF/Config/OS/Name=Win2000, string "Operating system is {STAF/Config/OS/Name}" resolves to "Operating system is Win2000".

    Variable references can be used in many places when submitting a STAF request. For example:

    See section 8.21, "Variable (VAR) Service" for more information on setting and resolving variables.


    2.5 Security

    Security in STAF can be defined at the machine level and/or the user level. In other words, you grant access to machines and/or to userids. Access in STAF is granted by specifying a certain trust level for a machine or user, where trust level 0 indicates no access and trust level 5 indicates all access. Each service in STAF defines what trust level is required in order to use the various functions the service provides.

    A basic description of each level follows

    In order to use user trust security in STAF, you must have at least one authenticator registered.

    Note: The local machine can be granted a trust level by specifying interface "local" and a system identifier of "local".

    User authentication overrides machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.


    2.6 Queues

    Each handle in STAF has a priority queue associated with it. This queue is used to accept/retrieve messages from other processes/machines. Each message in the queue has the following data associated with it.

    STAF allows you to register to receive notifications for certain events, such as STAF starting and shutting down. These events will appear in the queue of the requesting process. They will reveal the originating handle as handle 1 of the originating machine, which is the reserved STAF Process handle.


    2.7 Strings and Codepages

    The requests submitted to STAF and the results received from STAF are all strings. These strings may contain any arbitrary set of characters, including the NULL (i.e., 0) character. When working in an environment with a heterogeneous set of codepages, STAF will translate the request and result strings from and to the necessary codepages. This ensures that the request and result strings are not misinterpreted by the receiver.

    In general, when using STAF services, there shouldn't be any round trip problems. "Round trip" in this context means when all requests are originating from the same system, even if the requests are sent to, and the data is stored on, a system with a different codepage. However, if you send, for example, a request to log data containing Japanese codepage specific characters to any system and then query the log from a system using a US English codepage, you won't get the "correct" data, as that is not a valid "round trip".

    Note: All STAF generated strings are composed of only ASCII-7 characters and will safely survive the translation from/to different codepages.

    2.7.1 Windows Codepage Translation Anomalies

    If you need to specify non-ASCII characters in a request, then you need to be aware of some anomalies if your target system is a Windows system that isn't using an English codepage and whose ANSI codepage (ACP) identifier is different from the OEM codepage (OEMCP) identifier. The system locale determines which codepages are defaults for the Windows system. However, some European locales such as French and German set different values for the ACP and OEMCP. By default, STAF uses the OEM codepage when doing codepage translation. But, depending on where the data is input, it may be necessary to tell STAF to use the ANSI codepage. The ANSI codepage is used in the window manager and graphics device interface and by many applications. However, the Windows command line and bat files use the OEM codepage as they are interpreted by cmd.exe. You can use CHCP to display or change the codepage used by the command line. Note that these anomalies occur only on Windows systems.

    To avoid these Windows codepage anomalies, you may need to change the codepage used by STAF using one of these methods:

    Note: To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage. For example:

        STAF testmach1 VAR RESOLVE STRING {STAF/Config/CodePage}
    

    2.7.2 Codepage Converter Error on a FS GET FILE Request

    On a GET FILE request to the FS service (or on another service request that submits a GET FILE request to the FS service like the STAX service does on an EXECUTE FILE request), RC 39 (Converter Error) is returned if the file contains data that is not valid in the codepage that STAF is using. To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage as discussed in the previous section.

    To resolve an RC 39 (Converter Error) on a GET FILE request to the FS service, either:


    3.0 Installation

    The STAF Installation Guide (http://staf.sourceforge.net/current/STAFInstall.pdf) has detailed information on how to install STAF.


    4.0 Configuration

    STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF Configuration File is read and processed line by line. Whitespace at the front of the line is removed before processing. Blank lines, or lines containing only whitespace are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line. The maximum length for a line in the STAF Configuration File is 2048 characters. The various configuration statements are described in the following sections.

    You may use variables for all the values of configuration statement options, with the exception of the SET VAR configuration statement itself. However, these variables must be either predefined STAF variables (see 2.4, "Variables") or be previously defined in the STAF Configuration File via the SET VAR configuration statement (see below).


    4.1 Comments

    4.1.1 Description

    You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.

    Examples

    # This is a comment line
    

    4.2 Machine Nickname

    4.2.1 Description

    You may specify a nickname for your machine using the MACHINENICKNAME configuration statement.

    This allows you to override the machine nickname which is set to the value of the STAF/Config/Machine system variable by default. This primarily affects the data stored by services such as the Log and Monitor services, which store data based on the machine from which it came by using the STAF/Config/MachineNickname system variable as part of the directory path when creating logs and monitor data. By allowing the STAF/Config/MachineNickname system variable to be overridden, it allows you to better manage your data.

    The machine nickname is not used to communicate with other systems and does not have any effect on trust.

    This option is used in both connected and disconnected modes (e.g. disconnected mode is when you are not using a network interface).

    Syntax

    MACHINENICKNAME <Nickname>
    

    <Nickname> is the nickname you wish to use for your machine. It is case sensitive.

    Examples

    MACHINENICKNAME testmachine1
    MACHINENICKNAME JohnDoe
    

    4.3 Network Interfaces

    4.3.1 Description

    You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement. The INTERFACE configuration statement registers connection providers (also called network interfaces, or interfaces for short).

    Notes:

    1. Currently, STAF provides two network interfaces, secure TCP/IP and non-secure TCP/IP (except a secure TCP/IP interface is not yet provided for z/OS). The default STAF configuration file configures a secure ssl interface as the default interface and also configures a non-secure tcp interface (except on z/OS where only a non-secure tcp interface is configured). STAF also allows you to plug in network interfaces (aka connection providers) so that you can create your own connection provider which can communicate via any mechanism you choose (e.g. a Serial Line, NetBIOS, or SNA). Connection provider interfaces are C/C++ based so they are platform specific. However, we haven't provided any documentation yet on how to do this.

    2. An interface named local is also provided with STAF. Requests coming from the local system will appear as though they came from an interface named "local" and a system identifier of "local".

    Syntax

    INTERFACE <Name> LIBRARY <Implementation Library> [OPTION <Name[=value]>]...
    

    <Name> is the name by which this network interface (aka Connection Provider) will be known on this machine.

    LIBRARY is the name of the shared library / DLL which implements the network interface (aka Connection Provider). STAF provides one implementation library called STAFTCP which provides support for both secure and non-secure TCP/IP communcation.

    OPTION specifies a configuration option that will be passed on to the shared library / DLL which implements the connection provider. You may specify multiple OPTIONs for a given connection provider. See 4.3.2, "STAFTCP Connection Provider" for acceptable options for the STAFTCP shared library / DLL.

    Examples

    INTERFACE ssl    LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550
    INTERFACE tcp    LIBRARY STAFTCP OPTION SECURE=No  OPTION PORT=6500
    INTERFACE tcp2   LIBRARY STAFTCP 
    INTERFACE tcp3   LIBRARY STAFTCP OPTION PORT=6600
    INTERFACE serial LIBRARY STAFSER
    

    4.3.2 STAFTCP Connection Provider

    The STAFTCP connection provider shared library / DLL supports TCP/IP communication. STAF supports both secure and non-secure TCP/IP communication on most platforms. STAF supports both IPv4 and IPv6. IPv6 is supported in the IPv6 enabled version of STAF.

    Each STAFTCP connection provider configured on a single machine must use a unique port number. To communicate to a remote machine running STAF, your machine and the remote machine must both have a STAFTCP connection provider configured with the same SECURE option value and the same PORT option value. A non-secure STAFTCP connection provider cannot communicate to a secure STAFTCP connection provider. Also, a secure TCP connection provider can only communicate to another secure TCP connection provider if the same certificate is used.

    The STAFTCP connection provider supports the following OPTIONs:

    CONNECTTIMEOUT=<Number> specifies the maximum time in milliseconds to wait for a connection attempt to a remote system to succeed. The default is 5000 (5 seconds). You may need to increase this value if you are consistently receiving return code 16 when trying to communicate with distant STAF systems. Note that the total time to wait for a connection to a remote system to succeed is (CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1)). If using the defaults, the maximum total time to wait for a connection to a remote system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds. The CONNECTATTEMPTS and CONNECTRETRYDELAY values are operational parameters that can be set in the STAF configuration file.

    PORT=<Number> specifies the TCP/IP port on which this connection provider listens for connections. The default port is 6550 if option SECURE=Yes. The default port is 6500 if option SECURE=No. Each STAFTCP connection provider configured on a single machine must use a unique port number.

    PROTOCOL=<IPv4 | IPv6 | IPv4_IPv6> specifies the communication protocol that this connection provider uses. The possible values are IPv4, IPv6, or IPv4_IPv6. When this option is absent, the default is IPv4_IPv6 which indicates to use both IPv4 and IPv6 protocols. This option is only valid for IPv6 enabled versions of STAF.

    SECURE=<Yes | No> specifies whether to use secure or non-secure TCP/IP. Secure TCP/IP uses OpenSSL. This option is not available on z/OS where only non-secure TCP/IP is currently supported. The default is No.

    SSL/CACertificate specifies the fully qualified path to the file containing the STAF CA certificate list used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/CAList.crt which is a list of the default server certificate provided with STAF.

    SSL/ServerCertificate specifies the fully qualified path to the file containing the STAF server certificate used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/STAFDefault.crt which is a self-signed x509 default certificate provided with STAF.

    SSL/ServerKey specifies the fully qualifed path to the file containing the STAF server key used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/STAFDefault.key which is a default server key provided with STAF.

    Examples

    INTERFACE ssl  LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550
    INTERFACE tcp  LIBRARY STAFTCP OPTION SECURE=No  OPTION PORT=6500
    INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6501
    INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6700 OPTION PROTOCOL=IPv6
    INTERFACE tcp4 LIBRARY STAFTCP OPTION CONNECTTIMEOUT=15000
    INTERFACE ssl2 LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6551 \
                   OPTION SSL/CACertificate={STAF/Config/STAFRoot}/bin/MyCAList.crt \
                   OPTION SSL/ServerCertificate={STAF/Config/STAFRoot}/bin/MySTAF.crt \
                   OPTION SSL/ServerKey={STAF/Config/STAFRoot}/bin/MySTAF.key 
    

    4.4 Service Registration

    4.4.1 Description

    External services are registered with the SERVICE configuration statement.

    Syntax

    SERVICE <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
                   [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    or

    SERVICE <Name> DELEGATE <Machine> [TONAME <Remote Service Name>]
    

    <Name> is the name by which this service will be known on this machine.

    LIBRARY is the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, for a Java service, this might be the name of the Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See below for information regarding the JSTAF service proxy library. Otherwise, see the documentation provided by the service proxy library.

    OPTION specifies a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See below for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service during initialization.

    DELEGATE specifies the machine to which to delegate this service. This machine must be running STAF V3.0.0 or later.

    Note: From a trust perspective, the tcp interface names on the "delegated to" service machine and on the machine delegating service requests to it must match or the trust statement for the machine that is delegating service requests must use a wildcard to match any interface.

    TONAME is the name of the service on <Machine> to which the delegated requests will be sent. The default is the same name as specified with <Name>.

    Examples

    SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096"
    SERVICE LOG     LIBRARY STAFLog
    SERVICE STAX    LIBRARY JSTAF  EXECUTE C:\STAF\service\STAX.jar \
                    OPTION J2=-Xmx128m
    SERVICE SAMPLEJ LIBRARY JSTAF  EXECUTE C:\STAF\services\Sample.jar \
                    PARMS {STAF/Config/STAFRoot}\bin\sample.dft
    SERVICE MYLOG   DELEGATE TestSrv1
    SERVICE PAGER   DELEGATE pagesrv.austin.ibm.com
    SERVICE EVENT   DELEGATE EventSrv TONAME DB2EVENT
    SERVICE NOTIFY  LIBRARY Notify PARMS "24 Hours 7 Days"
    SERVICE ZIP     LIBRARY STAFEXECPROXY EXECUTE STAFZip
    

    4.4.2 JSTAF service proxy library

    The library JSTAF acts as a proxy for STAF services implemented in the Java language. The minimum version of Java that JSTAF requires depends on the operating system for which STAF was built:

    Note: JSTAF in a 32-bit version of STAF requires a 32-bit version of Java. Similarly, JSTAF in a 64-bit version of STAF requires a 64-bit version of Java.

    The EXECUTE option for a Java service should specify the fully-qualified name of the jar file that implements the service. The jar file will be automatically added to the class path by JSTAF.

    Note: In versions of STAF prior to 2.4.0, the name of the Java class that implements the service was specified for the EXECUTE option and you had to make sure that the service's class files were in the class path. This is still supported, but this method is deprecated and will be removed in a future version of STAF.

    JSTAF supports the following OPTIONs:

    JVMName=<Name> specifies the name for the JVM you want the Java service to run in. If the JVM does not already exist, it will be created. If no JVMName is specified, then the Java service will run in the default JVM, named STAFJVM1, which is created the first time a Java service is registered with no JVMName specified. This option allows JSTAF to run Java services in different JVMs.

    JVM=<Executable> specifies the name of the desired Java executable. The default is "java". Note, this option is only valid for the first service created with a given JVMName.

    J2=<Java option> specifies one or more arbitrary Java option(s) that should be passed to the JVM. You can find more information on these options by using the command "java" (for standard options) and "java -X" (for non-standard options), or by consulting your Java documentation. Note that -X options can vary depending on which Java implementation (e.g. Oracle Java 7 vs IBM Java 6) you installed. Note, this option is only valid for the first service created with a given JVMName.

    Note: If you are using the HP-UX IA64 64-bit version of STAF, you must specify the -d64 option to the JVM. This can be done by specifying J2=-d64

    MAXLOGS=<Number> specifies the maximum number of log files for the JVM that should be saved. The default is 5. The JVM log files are stored in the {STAF/DataDir}/lang/java/jvm/<JVMName> directory and contain JVM start information such as the date/time when the JVM was started, the JVM executable, and the J2 options used to start the JVM. In addition, it contains any other information logged by the JVM, including any errors that may have occurred while the JVM was running. The current JVM log file is named JVMLog.1 and saved JVM log files, if any, are named JVMLog.2 to JVMLog.<MAXLOGS>. Note, this option is only valid for the first service created with a given JVMName.

    MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the JVM log file(s). The default is 1048576 (1M). This option determines when to create a new JVM log file. When the JVM is started, if the size of a JVM log file exceeds the maximum size specified by this option, a new JVM log file will be created. Note, this option is only valid for the first service created with a given JVMName.

    Note: You can view the JVM log for a Java service that is currently registered using the STAFJVMLogViewer utility. Section 9.2, "JVM Log Viewer Class" provides more information on this utility.

    Examples

    OPTION J2=-verbose:gc
    OPTION "J2=-cp {STAF/Config/BootDrive}/MyJava/Extra.jar{STAF/Config/Sep/Path}{STAF/Env/Classpath}"
    OPTION J2=-Xms128m
    OPTION J2=-Xmx512m
    OPTION J2=-d64
    OPTION "J2=-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=256m"
    OPTION JVMName=MyJVM1
    OPTION JVM=/opt/sunjdk1.4.0/jre/bin/java
    OPTION MAXLOGS=2
    OPTION MAXLOGSIZE=2048
    

    If you wanted to run the STAX Java service in a JVM, called MyJVM1, with a maximum heap size of 1024M, and wanted the Event and EventManager Java services to run in a different JVM, called MyJVM2, with a maximum heap size of 512M, you could specify the following service registration lines in the STAF.cfg file (or dynamically register the services in this order using the specified options).

    SERVICE STAX  LIBRARY JSTAF  EXECUTE C:/STAF/service/STAX.jar \
                  OPTION JVMName=MyJVM1 OPTION J2=-Xmx1024m
    SERVICE Event LIBRARY JSTAF  EXECUTE C:/STAF/service/STAFEvent.jar \
                  OPTION JVMName=MyJVM2 OPTION J2=-Xmx512m
    SERVICE EventManager LIBRARY JSTAF  EXECUTE C:/STAF/services/EventManager.jar \
                  OPTION JVMName=MyJVM2
    

    4.4.3 PLSTAF service proxy library

    The library PLSTAF acts as a proxy for STAF services implemented in the Perl language. PLSTAF is currently supported on Windows (IA32), Linux (IA32), and Mac OS X. On Linux IA32, PLSTAF is currently only supported with Perl 5.8.0.

    The EXECUTE option for a Perl service should specify the name of the .pm file (without the .pm extension) that implements the service.

    PLSTAF supports the following OPTIONs:

    USELIB=<Directory> specifies the directory containing the .pm file that implements the service. You must use the USELIB option unless you have set (prior to starting STAFProc) environment variable PERLLIB to include the directory containing the .pm file that implements the service.

    MAXLOGS=<Number> specifies the maximum number of log files for the Perl interpreter that should be saved. The default is 5. The Perl interpreter log files are stored in the {STAF/DataDir}/lang/perl/<serviceName> directory and contain the Perl interpreter start information such as the date/time when the Perl interpreter was started and the Perl service executable. In addition, it contains any other information logged by the Perl service and interpreter, including any errors that may have occurred while the Perl interpreter was running. The current Perl interpreter log file is named PerlInterpreter.1 and saved Perl interpreter log files, if any, are named PerlInterpreter.2 to PerlInterpreter.<MAXLOGS>.

    MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the Perl interpreter log file(s). The default is 1048576 (1M). This option determines when to create a new Perl interpreter log file. When the Perl interpreter is started, if the size of a Perl interpreter log file exceeds the maximum size specified by this option, a new Perl interpreter log file will be created.

    Note: The PLSTAF service proxy library uses embedded Perl directly within the STAFProc executable. This means that if a Perl service has a fatal error which terminates the Perl interpreter, the STAFProc executable will also be terminated. To prevent this, you can use the STAFEXECPROXY service proxy library when registering a Perl service.

    Note: To configure Perl services, prior to starting STAFProc, environment variable PERLLIB must be set to include the directory containing the PLSTAF.pm and PLSTAFService.pm files (located in the "bin" directory in the STAF installation root directory).

    Note: To configure Perl services, the directory containing the PLSTAF library (PLSTAF.dll on Windows, libPLSTAF.so on Linux, libPLSTAF.dylib on Mac OS X) must be in the operating system's library path (PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on Mac OS X) prior to starting STAFProc.

    Note: When configuring Perl services on Linux with Perl 5.8.0, the directory containing the Perl 5.8.0 libperl.so file must be included in environment variable LD_LIBRARY_PATH prior to starting STAFProc.

    Note: When removing a Perl service (or when shutting down STAF if Perl services had been configured), you may see a message in the STAFProc output similar to: "Perl exited with active threads". This message can be ignored.

    Examples

    SERVICE Device1  LIBRARY PLSTAF EXECUTE DeviceService 
    SERVICE Device2  LIBRARY STAFEXECPROXY EXECUTE DeviceService \
                     OPTION PROXYLIBRARY=PLSTAF
    SERVICE testA    LIBRARY STAFEXECPROXY EXECUTE myTestService \
                     OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=C:\MyServices
    

    4.4.4 STAFEXECPROXY service proxy library

    This library will allow you to execute an external STAF service within a new executable, rather than directly within the STAFProc executable. For example, this library could be used to run the Zip service in a separate executable, or run a Perl service where the Perl interpreter will run in a separate executable.

    Running an external STAF service in a separate executable will ensure that if the service has a fatal error, the error will not kill STAFProc. In addition, this allows monitoring of the external service's system resource utilization, since you can view the utilization for the new executable (otherwise, if the service was running within the STAFProc executable, then the service's resource utilization would be part of the STAFProc resource utilization).

    Note that using the STAFEXECPROXY library will introduce a level of IPC communication for all service requests to the service; rather than STAFProc sending the requests directly to the service, STAFProc will send the request to the STAFEXECPROXY library, which will then send the request to the new executable, which will then send the request to the service (processing the service result will have the same path in reverse). So, for external STAF services where performance is critical, such as the Log and Monitor services, using the STAFEXECPROXY library is not recommended.

    Note that since the JSTAF proxy library already runs the Java STAF service in a new executable (the JVM), using the STAFEXECPROXY library for Java STAF services is not supported (if you attempt to register a Java STAF service using the STAFEXECPROXY library, you will get an RC 27, Service configuration error).

    The EXECUTE option is used to indicate the service library to execute, or if the service will be executed by a proxy library, it will be used to indicate what service executable the proxy library should execute. For example, for the Zip service, "STAFZip" would be used for the EXECUTE value. For a Perl service, which uses the PLSTAF proxy library, the service .pm module would be used for the EXECUTE value.

    STAFEXECPROXY supports the following OPTIONs

        [OPTION PROXYLIBRARY=<ProxyLibrary>]
        [OPTION PROXYENV=<Variable=Value>]...
    
    (note that all other OPTIONs will be passed to the service library / DLL):

    OPTION PROXYLIBRARY=<ProxyLibrary> is used to indicate the proxy library to use for the external service. For example, you would use OPTION PROXYLIBRARY=PLSTAF for a Perl service. Note that this OPTION will not be passed on to the service library / DLL.

    OPTION PROXYENV=<Variable=Value> allows you to specify environment variables that will be set for the STAFEXECPROXY executable (in addition to or replacing the environment variables that were set when STAFProc was started). This allows you to set environment variables for the STAFEXECPROXY executable without requiring that these environment variables be set for STAFProc. This option is particularly useful for Perl STAF services, which on many Unix platforms require LD_PRELOAD to be set to the libperl library file location. However, setting LD_PRELOAD prior to starting STAFProc can cause incompatibility issues for processes started via STAFProc. So, you can use OPTION PROXYENV to specify the LD_PRELOAD environment variable for the STAFEXECPROXY executable, without having it set for STAFProc's environment. To "unset" an environment variable, you can set the <Value> to be blank. You may specify any number of PROXYENV OPTIONs.

    STAFExecProxy.exe (STAFExecProxy on Unix) is the separate executable for the external service that will be displayed in the operating system's process list. You can determine the PID for the STAFExecProxy executable by running "HANDLE LIST HANDLES LONG".

    You may only run a single external service within a single STAFExecProxy executable (multiple services that use the STAFEXECPROXY library will each have a unique STAFExecProxy executable).

    Examples

    SERVICE Zip LIBRARY STAFEXECPROXY EXECUTE STAFZip
    
    SERVICE Device LIBRARY STAFEXECPROXY EXECUTE DeviceService \
                   OPTION PROXYLIBRARY=PLSTAF
    
    SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \
            GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \
            OPTION PROXYENV=LD_PRELOAD=/usr/lib/perl5/5.8.8/i386-linux-thread-multi/CORE/libperl.so \
            OPTION PROXYENV=TESTVAR=abcdef
     
    
    SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \
            GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \
            OPTION PROXYENV=LD_PRELOAD=/opt/ActivePerl-5.8/lib/CORE/libperl.so \
            OPTION PROXYENV=ANT_HOME= \
            OPTION "PROXYENV=MESSAGE=This is a test message"
     
    

    4.5 Service Loader Registration

    4.5.1 Description

    Service loaders are registered with the SERVICELOADER configuration statement.

    Syntax

    SERVICELOADER LIBRARY <Implementation library> [EXECUTE <Executable>]
                  [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    LIBRARY is the name of the shared library / DLL which implements the service loader or acts as a proxy for the service loader. See the information for each service loader to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the service loader. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.

    OPTION specifes a configuration option that will be passed on to the service loader library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service loader implementation. You may specify multiple OPTIONs for a given service loader. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service loader during initialization.

    Examples

    # Default Service Loader Service for LOG, MONITOR, RESPOOL, and ZIP services
    SERVICELOADER LIBRARY STAFDSLS
     
    # HTTP Service Loader Service for Java services (for Windows)
    SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/bin/STAFHTTPSLS.jar \
                  PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg"
     
    # HTTP Service Loader Service for Java services (for Unix)
    SERVICELOADER LIBRARY JSTAF EXECUTE /usr/local/staf/lib/STAFHTTPSLS.jar \
                  PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg"
     
    # Custom Service Loader Service written in Java
    SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/services/CustomServiceLoader.jar
    

    4.5.2 Default Service Loader Service (STAFDSLS)

    The default service loader service is implemented by library STAFDSLS and is written in C++. It can dynamically load the Log, Zip, Monitor, and ResPool C++ services. This service loader is configured automatically in the default STAF.cfg file as follows:

    # Add default service loader
    serviceloader library STAFDSLS
    

    4.5.3 HTTP Service Loader Service (STAFHTTPSLS)

    The HTTP service loader service is implemented by jar file STAFHTTPSLS.jar and is written in Java and is installed as part of STAF Java support in a typical installation of STAF. It can dynamically load any STAF service written in Java. It can download the jar file for a STAF Java service (or a zip file that contains the jar file) from a web server or from a file on the local machine. It uses a configuration file to determine what services it can load. To use the HTTP service loader service, a Java runtime must be installed and you must add a SERVICELOADER configuration statement to the STAF configuration file including a CONFIGFILE parameter specifying the location of the HTTPSLS configuration file you created for it.

    When STAF encounters a request for a service that isn't currently registered, it checks each service loader that is registered in the STAF configuration file to see if it handles this service. The HTTP service loader service reads its HTTPSLS configuration file (first downloading it from a web server if needed) to see if it can handle this service. If so, it downloads the service from the specified location to a temporary directory on the local machine (and unzips it if necessary to access the STAF service jar file) and submits an ADD request to the SERVICE service to register the service. This way, STAF is able to load whatever Java services you want. Also, note that each time the HTTP service loader service attempts to load a service, it reads its HTTPSLS configuration file, so you can update the HTTPSLS configuration file and it will read it the next time it attempts to load a service (without restarting STAFProc). Note that whenever STAF is restarted, the tmp directory in the STAF data directory is deleted which means the temporary jar files that the HTTP service loader service downloaded will be deleted since they are stored in the STAF tmp data directory's service/<Serviceloader Name> sub-directory.

    The HTTP service loader service can reduce the maintenance for obtaining and managing STAF Java services by:

    Syntax

    SERVICELOADER LIBRARY JSTAF EXECUTE <Fully-qualified name of STAFHTTPSLS.jar>
                  [OPTION <Name[=Value]>]...
                  PARMS "CONFIGFILE <ConfigFileLocation>
                         [DOWNLOADATTEMPTS <NumDownloadAttempts>]
                         [DOWNLOADRETRYDELAY <DelayInSeconds>]"
    

    LIBRARY must always be JSTAF which is the STAF Java service proxy library (because the HTTP Service Loader is written in Java).

    EXECUTE specifies the location of the jar file which implements the HTTP service loader service. On Windows, specify {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar. On Unix, specify {STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar.

    OPTION specifies a configuration option that will be passed to JSTAF to further control the interface to the JVM where this service loader will be run. You may specify multiple OPTIONs. See section 4.4.2, "JSTAF service proxy library" for acceptable options to the JSTAF service proxy library. For example, you can override the version of Java that you want the HTTP service loader service to use via the JVM=<Java Path> option when you create a new JVM by also using the JVMName=<JVM Name> option.

    PARMS specifies the parameters that will be passed to the service loader during initialization where:

    Examples

    # Add HTTP Service Loader Service on Windows using local HTTPSLS config file
    SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \
                  PARMS "CONFIGFILE {STAF/Config/STAFRoot}/bin/httpsls.cfg"
     
    # Add HTTP Service Loader Service on Unix using HTTPSLS config file on SourceForge website
    SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar \
                  PARMS "CONFIGFILE http://staf.sourceforge.net/current/STAFHTTPSLS.cfg"
                  
    # Add HTTP Service Loader Service on Windows using HTTPSLS config file on a web server
    SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \
                  OPTION JVMName=HTTPSLS OPTION JVM=C:/java1.5.0_12/bin/java \
                  PARMS "CONFIGFILE http://server.company.com/project/httpsls.cfg \
                         DOWNLOADATTEMPTS 3 DOWNLOADRETRYDELAY 7"
    

    Note that you can register the HTTP service loader service multiple times specifying unique values for the CONFIGFILE parameter. For example, you may have one HTTP service loader service that downloads STAF Java services like STAX, Event, Cron, and Email from the SourceForge website and you may have a second HTTP service loader service that downloads your custom STAF Java services from your own web server.

    HTTPSLS Configuration File

    The HTTP service loader service is configured through a text file called the HTTPSLS configuration file. This file may have any name you desire and can be located on a web server or on the local machine. The HTTPSLS configuration file is read and processed line by line. Whitespace at the front and end of each line is removed before processing. Blank lines, or lines containing only whitespace, are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line.

    Each service that you want the HTTP service loader service to load must have a SERVICE entry in the HTTPSLS configuration file. The syntax for each service is similar to the SERVICE syntax used when registering a STAF service in the STAF configuration file.

    Comments 

    You specify a comment by placing a pound sign, #, as the first non-blank character in the line. Comment lines are ignored. For example:

    # This is a comment line
    

    Service Registration 

    External Java services are registered with the SERVICE configuration statement. The syntax is:

    SERVICE <Name> LIBRARY JSTAF EXECUTE <Location of Service Jar or Zip File>
                   [ZIPPATH <Path to Service Jar File>]
                   [OPTION <Name[=Value]>]...
                   [PARMS "<Service Parameters>"]
    

    SERVICE specifies the name of the STAF service to be registered.

    LIBRARY must always be JSTAF which is the STAF Java service proxy library as the HTTP Service Loader only supports loading Java services.

    EXECUTE specifies the url for the Java jar file which implements the service. Or, it can specify the url of a zip file that contains the Java jar file if the ZIPPATH option is also specified. Or, it can specify the fully-qualified name of the Java jar file that resides on the local machine. This option will resolve STAF variables. For example:

      http://server1.company.com/staf/myservice.jar
      http://prdownloads.sourceforge.net/staf/STAXV333.zip
      C:/STAF/services/stax/STAX.jar
      {STAF/Config/STAFRoot}/services/email/STAFEmail.jar
    

    ZIPPATH specifies the path to the service jar file in the zip file specified by the EXECUTE option. Note that this option should only be used if the EXECUTE option specifies a url for a zip file that can be unzipped using the STAF ZIP service. This option does not resolve STAF variables. For example:

      stax/STAX.jar
      myService.jar
    

    OPTION specifies a configuration option that will be passed on to JSTAF to further control the interface to the JVM where this service will be run. You may specify multiple OPTIONs for a given service. See section 4.4.2, "JSTAF service proxy library" for valid options that can be specified for the JSTAF service proxy library.

    PARMS specifies parameters that will be passed to the service during initialization.

    Examples 

    # Register the custom SERVICE1 service, downloading it from a web server
    SERVICE SERVICE1 LIBRARY JSTAF EXECUTE http://www.company.com/service1.jar
     
    # Register the custom SERVICE2 service, downloading it from a web server
    SERVICE SERVICE2 LIBRARY JSTAF EXECUTE http://www.company.com/service2.jar \
            OPTION JVMName=SERVICE2
     
    # Register the STAX V3.3.0 service, downloading it from the SourceForge website
    SERVICE STAX LIBRARY JSTAF \
                 EXECUTE http://prdownloads.sourceforge.net/staf/STAXV333.zip \
                 ZIPPATH stax/STAX.jar \
                 OPTION JVMName=STAX OPTION J2=-Xmx1024m \
                 PARMS "EXTENSIONXMLFILE C:/staf/services/extensions.xml"
     
    # Register the Cron V3.3.2 service, downloading it from the SourceForge website
    SERVICE CRON LIBRARY JSTAF \
                 EXECUTE http://server.company.com/staf/CronV332.zip \
                 ZIPPATH cron/STAFCron.jar OPTION JVMName=CRON
     
    # Register the Email service (which resides in a jar file on the local machine)
    SERVICE EMAIL LIBRARY JSTAF EXECUTE C:/STAF/services/email/STAFEmail.jar \
                  PARMS "MAILSERVER NA.relay.ibm.com \
                         BACKUPMAILSERVERS \"LA.relay.ibm.com EMEA.relay.ibm.com\""
    

    A sample HTTP Service Loader Service Configuration File is available on SourceForge that can be used to download the latest versions of STAF Java services available on SourceForge such as STAX, Event, Cron, EventManager, etc. It is located at http://staf.sourceforge.net/current/STAFHTTPSLS.cfg. Note that you may need to customize this HTTPSLS configuration file for the services that you use by changing parameters for some services (like the MAILSERVER and BACKUPMAILSERVERS parameters for the Email service) and/or you may need to run some services like STAX in its own JVM with a larger maximum heap size for the JVM by adding some OPTIONs. Or, you may not use use some of the services so you may want to remove them, or you may want to download the STAF Java service zip files and put them on your own web server for faster download times, etc.


    4.6 Authenticator Registration

    4.6.1 Description

    Authenticator services are registered with the AUTHENTICATOR configuration statement. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter.

    Syntax

    AUTHENTICATOR <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
                         [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    <Name> is the name by which this authenticator service will be known on this machine. The name cannot be "none" as this is reserved for use by STAF. If you want to authenticate across systems, you must register the authenticator on each system using the same name (case-insensitive).

    LIBRARY is the name of the shared library / DLL which implements the authenticator service or acts as a proxy for the authenticator service. See the information for each authenticator to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the authenticator service. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.

    OPTION specifies a configuration option that will be passed on to the shared library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given authenticator service. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the authenticator service during initialization.

    Examples

    AUTHENTICATOR MyAuth LIBRARY JSTAF EXECUTE C:/STAF/services/MyAuth.jar
     
    AUTHENTICATOR AuthSample LIBRARY JSTAF \
                  EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
                  OPTION JVMName=Auth \
                  PARMS "UserPropertiesFile {STAF/Config/STAFRoot}/services/authsample.properties"
    

    4.6.2 Sample Authenticator

    A sample authenticator service is provided by STAF and is available via the Download STAF website. It is called AuthSample and is available as a jar file called AuthSampleV300.jar.

    Registration Syntax

    To try out user trust, you can register the sample authenticator as follows (assuming you downloaded it to a services directory created in the STAF root directory).

    AUTHENTICATOR AuthSample LIBRARY JSTAF \
                  EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
                  PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/authsample.properties"
    

    LIBRARY must be JSTAF for this sample authenticator as it is implemented in Java.

    EXECUTE must be the fully-qualified name of the AuthSampleV300.jar file.

    This sample authenticator has the following required parameter:

    To perform user authentication across systems, the authenticator must be registered as the same name (case-insensitive) on all machines where you want to use user trust authentication and with the same user properties file (e.g. one that supports the same user identifiers and passwords).

    User Properties File

    An example of a user properties file is:

    # User Properties File for the Sample Authenticator
     
    User1=Password1
    User2=Password2
    User3=Password3
    User4=Password4
    User5=Password5
    

    You can specify any user identifiers and passwords that you want in a user properties file. However, if you specify any confidential information (e.g. any real passwords that you want to protect), you should only use the secure TCP interface so that this information is protected when sent over the network.


    4.7 Operational parameters

    4.7.1 Description

    STAFProc allows you to set various parameters which affect the general operation of STAF. The SET configuration statement lets you set these general operational parameters.

    Syntax

    SET [CONNECTATTEMPTS <Number>]
        [CONNECTRETRYDELAY <Number>[s|m|h|d|w]]
        [MAXQUEUESIZE <Number>]
        [MAXRETURNFILESIZE <Number>[k|m]]
        [HANDLEGCINTERVAL <Number>[s|m|h|d]]
        [INITIALTHREADS <Number>]
        [THREADGROWTHDELTA <Number>]
        [DATADIR <Directory Name>]
        [INTERFACECYCLING <Enabled | Disabled>]
        [DEFAULTINTERFACE <Name>]
        [DEFAULTAUTHENTICATOR <Name>]
        [ENABLEDIAGS]
        [STRICTFSCOPYTRUST]
        [RESULTCOMPATIBILITYMODE <Mode>]
        [DEFAULTSTOPUSING <Method>]
        [DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE]
        [DEFAULTFOCUS <Background | Foreground | Minimized>]
        [PROCESSAUTHMODE <Authentication Mode>]
        [DEFAULTAUTHUSERNAME]
        [DEFAULTAUTHPASSWORD]
        [DEFAULTAUTHDISABLEDACTION <Disabled Action>]
        [DEFAULTSHELL <Shell>]
        [DEFAULTNEWCONSOLESHELL <Shell>]
        [DEFAULTSAMECONSOLESHELL <Shell>]
    

    CONNECTATTEMPTS specifies the maximum number of times to attempt to connect to a remote system. The default is 2. Note that a trace warning message is generated for each failed attempt if the Warning trace point is enabled. You may also change this setting dynamically using the MISC service's SET command.

    CONNECTRETRYDELAY specifies the maximum time in milliseconds to wait after a failed connection attempt to a remote system before trying to connect again (if the maximum number of times to attempt to connect to a remote system has not been reached yet). The default is 1000 (i.e., 1 second). You may also change this setting dynamically using the MISC service's SET command. The retry delay time may be expressed in milliseconds, seconds, minutes, hours, days, or weeks. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified: s (for seconds), m (for minutes), h (for hours), d (for days), or w (for weeks). Examples of valid values include 2s or 2000.

    MAXQUEUESIZE specifies the maximum size of the queue associated with each process' handle. The default is 100. You may also change this setting dynamically using the MISC service's SET command.

    MAXRETURNFILESIZE specifies the maximum size of a file that can be returned by a START request submitted to the PROCESS service running on this machine or by a GET FILE request submitted to the FS service running on this machine. The default is 0 which indicates not to limit the maximum size of returned files. Limiting the maximum returned file size can help prevent out of memory issues as these requests put the entire returned file contents in a result string which can consume a lot of memory for large files. This value may be expressed in bytes, kilobytes, or megabytes. Its format is <Number>[k|m] where <Number> is an integer >= 0 and indicates bytes unless one of the following case-insensitive suffixes is specified: k (for kilobytes) or m (for megabytes). The calculated value cannot exceed 4294967295 bytes. Examples of valid values include 100000, 500k, or 5m.

    Note that in addition to setting the MAXRETURNFILESIZE operational parameter, you can also set the STAF/MaxReturnFileSize variable in the request variable pool of the handle that submitted the request. The lowest of these two values is used as the maximum return file size (not including 0 which indicates no limit). Or, if you're using STAX, it also provides a MAXRETURNFILESIZE parameter that can be set when registering the STAX service or dynamically via the STAX service's SET MAXRETURNFILESIZE request. See the STAX User's Guide for more information.

    HANDLEGCINTERVAL specifies the time interval that the Handle Manager's garbage collection polling loop will wait between loops before polling each remote handle specified in the notification list to see if the remote machine is still running the same instance of STAFProc and if the handle still exists. The default is 60000 (i.e. 1 minute). You may also change this setting dynamically using the MISC service's SET command. The time interval may be expressed in milliseconds, seconds, minutes, hours, or days. Its format is <Number>[s|m|h|d], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified: s (for seconds), m (for minutes), h (for hours), or d (for days). Note that the calculated value cannot be less than 5 seconds and cannot exceed 24 hours. Examples of valid values include 2m, 45s, or 50000.

    INITIALTHREADS specifies the number of threads initially created to handle service requests. The default is 5.

    THREADGROWTHDELTA specifies the number of additional threads which should be created when all existing threads are busy. The default is 1.

    DATADIR specifies the directory that STAF and its services will use to write data. The default is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}. Note that this directory name must be unique per instance of STAFProc running on a single machine. Also, make sure to include the "SET DATADIR" line in the STAF configuration file at the beginning of the file, before any services are registered, since the data directory can be used during service registration. See 4.14, "Data Directory Structure" for more information about the STAF data directory and its contents.

    INTERFACECYCLING specifies whether to enable or disable automatic interface cycling. The default is to enable automatic interface cycling. You may also change this setting dynamically using the MISC service's SET command. Recognized values are the following:

    DEFAULTINTERFACE specifies the name of the network interface (aka connection provider) to use, by default. If not specified, the first interface registered is the default. You may also change this setting dynamically using the MISC service's SET command.

    DEFAULTAUTHENTICATOR specifies the name of the Authenticator to use, by default. If not specified, the first Authenticator registered is the default. If no authenticators are registered, the default authenticator is none. You may also change this setting dynamically using the MISC service's SET command.

    ENABLEDIAGS specifies to enable diagnostics. The default is to disable diagnostics. You may also enable (or disable) recording diagnostics dynamically using the DIAG service.

    STRICTFSCOPYTRUST specifies to enable strict trust checking when copying a file or directory using the FS service. The default is to disable strict trust checking (e.g. do lenient trust checking) on a FS COPY request when the machine submitting the request is the same as the machine where which the file/directory is being copied. That is, STRICTFSCOPYTRUST specifies that a trust check should be done to verify that MachineA trusts MachineB when MachineA submits a COPY request to the FS service on MachineB to copy a file or directory back to MachineA. The default is to do lenient trust checking so that MachineA does not have to trust MachineB since why would MachineA ask MachineB to copy the file/directory if he didn't want the copy to work. You may also change this setting dynamically using the FS service's SET command.

    RESULTCOMPATIBILITYMODE specifies the compatibility mode used when sending the result from a STAF service request back to a pre-STAF V3 system. Recognized values are the following:

    You may also change this setting dynamically using the MISC service's SET command.

    DEFAULTSTOPUSING allows you to specify the default method used to STOP processes. See 8.13.3, "STOP" for more information on available methods. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTNEWCONSOLE specifies that processes should be STARTed in a new console window. So, if a process's stdout/stderr is not redirected, it will be unavailable. This is the default for Windows systems. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTSAMECONSOLE specifies that processes should be STARTed in the same console as STAFProc. So, if a process's stdout/stderr is not redirected, it will be written to STAFProc's stdout/stderr. This is the default on Unix systems. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTFOCUS specifies the focus that is to be given to new windows opened when starting a process on a Windows system. The default focus mode is Background. This option only has effect on Windows systems. This option will resolve variables. See 8.13.2, "START" for more information on the FOCUS option. You may also change this setting dynamically using the PROCESS service's SET command.

    PROCESSAUTHMODE specifies the mode by which usernames/passwords are authenticated when starting processes. The value of this option is platform specific. Recognized values are the following:

    Note: Previously, PASSWD and SHADOW were supported values for the PROCESSAUTHMODE on Unix systems, but support for for these modes has been removed.

    You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTAUTHUSERNAME specifies the username under which processes will be started, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTAUTHPASSWORD specifies the password with which processes will be authenticated, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTAUTHDISABLEDACTION specifies what default action should be taken if the user specifies a username/password on a request to start a process when process authentication has been disabled. The following values are recognized:

    You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTSHELL specifies the default shell to use when starting a process via a separate shell. The default shell used for Unix systems is /bin/sh. The default shell used for Windows systems is "cmd.exe /c". You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTNEWCONSOLESHELL specifies the default shell to use when starting a process in a new console window (e.g. NEWCONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.

    DEFAULTSAMECONSOLESHELL specifies the default shell to use when starting a process in the same console as STAFProc (e.g. SAMECONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.

    A shell value can contain substitution characters described in the following table.

    Table 1. Substitution Characters for Shells
    Substitution character Description Supported systems
    %c Substitute the values specified by the COMMAND and PARMS options. Windows and Unix
    %C Same as %c, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %p Substitute the value specified by the PASSWORD option, or an empty string if no PASSWORD is provided. Windows and Unix
    %P Same as %p, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %t Substitute the value specified by the TITLE option, or <Unknown> if no TITLE is provided. Windows and Unix
    %T Same as %t, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %u Substitute the value specified by the USERNAME option, or an empty string if no USERNAME is provided. Windows and Unix
    %U Same as %u, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %w Substitute the value specified by the WORKLOAD option, or <Unknown> if no WORKLOAD is provided. Windows and Unix
    %W Same as %w, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %x Substitute the values specified by the COMMAND and PARMS options followed by input/output redirection, if I/O options are specified on the PROCESS START request (e.g. STDIN, STDOUT). When using this option, do not specify any redirection in the COMMAND/PARMS values. Windows and Unix
    %X Same as %x, except the substituted value will be quoted (with all nested quotes properly escaped). Windows and Unix
    %% Substitute a %. Windows and Unix

    Notes:

    1. When specifying a shell value, it must contain one of the following: %c, %C, %x, %X.
    2. The use of %c versus %C, as well as %x versus %X, is highly dependent on the shell you specify. If the shell expects the command and parameters to be parsed as a single string, then use %C or %X. If the shell expects the command and parameters to be parsed as separate strings, then use %c or %x.
    3. Specifying 'su - %u -c %C' as the shell when starting a process on a UNIX system (so that it simulates the environment of the user specified by the USERNAME option) will cause variables specified via an ENV option to not be set for the process.

    Examples

    SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2s
    SET MAXQUEUESIZE 1000
    SET MAXRETURNFILESIZE 25m
    SET HANDLEGCINTERVAL 50s
    SET INITIALTHREADS 10 THREADGROWTHDELTA 3
    SET DATADIR /test/stafdata
    SET DEFAULTINTERFACE tcp
    SET DEFAULTAUTHENTICATOR SampleAuth
    SET ENABLEDIAGS
    SET RESULTCOMPATIBILITYMODE none
    SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE
    SET DEFAULTFOCUS minimized
    SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass
    SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error
    SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C"
    SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C"
    SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X"
    SET DEFAULTSHELL "su - %u -c %C"
    

    4.8 Variables

    4.8.1 Description

    You may set STAF variables in the system or shared variable pool at startup by using the SET VAR configuration statement. SET VAR will set a variable to a certain value. The variable is created if it does not exist.

    Note that you may SET multiple variables with a single request.

    Syntax

    SET [SYSTEM | SHARED] VAR <Name=Value> [VAR <Name=Value>] ...
    

    SYSTEM means the variable is to be set in system variable pool. This is the default.

    SHARED means the variable is to be set in shared variable pool.

    VAR means the variable to be set. Name is the name of the variable and Value is the value of the variable.

    Examples

    SET VAR WebServer=testsrv1.test.austin.ibm.com
    SET SHARED VAR "Author1=Jane Tester" VAR "Author2=John Tester"
    SET SYSTEM VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
    

    4.9 Trust

    4.9.1 Description

    You may grant access to machines or users by using the TRUST configuration statement.

    Trust configuration statements for machines are based on the network identification of the system. In particular, different trust levels can be given to the same system coming in through different networking interfaces. Both logical and physical identifiers may be used in trust configuration statements for machines.

    Trust configuration statements for users require that you have an authenticator registered.

    Syntax

    TRUST LEVEL <Level> < DEFAULT | MACHINE <Machine> [MACHINE <Machine>]... |
                          USER <User> [USER <User>]... >
    

    LEVEL is the level of trust that you wish to grant, see 2.5, "Security" for a list of trust levels. This option will resolve variables.

    DEFAULT indicates that you wish to set the default trust level. This is the trust level that will be used for machines which have no explicit trust level set. If no default has been specified in the STAF Configuration file, the default is set to 3.

    MACHINE indicates a specific machine for which to set a trust level. This option will resolve variables. The format for <Machine> is:

      [<Interface>://]<System Identifier>
    
    where:

    Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).

    Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).

    Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.

    Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)

    USER indicates a user for which to set a trust level. This option will resolve variables. The format for <User> is:

      [<Authenticator>://]<User Identifier>
    
    where:

    Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).

    How to determine Effective Trust for a User

    If multiple trust specifications would match the same user, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:

    1. Exact match of authenticator and user identifier
    2. Exact match of authenticator, wildcard match of user identifier
    3. Wildcard authenticator match, exact match of user identifier
    4. Wildcard authenticator match, wildcard match of user identifier
    If multiple trust specifications match within the same rank, the lowest matching trust level will be used.

    How to determine Effective Trust for a Machine

    If multiple trust specifications would match the same system, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:

    1. Exact match of interface and physical network identifier
    2. Exact match of interface and logical network identifier
    3. Exact match of interface, wildcard match of physical network identifier
    4. Exact match of interface, wildcard match of logical network identifier
    5. Wildcard interface match, exact match of physical network identifier
    6. Wildcard interface match, exact match of logical network identifier
    7. Wildcard interface match, wildcard match of physical network identifier
    8. Wildcard interface match, wildcard match of logical network identifier
    If multiple trust specifications match within the same rank, the lowest matching trust level will be used.

    Note: The user authentication overrides the machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.

    Examples

    TRUST DEFAULT LEVEL 3
    TRUST LEVEL 5 MACHINE local://local
    TRUST LEVEL 5 MACHINE client1.austin.ibm.com MACHINE client3.raleigh.ibm.com
    TRUST LEVEL 5 MACHINE 9.3.224.16
    TRUST LEVEL 4 MACHINE tcp://mysystem.site.com
    TRUST LEVEL 0 MACHINE badguy.austin.ibm.com
    TRUST LEVEL 3 MACHINE tcp2://9.3.224.*
    TRUST LEVEL 2 MACHINE *.austin.ibm.com
    TRUST LEVEL 2 MACHINE tcp*://*.site.com
    TRUST LEVEL 5 USER John@company.com USER Jane@company.com
    TRUST LEVEL 0 USER badguy@company.com
    TRUST LEVEL 3 USER *@company.com
    TRUST LEVEL 4 USER SampleAuth://*@company.com
    TRUST LEVEL 1 USER *://*
    

    4.10 Start/Shutdown Notifications

    4.10.1 Description

    You may specify that you want notifications sent to certain machines/processes when STAF is either started or shutdown. You do this by using the NOTIFY configuration statement. Notifications are handled by the STAF Queue service, see 8.14, "Queue Service" for more information.

    Note: You may also dynamically register for SHUTDOWN notifications via the SHUTDOWN service, see 8.18, "Shutdown Service".

    Warning: In order for the receiving machine to accept the notifications, it must specify a default or explicit trust level of at least 3 for this machine. As of version 2.2.0 of STAF, the default trust level is 3, so no explicit action is necessary on systems running this version of STAF (or higher).

    Syntax

    NOTIFY <ONSTART | ONSHUTDOWN> MACHINE <Machine> [PRIORITY <Priority>]
           <NAME <Name> | HANDLE <Handle>>
    

    ONSTART indicates that a notification should be sent when STAF is fully initialized. The type of the message will be the string STAF/Start with a blank message.

    ONSHUTDOWN indicates that a notification should be sent when STAF is shutdown. The type of the message will be the string STAF/Shutdown with a blank message.

    MACHINE indicates the machine to receive the message.

    PRIORITY indicates the priority of the message. The default is 5.

    NAME specifies that all processes with the given registered name on the given machine should be notified. This option is usually preferred over HANDLE, as it is difficult to know the desired handle in advance.

    HANDLE specifies that the process with the given handle on the given machine should be notified.

    Examples

    NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager
    NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager
    

    4.11 Tracing

    4.11.1 Description

    STAF provides various tracing facilities to help in auditing and debugging. STAF externalizes these facilities through trace points. Enabling a particular trace point causes trace messages to be generated whenever a particular event occurs, such as a service request resulting in an "Insufficient Trust Level" (aka "Access Denied") error code. Care should be taken when enabling trace points, as certain trace points, such as ServiceResult, can lead to large quantities of trace messages being generated. In these cases, it is best to limit tracing to only specific services.

    You may enable or disable STAF trace points and STAF services for tracing using the TRACE configuration statement. In addition, you can set the trace output destination and set the default tracing state for newly registered services. By default, all STAF services are enabled for tracing. Also, if you are using the default STAF configuration file provided, only the ERROR and DEPRECATED trace points are enabled by default.

    Note: The TRACE ENABLE/DISABLE SERVICE(S) statements affect the current list of services. So, if you add line TRACE DISABLE ALL SERVICES to the configuration file and then register any external services later in the configuration file, those services will not necessarily be disabled. To ensure that all registered services are disabled, either set the default service state to disabled, or add the TRACE statements after the SERVICE configuration statements in the configuration file.

    Syntax

    TRACE ENABLE ALL  [ TRACEPOINTS | SERVICES ]
    TRACE ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    TRACE ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
    TRACE ENABLE SERVICE <Service> [SERVICE <Service>]...
     
    TRACE DISABLE ALL  [ TRACEPOINTS | SERVICES ]
    TRACE DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    TRACE DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
    TRACE DISABLE SERVICE <Service> [SERVICE <Service>]...
     
    TRACE SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] >
    TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled>
    TRACE SET MAXSERVICERESULTSIZE <Number>[k|m]
    

    See the TRACE service, section 8.19, "Trace Service", for information on the above options.

    See table 8.19.2, "Trace Points Reference" for a list of valid trace points.

    Examples

    TRACE SET DESTINATION TO STDERR
    TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc
    TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc APPEND
    TRACE SET DESTINATION TO STDOUT FILE {STAF/Config/STAFRoot}/bin/STAF.trc
    TRACE SET DESTINATION TO STDERR FILE {STAF/Config/STAFRoot}/bin/STAF.trc
    TRACE ENABLE ALL
    TRACE DISABLE SERVICE "Sem"
    TRACE ENABLE TRACEPOINTS "Error ServiceAccessDenied"
    TRACE DISABLE SERVICES "Process Queue Var"
    TRACE SET DEFAULTSERVICESTATE Enabled
    TRACE SET MAXSERVICERESULTSIZE 10k
    

    In order to ensure that you are only tracing service results on the var and sem services, and that tracing for all other services is disabled (including services registered in the future) do this :

    TRACE SET DEFAULTSERVICESTATE Disabled
    TRACE DISABLE ALL SERVICES
    TRACE DISABLE ALL TRACEPOINTS
    TRACE ENABLE TRACEPOINTS "ServiceResult"
    TRACE ENABLE SERVICES "VAR SEM"
    


    4.12 Configuration File Examples

    4.12.1 Default Configuration File

    This is the default configuration file provided with STAF.

    # Turn on tracing of internal errors and deprecated options
    trace enable tracepoints "error deprecated"
     
    # Enable TCP/IP connections
    interface ssl library STAFTCP option Secure=Yes option Port=6550
    interface tcp library STAFTCP option Secure=No  option Port=6500
     
    # Set default local trust
    trust machine local://local level 5
     
    # Add default service loader
    serviceloader library STAFDSLS
    

    4.12.2 Configuration File Example

    Warning: This configuration file contains references to fictional services, machines, etc. and is provided for informational purposes only. Please do not try to use this as your actual STAF.cfg file. It is unlikely to work.

    # ---------------------------------------------------------------------
    # STAF Configuration File
    # ---------------------------------------------------------------------
    # Set the writeable location where STAF can write data
    SET DATADIR E:\test\stafdata
     
    # Enable TCP/IP connections
    interface ssl library STAFTCP option Secure=Yes option Port=6550
    interface tcp library STAFTCP option Secure=No  option Port=6500 option ConnectTimeout=10000
     
    # Set default local trust
    trust machine local://local level 5
     
    # Add default service loader
    serviceloader library STAFDSLS
     
    # ---------------------------------------------------------------------
    # STAF Log Mask Variable
    # ---------------------------------------------------------------------
    SET SHARED VAR STAF/Service/Log/Mask="START STOP WARNING FATAL ERROR"
     
    # ---------------------------------------------------------------------
    # Setup Trust Levels
    # ---------------------------------------------------------------------
    TRUST DEFAULT LEVEL 2
    TRUST LEVEL 3 MACHINE test1.austin.ibm.com MACHINE test2.test.austin.ibm.com
    TRUST LEVEL 5 MACHINE automate.austin.ibm.com
    TRUST LEVEL 4 MACHINE *.test.austin.ibm.com
    TRUST LEVEL 3 USER IBM://*@us.ibm.com
    TRUST LEVEL 4 USER JohnDoe@company.com
    TRUST LEVEL 0 USER BadGuy@company.com
     
    # ---------------------------------------------------------------------
    # Delegated Services
    # ---------------------------------------------------------------------
    SERVICE pager DELEGATE globpager.test.austin.ibm.com
     
    # ---------------------------------------------------------------------
    # Java Services
    # ---------------------------------------------------------------------
     
    # Operating system independent name for my STAF services directory
    SET SYSTEM VAR myServiceDir={STAF/Config/STAFRoot}{STAF/Config/Sep/File}services
     
    SERVICE STAX  LIBRARY JSTAF \
                  EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAX.jar \
                  OPTION J2=-Xms64m OPTION J2=-Xmx128m
    SERVICE Event LIBRARY JSTAF \
                  EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAFEvent.jar
     
    # ---------------------------------------------------------------------
    # C++ Services
    # ---------------------------------------------------------------------
    SERVICE log      LIBRARY STAFLog
    SERVICE monitor  LIBRARY STAFMon
    SERVICE respool  LIBRARY STAFPool
     
    # ---------------------------------------------------------------------
    # Notifications
    # ---------------------------------------------------------------------
    NOTIFY ONSTART MACHINE automate.austin.ibm.com PRIORITY 3 NAME EventManager
    NOTIFY ONSHUTDOWN MACHINE automate.austin.ibm.com NAME EventManager
     
    # ---------------------------------------------------------------------
    # Activate tracing
    # ---------------------------------------------------------------------
    TRACE SET DESTINATION TO FILE {STAF/DataDir}/user/STAF.trc
    TRACE ENABLE TRACEPOINTS "ServiceAccessDenied Error"
    TRACE ENABLE SERVICES "Process Trust"
    

    4.13 Tuning

    4.13.1 Description

    STAF provides a way to tune its thread stack size. This is done via setting a "STAF_THREAD_STACK_SIZE" environment variable before STAFProc gets started. User can use this environment variable to set STAF's thread stack size in kilobytes.

    Examples, to set the thread stack size to 128KB

    On Unix: export STAF_THREAD_STACK_SIZE=128
    On Windows: set STAF_THREAD_STACK_SIZE=128
    

    4.14 Data Directory Structure

    By default, STAF and its services will write data to: {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}. For example: C:\STAF\data\STAF on Windows systems or /usr/local/staf/data/STAF on Unix systems or /Library/staf/data/STAF on Mac OS X systems. The STAF/DataDir system variable is set to the fully-qualified name of this directory.

    You may use the DATADIR operational parameter to change the writeable data directory for STAF. This directory name must be unique per instance of STAF running on a single machine.

    Note that the ability to change the data directory allows you to install STAF to a shared location (e.g. a read-only directory that is accessible via a mounted drive, etc.) and use a unique writeable data directory per instance of STAF.

    The following table describes the structure of the STAF data directory:

    Table 2. Data Directory Structure
    Directory Name Description
    {STAF/DataDir}/tmp This is the location where temporary data can be stored. This directory and all of its contents will be removed and an empty tmp directory is created whenever STAFProc is restarted.
    {STAF/DataDir}/user Other user data (e.g. from testcases, applications, etc.) can be stored in this directory. You should create subdirectories within this directory to when storing your data.
    {STAF/DataDir}/service This directory exists if one or more external services are (or have been) registered. If a service stores persistent data, it should create a subdirectory within this directory using its registered service name (in lower-case) and store its data in this subdirectory. For example:
    {STAF/DataDir}/service/event
    {STAF/DataDir}/service/log
    {STAF/DataDir}/service/stax
    
    {STAF/DataDir}/lang/java/jvm This directory exists if one or more external Java services are (or have been) registered. For each JVM created for Java services, STAF will create a subdirectory within this directory using the name of the JVM. The log files for the JVM (e.g. JVMLog.1) will be stored in this subdirectory. For example:
    {STAF/DataDir}/lang/java/STAFJVM1/JVMLog.1
    {STAF/DataDir}/lang/java/STAX/JVMLog.1
    
    {STAF/DataDir}/lang/java/service This directory exists if one or more external Java services are (or have been) registered. For each Java service registered, STAF will create a subdirectory within this directory using the registered service name and a subdirectory with it named jars. This subdirectory will contain nested jar files for the service, if any are provided by the service. For example:
    {STAF/DataDir}/lang/java/service/Event/jars
    {STAF/DataDir}/lang/java/service/STAX/jars
    
    {STAF/DataDir}/register For STAF's use only. This directory is used for storing registration data, if any, specified when this version of STAF was installed.

    4.14.1 Unix STAF Temporary Directory

    On Unix systems, STAF also writes a few files to the /tmp directory by default for each instance of STAFProc that is running. You can override the location of the directory by setting the STAF_TEMP_DIR environment variable. However, you must use the same STAF_TEMP_DIR environment variable for all instances of STAFProc in order for STAF to make sure that each STAFProc instance has a unique STAF_INSTANCE_NAME and a unique {STAF/DataDir}. Note that you should not specify {STAF/DataDir}/tmp for the value of the STAF_TEMP_DIR environment variable because each time STAFProc starts, it deletes the {STAF/DataDir}/tmp directory and this occurs after STAF creates some of these files.

    The following files are created in the Unix STAF Temporary Directory when starting STAFProc (and are deleted when STAFProc is shutdown).

    Warning!
    Do not delete these files while the STAFProc instance is running.

    When submitting a request to the "local" interface to communicate with a STAFProc instance, the STAF_INSTANCE_NAME environment variable must be set (if the STAFProc instance is not using the default name "STAF"). Also, on Unix only, the STAF_TEMP_DIR environment variable must be set (if the STAFProc instance is not using the default "/tmp" directory). Otherwise, the local service request will not be able to communicate with that STAFProc instance and RC 21 (STAF Not Running) will be returned.


    5.0 Commands


    5.1 STAFProc

    STAFProc is what starts STAF running on a machine.

    Syntax

    STAFProc [STAF Configuration File]
    

    Examples

    STAFProc d:\staf\bin\mystaf.cfg
    

    If [STAF Configuration File] is not specified, STAFProc will try to use the file staf.cfg. It will search for this file in the current directory, as well as the directory in which STAFProc resides.

    Warning: In order to stop the STAFProc daemon process, you should enter the command "STAF local shutdown shutdown" (or use the associated program in your "Start" menu on Windows systems). Pressing CTRL-C (or issuing a "kill" command) will terminate STAFProc, but will not allow it to properly cleanup, which may cause problems and/or delays when trying to restart STAFProc. See section 8.18, "Shutdown Service" for more information on the SHUTDOWN service.

    Note: Any changes made to the STAF Configuration File after STAFProc has been started will not take effect until you shutdown and restart STAFProc.

    5.1.1 Running Multiple Instances of STAFProc

    Multiple instances of STAFProc can be run at the same time on the same system . This makes it possible to use STAF to install/upgrade STAF itself. To run multiple instances of STAF, system-specific resources need to be differentiated. There is a special environment variable, STAF_INSTANCE_NAME, that can be used to specify a name for each STAFProc instance to differentiate between multiple instances of STAF. If this environment variable is not set, the default value, "STAF", is used for the instance name. If the STAF_INSTANCE_NAME environment variable is not set to a unique value prior to starting a new instance of STAFProc, you will see a "STAFProc already started" error.

    For each instance of STAFProc running on a system, the following settings must be unique:

    The installer creates a STAFEnv script file in the root STAF install location that can be used to set the required environment variables for a version of STAF. On Windows, the script file is called STAFEnv.bat and on Unix, the script file is called STAFEnv.sh. The STAFEnv script files are especially useful if you are going to be running two versions of STAF on the same machine and need a convenient way to switch settings for each version of STAF. An optional argument specifying the STAF instance name can be passed to a STAFEnv script file. A similar STAFEnv script file will also be created for setting up the environment for STAF V2, if STAF V2 is installed on the same machine as STAF V3.

    Here's a sample STAFEnv.bat file for Windows:

    @echo off
    REM STAF environment variables for 3.0.2
    set PATH=C:\STAF\bin;%PATH%
    set CLASSPATH=C:\STAF\bin\JSTAF.jar;C:\STAF\samples\demo\STAFDemo.jar;%CLASSPATH%
    set STAFCONVDIR=C:\STAF\codepage
    if "%1" EQU "" set STAF_INSTANCE_NAME=STAF
    if "%1" NEQ "" set STAF_INSTANCE_NAME=%1
    

    Here's a sample STAFEnv.sh file for Linux:

    #!/bin/sh
    # STAF environment variables for 3.0.2
    PATH=/usr/local/staf/bin:$PATH
    LD_LIBRARY_PATH=/usr/local/staf/lib:$LD_LIBRARY_PATH
    CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar:$CLASSPATH
    STAFCONVDIR=/usr/local/staf/codepage
    if [ $# = 0 ]
    then
        STAF_INSTANCE_NAME=STAF
    else
        STAF_INSTANCE_NAME=$1
    fi
    export PATH LD_LIBRARY_PATH CLASSPATH STAFCONVDIR STAF_INSTANCE_NAME
    

    The sample scripts that are created automatically by STAF will use the actual install directories in the STAFEnv script files.

    Here's an example of starting STAF V2 and STAF V3 on a Windows system, where STAF V2 is installed in C:\STAF and STAF V3 is installed in C:\STAF3. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.

      C:
      cd \STAF
      STAFEnv.bat
      STAFProc
    
    In another command prompt:
      C:
      cd \STAF3
      STAFEnv.bat
      STAFProc
    

    Here's an example of starting two instances of STAF V3 on a Unix system, specifying instance name STAF (the default) for one instance and instance name STAF2 for another instance. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.

      cd /usr/local/staf
      . ./STAFEnv.sh
      STAFProc /usr/local/staf/bin/STAF.cfg & 
      
      . ./STAFEnv.sh STAF2
      STAFProc /usr/local/staf/bin/STAF2.cfg & 
    

    Note: The STAF_INSTANCE_NAME environment variable must be set to the same value for a given STAFProc daemon and any applications/testcases that want to communicate to the instance of STAF.

    5.1.2 Running STAFProc on Windows with User Account Controls (UAC) Enabled

    On Windows Vista and Windows Server 2008 and later (including Windows 7, Windows 8, and Windows Server 2012, etc) with User Account Controls (UAC) enabled, STAFProc is run using the least amount of privileges (e.g. that of a standard user) even if you are logged in as an administrator. If you want to run a process via the STAF PROCESS START request that requires administrative privileges, such as an install program, and not get UAC prompts, you may need to run STAFProc as an administrator. There are several ways to do this:

    Note: When STAFProc.exe is run as an Administrator, you must also run STAF.exe as an Administrator if you want to submit STAF requests from a command prompt on the local Windows sytems. Otherwise, you'll get "Error registering with STAF, RC: 21". The same is true if you run a program on this Windows system that submits STAF service requests using the STAF APIs for Java, C/C++, Perl, Python, Tcl, etc, such as the STAX Monitor Java application. The program must also be run as an Administrator (e.g. by running it from an "Administrator: Command Prompt").


    5.2 STAF

    STAF is an executable that is used to submit requests to STAF from the command line. Please see "Using the STAF command from shell-scripts" for more information on using the STAF command from within shell-scripts.

    Syntax

    STAF [-verbose] <Endpoint> <Service> <Request>
    

    Examples

    STAF local PING PING
    STAF local sem event SynchSem post
    STAF testmach1 PROCESS START COMMAND notepad
    STAF testmach1.company.com PROCESS LIST
    STAF -verbose testmach1.company.com PROCESS LIST
    STAF ssl://testmach1 PROCESS START SHELL COMMAND /tests/myTest RETURNSTDOUT STDERRTOSTDOUT WAIT
    STAF tcp://testmach1 TRUST LIST
    STAF alt-tcp2://9.3.283.13 SERVICE LIST
    STAF testmach1@6600 PROCESS START COMMAND notepad NOTIFY ONEND
    STAF tcp://testmach.company.com@6500 MISC WHOAMI
    STAF local ECHO ECHO "Hi there"
    STAF 9.3.823.20 LOG MACHINE LOGNAME MyLog LEVEL info MESSAGE "This is a message"
    STAF local var set SYSTEM var "SomeName=Some  text  string"
    

    Notes

    1. Take a closer look at the last three examples. Quotes are required around the value to the echo, message, and set options because their values contain spaces. When calling STAF APIs directly from testcases/applications, you should normally use the colon-length-colon delimited format described in 7.2, "Option Value Formats".

    2. Older versions of STAF (prior to V2.1.0) required extra effort when quoting things on the command line. If you should need to resort to the old command line handling algorithm, simply set the environment variable STAF_OLDCLI to any non-empty value.

    3. If running multiple instances of STAFProc, the STAF_INSTANCE_NAME environment variable must be set to the instance name of the STAFProc daemon that you want the STAF command to talk to. For example:
      set STAF_INSTANCE_NAME=MySTAF
      staf local ping ping
      

    Output

    On a successful STAF request (i.e., a request with a zero return code), the output from the STAF command will be as follows

    Response
    --------
    <Result string>
    

    where <Result string> is any information that was returned from the STAF service request.

    For example, the output of STAF LOCAL PING PING should be

    Response
    --------
    PONG
    

    On an unsuccessful STAF request (i.e., a request with a non-zero return code), the output from the STAF command will be as follows

    Error submitting request, RC: <Return code>
    Additional info
    ---------------
    <Result string>
    

    where <Return code> is the actual return code from the request, and <Result string> is any information returned from the request. <Result string> usually contains information that explains why the error occurred. Note, the "Additional info" will only be present if a non-empty result string was returned. Additionally, you may refer to Appendix A, "API Return Codes" for information about the <Return code>

    For example, the output of STAF LOCAL SEM LIST should be

    Error submitting request, RC: 7
    Additional info
    ---------------
    You must have at least 1, but no more than 1 of the option(s), MUTEX EVENT
    

    Note: If the <Result string> from a STAF command contains any null characters, you can set the environment variable STAF_REPLACE_NULLS to any non-empty value. This will cause the STAF command to replace any null characters in the <Result string> with the specified value. Otherwise, the <Result string> will be truncated at the first null character found.

    When structured data (see 6.1, "Marshalling Structured Data") is returned in the result strings above, the STAF command will automatically unmarshall the data and print it in the most appropriate format. If the data is a <List> of <String>, then each entry in the list will be printed on its own line. For example,

    C:\> staf local fs list directory c:\
    Response
    --------
    AUTOEXEC.BAT
    boot.ini
    CONFIG.SYS
    Documents and Settings
    i387
    IO.SYS
    MSDOS.SYS
    My Music
    NTDETECT.COM
    ntldr
    PAGEFILE.SYS
    Program Files
    Recycled
    RECYCLER
    System Volume Information
    temp
    WINNT
    

    If the data is a <Map> (or <Map:<Class>>) which has values which are all of type <String>, then each key/value pair will be printed on its own line. For example,

    C:\> staf local monitor list settings
    Response
    --------
    Max Record Size    : 1024
    Resolve Message    : Disabled
    Resolve Message Var: Disabled
    

    The above two types of formatted output are frequently referred to as "default format".

    If the data is a <List> of <Map:<Class>> where every item in the list is an instance of the same map class, then the data will be printed out in a tabular format, called "table format". For example,

    $ staf local handle list handles
    Response
    --------
    Handle Handle Name                     State      Last Used Date-Time
    ------ ------------------------------- ---------- -------------------
    1      STAF_Process                    InProcess  20040929-13:57:40
    2      STAF/Service/STAFServiceLoader1 InProcess  20040929-16:06:47
    5      STAF/Service/LOG                InProcess  20040929-13:57:52
    7      STAF/Service/RESPOOL            InProcess  20040929-13:58:04
    51     STAF/Service/MONITOR            InProcess  20040929-16:06:47
    57     STAF/Client                     Registered 20040929-16:09:35
    

    The column headings in the table format are determined using the display name specified for each key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.

    By default a single record in the table format will only display the first 20 lines (the last line will show "(More...)" to indicate that there were more lines in the record). You can override the maximum number of lines that are displayed per record by setting the environment variable STAF_TABLE_LINES_PER_RECORD to the maximum number of lines.

    You can disable the output of tables by setting the environment variable STAF_PRINT_NO_TABLES to any value. If you disable the output of tables, their data will show up in the more verbose mode (described below).

    If the data is more complex than the above (or tables have been turned off), the output will be printed in a hierarchical nested format, called "verbose format". The best way to describe it is with an example.

    C:\> staf local sem query event Test
    Response
    --------
    {
      State      : Reset
      Last Posted: {
        Machine    : crankin3
        Handle Name: STAF/Client
        Handle     : 62
        User       : none://anonymous
        Date-Time  : 20040929-16:20:56
      }
      Last Reset : {
        Machine    : crankin3
        Handle Name: STAF/Client
        Handle     : 65
        User       : none://anonymous
        Date-Time  : 20040929-16:21:43
      }
      Waiters    : [
        {
          Machine    : crankin3
          Handle Name: TestHandle
          Handle     : 67
          User       : none://anonymous
          Date-Time  : 20040929-16:22:16
        }
      ]
    }
    

    You can change the amount of indentation used by setting the environment variable STAF_INDENT_DELTA to any non-negative integer.

    You can use the -verbose option to force the use of the verbose mode on a command basis. For example,

    C:\> staf -verbose local fs list directory c:\
    Response
    --------
    [
      AUTOEXEC.BAT
      boot.ini
      CONFIG.SYS
      Documents and Settings
      i387
      IO.SYS
      MSDOS.SYS
      My Music
      NTDETECT.COM
      ntldr
      PAGEFILE.SYS
      Program Files
      Recycled
      RECYCLER
      System Volume Information
      temp
      WINNT
    ]
    

    You can force the exclusive use of the verbose mode by setting the environment variable STAF_PRINT_MODE to "verbose". For example,

    C:\> set STAF_PRINT_MODE=verbose
     
    C:\> staf local fs list directory c:\
    Response
    --------
    [
      AUTOEXEC.BAT
      boot.ini
      CONFIG.SYS
      Documents and Settings
      i387
      IO.SYS
      MSDOS.SYS
      My Music
      NTDETECT.COM
      ntldr
      PAGEFILE.SYS
      Program Files
      Recycled
      RECYCLER
      System Volume Information
      temp
      WINNT
    ]
    

    If you should ever need to get at the raw result string (instead of the structured output), you can set the environment variable STAF_PRINT_MODE to "raw". For example,

    C:\> set STAF_PRINT_MODE=raw
     
    C:\> staf local fs list directory C:/temp/docs
    Response
    --------
    @SDT/*:267:@SDT/{:26::13:map-class-map@SDT/{:0:@SDT/[10:218:@SDT/$S:11:STAFTcl.h
    tm@SDT/$S:12:STAFPerl.htm@SDT/$S:14:STAFPython.htm@SDT/$S:7:History@SDT/$S:12:ST
    AFCMDS.htm@SDT/$S:11:STAFFAQ.htm@SDT/$S:10:STAFGS.pdf@SDT/$S:12:STAFHome.htm@SDT
    /$S:10:STAFRC.htm@SDT/$S:10:STAFUG.htm
    

    Note, by default, any <String> value that looks as though it, itself, is a marshalled data structure will be recursively unmarshalled. For example, if someone marshalls a data structure and uses the resultant string as the message for a log request, and then you query the log, the data structure in the log message string will automatically be unmarshalled. If you want to turn off this behavior from the command line, and, instead, see the marshalled string in the message, set the environment variable STAF_IGNORE_INDIRECT_OBJECTS to any value.

    Using the STAF command from shell-scripts

    There are two special environment variables that can be used to make the STAF command blend in with shell-scripts. The first is STAF_QUIET_MODE. Setting this environment variable to any non-null value will cause the STAF command to only output the <Result string> that the request generated. For example, the "STAF local ping ping" command above would simply return

    PONG
    

    This makes it easy to call STAF from shell-scripts. For example,

    export STAF_QUIET_MODE=1
     
    STAFResult=`STAF local ping ping`
     
    if [ $? -ne 0 ]; then
       echo "Non-zero return code from ping request";
    elif [ "$STAFResult" != "PONG" ]; then
       echo "Expected PONG, received $STAFResult";
    else
       echo "ping request succeeded"
    fi
    

    The second environment variable is STAF_STATIC_HANDLE. If this environment variable is set, the STAF command will use the handle number indicated by this environment variable. This ensures that the shell-script can use the same handle throughout its execution. You may obtain a static handle in one of two ways. The first is using the CREATE command of the HANDLE service (see 8.6.2, "CREATE"). For example,

    export STAF_STATIC_HANDLE=`STAF local handle create handle name "My Test"`
    

    In this case, you are responsible for deleting the shell-scripts handle prior to your shell-script exiting. For example,

    STAF local handle delete handle $STAF_STATIC_HANDLE
    

    The second way is by using the STATICHANDLENAME option when starting your script through the PROCESS service (see 8.13.2, "START"). In this case the STAF_STATIC_HANDLE environment variable will already be set for you. In addition, the handle will automatically be deleted by STAF when your shell-script completes.

    You can test for the existence of the STAF_STATIC_HANDLE environment variable to determine if your shell-script was started via STAF, or whether it was started by hand from the command line.


    6.0 API Reference


    6.1 Marshalling Structured Data

    STAF supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure.

    STAF supports the following generic data types with its marshalling.

    Most languages support some form of the None, String, List, and Map data types. However, a map class and a marshalling context are likely new concepts.

    A map class is really just a specialized map that is associated with a map class definition. The map class definition is used to reduce the size of a marshalling map class in comparison to a map containing the same data. It also contains information about how to display instances of the map class. A map class definition contains for following information for each key defined for a map class:

    You indicate that a map is an instance of a map class by setting the key "staf-map-class-name" to the name of the map class. And, when you unmarshall a data structure, if you see that a map has a key called "staf-map-class-name", you know that the map is really an instance of a map class. You get and set map class definitions using a marshalling context.

    A marshalling context is simply a container for map class definitions and a data structure that uses (or is defined in terms of) them. In order to use a map class when marshalling data, you must add the map class definition to the marshalling context, set the root object of the marshalling context to the object you want to marshall, and then marshall the marshalling context itself. When you unmarshall a data structure, you will always receive a marshalling context. Any map class definitions referenced by map classes within the data structure will be present in the marshalling context.

    When a string is unmarshalled into a data structure, it is possible that one of the string objects that is unmarshalled is itself the string form of another marshalled data structure. By default, STAF will recursively unmarshall these nested objects. However, each language has a way to disable these additional processing.


    6.2 C

    STAF externalizes six primary APIs to C/C++ programs. These APIs allow you to register/unregister with STAF, submit service requests, and free the memory associated with service request results. In addition, STAF provides a wide range of APIs for defining, manipulating, and marshalling data structures. Also, STAF provides some APIs for handling private data.

    Note: STAF-enabled programs written in C must be linked with the C++ compiler (or by using any other means which allows the C++ runtime to get initialized). Otherwise, the C++ runtime won't get a chance to initialize so the STAF static data doesn't get initialized. Most systems require mixed C and C++ code to get linked by the C++ compiler.

    6.2.1 STAFRegister

    Description

    The STAFRegister call is used by a C program to register with STAF.

    Syntax

    STAFRC_t STAFRegister(char *handleName, STAFHandle *handle)
    

    handleName points to the name by which you want this handle to be known.

    handle is a pointer to the STAFHandle that will be set on successful return from the function. You will use this handle on all other subsequent STAF calls.

    Examples

    char *myName = "MyProgram";
    STAFHandle_t myHandle = 0;
    STAFRC_t rc = STAFRegister(myName, &myHandle);
    

    6.2.2 STAFRegisterUTF8

    Description

    The STAFRegisterUTF8 API is identical in all respects with STAFRegister, except that handleName is a string in UTF-8 format. This API is used primarily by the Java interfaces.

    6.2.3 STAFUnRegister

    The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.

    Syntax

    STAFRC_t STAFUnRegister(STAFHandle handle)
    

    handle is the handle that you received on the call to STAFRegister.

    Examples

    /* myHandle was previously set by STAFRegister */
     
    STAFRC_t rc = STAFUnRegister(myHandle);
    

    6.2.4 STAFSubmit

    Description

    The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.

    Syntax

    STAFRC_t STAFSubmit(STAFHandle handle, char *where, char *service,
                        char *request, unsigned int requestLength,
                        char **resultPtr, unsigned int *resultLength);
    

    handle is the handle you received on the call to STAFRegister.

    where points to a string containing the destination machine for the service request. This should be either LOCAL or the name of a machine.

    service points to the name of the service to which you are submitting the request.

    request points to the actual request that you are sending to the service. This request may contain NULL (0x00) bytes.

    requestLength indicates the length of the request buffer passed in.

    resultPtr points to a char * that will contain the address of the result on return from the function. If, on return from STAFSubmit, *resultPtr is not 0, you must use STAFFree to free the result, even if the return code from STAFSubmit was non-zero. Note, if resultPtr is non-zero, then the buffer that resultPtr points to will always be NULL terminated. However, this buffer may contain NULL (0x00) bytes, therefore, it is not safe to determine the length of the buffer via strlen(). Instead, you should use the length provided by resultLength below.

    resultLength points to an unsigned int which, on return from STAFSubmit, will contain the length of the result buffer.

    Examples

    /* myHandle was previously set by STAFRegister */
     
    char *someMachine = "testmach1";
    char *service = "PING";
    char *request = "PING";
    unsigned int requestLength = strlen(request);
    char *result = 0;
    unsigned int resultLength = 0;
    STAFRC_t rc = 0;
     
    rc = STAFSubmit(myHandle, someMachine, service, request, requestLength,
                    &result, &resultLength);
    

    6.2.5 STAFSubmit2

    Description

    The STAFSubmit2 API is identical to the STAFSubmit API except that it has an additional parameter, syncOption, which allows submission of asynchronous requests.

    Syntax

    STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption,
                         char *where, char *service,
                         char *request, unsigned int requestLength,
                         char **resultPtr, unsigned int *resultLength)
    

    syncOption can be any of the following:

    The format of the queued message obtained when specifying kSTAFReqQueue or kSTAFReqQueueRetain will be a marshalled <Map:STAF/RequestComplete> which represents the request completion information. See table Table 3 for the map class definition.

    Table 3. Definition of map for "STAF/RequestComplete" type message
    Description: This map represents STAF/RequestComplete message information.
    Key Name Type Format / Value
    requestNumber <String>
    rc <String>
    result <String>

    For example, if you submitted the request "RESOLVE STRING {STAF/Config/OS/Name}" to the VAR service using kSTAFReqQueue, and received a request number of 42, then the message you would receive when the request completed might look like

    {
      requestNumber: 42
      rc           : 0
      result       : WinNT
    }
    

    The queued message will always be delivered with the default priority of 5.

    6.2.6 STAFSubmitUTF8

    Description

    The STAFSubmitUTF8 API is identical in all respects with STAFRegister, except that where, service, request, and *resultPtr are all strings in UTF-8 format. This API is used primarily by the Java interfaces.

    6.2.7 STAFSubmit2UTF8

    Description

    The STAFSubmit2UTF8 API is identical in all respects with STAFSubmit2, except that where, service, request, and *resultPtr are all strings in UTF-8 format. This API is used primarily by the Java interfaces.

    6.2.8 STAFFree

    Description

    STAFFree is used to free the memory occupied by the result buffer on a call to STAFSubmit. You only need to call this if result buffer pointer is not zero on return from STAFSubmit.

    Syntax

    STAFRC_t STAFFree(STAFHandle handle, char *result);
    

    handle is the handle you received on the call to STAFRegister.

    result is the pointer passed back from the STAFSubmit call.

    Examples

    /* myHandle was previously set by STAF     */
    /* result was previously set by STAFSubmit */
     
    STAFRC_t rc = 0;
     
    if (result != 0) rc = STAFFree(myHandle, result);
    

    6.2.9 Data Structure and Marshalling APIs

    STAF externalizes a wide range of APIs for defining data structures and (un)marshaling data structures. Here is a list of the APIs. A later version of this documentation will provide more details.

    typedef enum
    {
        kSTAFNoneObject               = 0,
        kSTAFScalarStringObject       = 1,
        kSTAFListObject               = 2,
        kSTAFMapObject                = 3,
        kSTAFMarshallingContextObject = 4
    } STAFObjectType_t;
     
    typedef enum
    {
        kSTAFMarshallingDefaults = 0x00000000
    } STAFObjectMarshallingFlags_t;
     
     
    typedef enum
    {
        kSTAFUnmarshallingDefaults = 0x00000000,
        kSTAFIgnoreIndirectObjects = 0x00000001
    } STAFObjectUnmarshallingFlags_t;
     
     
    // Object constructors/destructors
    //
    // Note: When a STAFObject is destructed, it recursively deletes all nested
    //       objects
     
    STAFRC_t STAFObjectConstructCopy(STAFObject_t *copy, STAFObject_t source);
    STAFRC_t STAFObjectConstructReference(STAFObject_t *ref, STAFObject_t source);
    STAFRC_t STAFObjectConstructNone(STAFObject_t *pNone);
    STAFRC_t STAFObjectConstructScalarString(STAFObject_t *pScalar,
                                             STAFStringConst_t string);
    STAFRC_t STAFObjectConstructList(STAFObject_t *list);
    STAFRC_t STAFObjectConstructMap(STAFObject_t *map);
    STAFRC_t STAFObjectConstructMarshallingContext(STAFObject_t *context);
    STAFRC_t STAFObjectDestruct(STAFObject_t *object);
     
    // General functions
     
    STAFRC_t STAFObjectIsStringMarshalledData(STAFStringConst_t string,
                                              unsigned int *isMarshalledData);
     
    // Object functions
     
    STAFRC_t STAFObjectGetType(STAFObject_t object, STAFObjectType_t *type);
    STAFRC_t STAFObjectGetSize(STAFObject_t object, unsigned int *size);
    STAFRC_t STAFObjectIsReference(STAFObject_t object, unsigned int *isRef);
    STAFRC_t STAFObjectUnmarshallFromString(STAFObject_t *newContext,
                                            STAFStringConst_t string,
                                            STAFObject_t context,
                                            unsigned int flags);
    STAFRC_t STAFObjectMarshallToString(STAFObject_t object, STAFObject_t context,
                                        STAFString_t *string, unsigned int flags);
    STAFRC_t STAFObjectGetStringValue(STAFObject_t object, STAFString_t *string);
     
    // Scalar functions
     
    STAFRC_t STAFObjectScalarGetStringValue(STAFObject_t object,
                                            STAFStringConst_t *string);
    STAFRC_t STAFObjectScalarGetUIntValue(STAFObject_t object,
                                          unsigned int *uInt,
                                          unsigned int defaultValue);
     
    // List functions
     
    STAFRC_t STAFObjectListAppend(STAFObject_t list, STAFObject_t object);
     
    // Iterator functions
     
    STAFRC_t STAFObjectConstructListIterator(STAFObjectIterator_t *iter,
                                             STAFObject_t list);
    STAFRC_t STAFObjectIteratorHasNext(STAFObjectIterator_t iter,
                                       unsigned int *hasNext);
    STAFRC_t STAFObjectIteratorGetNext(STAFObjectIterator_t iter,
                                       STAFObject_t *object);
    STAFRC_t STAFObjectIteratorDestruct(STAFObjectIterator_t *iter);
     
    // Map functions
     
    STAFRC_t STAFObjectMapGet(STAFObject_t map, STAFStringConst_t key,
                              STAFObject_t *object);
    STAFRC_t STAFObjectMapPut(STAFObject_t map, STAFStringConst_t key,
                              STAFObject_t object);
    STAFRC_t STAFObjectMapHasKey(STAFObject_t map, STAFStringConst_t key,
                                 unsigned int *hasKey);
    STAFRC_t STAFObjectConstructMapKeyIterator(STAFObjectIterator_t *pIter,
                                               STAFObject_t map);
    STAFRC_t STAFObjectConstructMapValueIterator(STAFObjectIterator_t *pIter,
                                                 STAFObject_t map);
     
    // Marshalling Context functions
     
    STAFRC_t STAFObjectMarshallingContextSetMapClassDefinition(
        STAFObject_t context,
        STAFStringConst_t name,
        STAFObject_t mapClassDefinition);
     
    STAFRC_t STAFObjectMarshallingContextGetMapClassDefinition(
        STAFObject_t context,
        STAFStringConst_t name,
        STAFObject_t *mapClassDefinition);
     
    STAFRC_t STAFObjectMarshallingContextHasMapClassDefinition(
        STAFObject_t context,
        STAFStringConst_t name,
        unsigned int *pHasMapClassDefinition);
     
    STAFRC_t STAFObjectMarshallingContextSetRootObject(STAFObject_t context,
                                                       STAFObject_t object);
    STAFRC_t STAFObjectMarshallingContextGetRootObject(STAFObject_t context,
                                                       STAFObject_t *object);
    STAFRC_t STAFObjectMarshallingContextAdoptRootObject(STAFObject_t context,
                                                         STAFObject_t *object);
    STAFRC_t STAFObjectMarshallingContextGetPrimaryObject(STAFObject_t context,
                                                          STAFObject_t *object);
    STAFRC_t STAFObjectConstructMapClassDefinitionIterator(
        STAFObjectIterator_t *pIter, STAFObject_t context);
    

    6.2.10 Private Data Manipulation APIs

    STAF externalizes some APIs for handling private data in STAF command request options. Here are the definitions for these APIs.

    // This method adds privacy delimiters to the data.
    // For example, if data passed in is "secret", sets result
    // to "!!@secret@!!".
     
    STAFRC_t STAFAddPrivacyDelimiters(STAFStringConst_t data,
                                      STAFString_t *result);
     
    // This method removes the specified number of levels of privacy
    // delimiters from the data.  Set numLevels to 0 to remove all
    // levels of privacy delimiters.
    // For example, if data passed in is "!!@secret@!!", sets
    // result to "secret".
                                      
    STAFRC_t STAFRemovePrivacyDelimiters(STAFStringConst_t data,
                                         unsigned int numLevels,
                                         STAFString_t *result);
     
    // This method masks any private data indicated by the privacy
    // delimiters by replacing the private data with asterisks.
    // For example, if data passed in is "!!@secret@!!", sets
    // result to "************".
                                         
    STAFRC_t STAFMaskPrivateData(STAFStringConst_t data, STAFString_t *result);
     
    // This method escapes any privacy delimiters found in the data.
    // For example, if data passed in is "!!@secret@!!", sets
    // result to "^!!@secret^@!!".
     
    STAFRC_t STAFEscapePrivacyDelimiters(STAFStringConst_t data,
                                         STAFString_t *result);
    

    6.2.11 Other Utility APIs

    STAF externalizes some other general utility APIs. Here are the definitions for these APIs.

    /*********************************************************************/
    /* STAFUtilFormatString - Generates a string based on a format       */
    /*                        string, ala printf().  This is generally   */
    /*                        used to format STAF request strings.       */
    /*                                                                   */
    /* Accepts: (In)  The format string                                  */
    /*          (Out) A pointer to the output string                     */
    /*          (In)  All data indicated in the format string            */
    /*                                                                   */
    /* Returns:  Standard return codes                                   */
    /*                                                                   */
    /* Notes  :  1) The caller is responsible for destructing the        */
    /*              output string                                        */
    /*********************************************************************/
    /* Valid format string specifiers:                                   */
    /*                                                                   */
    /* %d - an unsigned integer                                          */
    /* %s - a STAFString_t                                               */
    /* %C - a STAFString_t which will be formatted in colon-length-colon */
    /*      delimited format                                             */
    /* %% - a percent sign                                               */
    /*                                                                   */
    /* Any other %<char> is simply ignored (and not copied)              */
    /*********************************************************************/
    unsigned int STAFUtilFormatString(STAFStringConst_t formatString,
                                      STAFString_t *outputString, ...);
     
     
    /*********************************************************************/
    /* STAFUtilFormatString2 - Generates a string based on a format      */
    /*                         string, ala printf().  This is generally  */
    /*                         used to format STAF request strings.      */
    /*                                                                   */
    /* Accepts: (In)  The format string                                  */
    /*          (Out) A pointer to the output string                     */
    /*          (In)  A variable argument list                           */
    /*                                                                   */
    /* Returns:  Standard return codes                                   */
    /*                                                                   */
    /* Notes  :  1) The caller is responsible for destructing the        */
    /*              output string                                        */
    /*           2) Valid format strings are the same as defined for     */
    /*              STAFUtilFormatString()                               */
    /*********************************************************************/
    unsigned int STAFUtilFormatString2(STAFStringConst_t formatString,
                                       STAFString_t *outputString, va_list args);
     
     
    /*********************************************************************/
    /* STAFUtilStripPortFromEndpoint - Removes @<Port> from the end of   */
    /*     an endpoint if present.                                       */
    /*                                                                   */
    /* Accepts: (In/Out)  A pointer to a string containing the endpoint  */
    /*                    with format:                                   */
    /*                      [<Interface>://<Machine Identifier>[@<Port>] */
    /*          (Out)     A pointer to a string containing the stripped  */
    /*                    endpoint with format:                          */
    /*                      [<Interface>://<Machine Identifier>          */
    /*                                                                   */
    /* Returns:  0                                                       */
    /* Notes  :  1) The caller is responsible for destructing the output */
    /*              string containing the stripped endpoint              */
    /*********************************************************************/
    STAFRC_t STAFUtilStripPortFromEndpoint(STAFStringConst_t endpoint,
                                           STAFString_t *strippedEndpoint);
     
                                           
    /*********************************************************************/
    /* STAFUtilConvertDurationString - Converts the time duration        */
    /*   expressed as a string to a numeric value in milliseconds.       */
    /*                                                                   */
    /* Accepts: (In)  The duration string                                */
    /*                The duration string may be expressed in            */
    /*                milliseconds, seconds, minutes, hours, days, or    */
    /*                weeks.  Its format is:                             */
    /*                  <Number>[<Type>]                                 */
    /*                where <Number> is an integer >= 0 and <Type>, if   */
    /*                specified, is one of the following:                */
    /*                s (for seconds), m (for minutes), h (for hours),   */
    /*                d (for days), or w (for weeks). For example:       */
    /*                - 100 specifies 100 milliseconds,                  */
    /*                - 10s specifies 10 seconds,                        */
    /*                - 5m specifies 5 minutes,                          */
    /*                - 2h specifies 2 hours,                            */
    /*                - 1d specifies 1 day,                              */
    /*                - 1w specifies 1 week                              */
    /*          (Out) The numeric duration value in milliseconds         */
    /*          (Out) A pointer to an error string                       */
    /*                                                                   */
    /* Returns:  0,  if successful                                       */
    /*           47  if unsuccessful (*errorBuffer will be set)          */
    /*********************************************************************/
    STAFRC_t STAFUtilConvertDurationString(STAFStringConst_t durationString,
                                           unsigned int *duration,
                                           STAFString_t *errorBuffer);
    

    6.2.12 Other APIs

    STAF externalizes other APIs that fall into the following general classes

    Please see the indicated header files for more information on syntax and use of these families of APIs.


    6.3 C++

    STAF externalizes five primary classes to C++ programs. These class are

    Additionally, these classes use several other classes which are

    STAF also provides some other miscellaneous C++ classes, which are

    In addition, C++ applications are able to take advantage of the C-only APIs, such as Thread support.

    6.3.1 STAFHandle and STAFResult

    The STAFHandle class is used to register with, and submit service requests to, STAF. In C++ STAFHandles are reference counted, so they are automatically freed for you. To obtain a STAFHandle, you call one of the create() methods. The first is the standard call you will use, and it allows you to specify the name by which your program should be known. The second create method allows you to create a STAFHandle object from an existing STAFHandle_t which would have been obtained from the C API STAFRegister(). By default, a STAFHandle obtained through the first method will automatically be unregistered when the STAFHandle is destructed. A STAFHandle created via the second method will not automatically be unregistered when the STAFHandle is destructed. In either case, you can change this behavior with the setDoUnreg() method.

    Once you have a valid STAFHandlePtr, you can begin submitting requests to STAF. To do this, you use the submit() method, to which you specify the machine and service which should handle the request, as well as the request string itself. An optional fourth parameter defines whether this will be a synchronous or asynchronous request (if the parameter is not specified, the request will be synchronous). See the documentation for the C API STAFSubmit2 for the values allowed for this parameter. In return you get a reference counted pointer to a STAFResult object. Again, the underlying STAFResult object will be automatically freed when the reference count reaches zero. The STAFResult object itself contains a return code 'rc', a result string variable 'result', a result object variable 'resultObj', and a result marshalling context object variable 'resultContext'. If the STAFHandle's fDoUnmarshallResult flag is set to true (which it will be by default when a STAFHandle is created), then auto-unmarshalling will be performed which means the 'resultContext' variable will be set to the marshalling context obtaining from unmarshalling the string result data, and the 'resultObj' variable will contain the root object of this marshalling context. This allows you to not have to call the unmarshall() method to unmarshall the result immediately after call a submit() method. Note that if the STAFHandle's fDoUnmarshallResult flag is set to a false (which can be done using the setDoUnmarshallResult() method), the 'resultContext' and 'resultObj' variables will be set to the None object.

    You may examine the underlying STAFHandle_t via getHandle(). You may take ownership of the underlying STAFHandle_t via adoptImpl(). In this latter case, you are now responsible for the STAFHandle_t and are required to call STAFUnRegister(). Additionally, after a call to adoptImpl(), the existing STAFHandle object is invalidated and may not be used to call the submit() method.

    The utility function wrapData returns the colon-length-colon delimited version of the specified string. This is useful for specifying the values in STAF request string. See 7.2, "Option Value Formats" for more information.

    The utility function stripPortFromEndpoint returns an endpoint with the @port removed from the end of the endpoint, if present.

    Several utility functions are provided to handle private data that can be specified in values in a STAF request string. These functions are addPrivacyDelimiters, escapePrivacyDelimiters, removePrivacyDelimiters, and maskPrivateData. See 7.3, "Private Data" for more information about handling private data.

    Definition

    // STAFResult - This class contains the results of a STAFSubmit call
     
    class STAFResult
    {
    public:
     
        STAFResult(STAFRC_t theRC = kSTAFOk,
                   const STAFString &theResult = STAFString())
            : rc(theRC), result(theResult)
        { /* Do Nothing */ }
     
        STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen,
                   STAFString::CodePageType codePageType)
            : rc(theRC), result(data, dataLen, codePageType)
        { /* Do Nothing */ }
     
        STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen,
                   STAFString::CodePageType codePageType, bool doUnmarshallResult)
            : rc(theRC), result(data, dataLen, codePageType)
        {
            if (doUnmarshallResult)
            {
                resultContext = STAFObject::unmarshall(
                    result, kSTAFUnmarshallingDefaults);
                resultObj = resultContext->getRootObject();
            }
            else
            {
                resultContext = STAFObject::createNone();
                resultObj = STAFObject::createNone();
            }
        }
     
        STAFRC_t rc;
        STAFString result;
        STAFObjectPtr resultObj;
        STAFObjectPtr resultContext;
    };
     
     
    class STAFHandle;
    typedef STAFRefPtr<STAFResult> STAFResultPtr;
    typedef STAFRefPtr<STAFHandle> STAFHandlePtr;
     
     
    // STAFHandle - This class is used to interact with STAF.  You obtain a
    //              STAFHandle via the create() call.
     
    class STAFHandle
    {
        // This is the standard call to create a STAFHandle.  By default, this
        // STAFHandle object will unregister with STAF when destructed.
        static STAFRC_t create(const STAFString &name, STAFHandlePtr &handle);
     
        // This call is used to create a STAFHandle which uses an existing
        // STAFHandle_t.  By default, this STAFHandle object will not unregister
        // with STAF when destructed.
        static STAFRC_t create(STAFHandle_t handleT, STAFHandlePtr &handle,
                               bool doUnreg = false);
     
        STAFResultPtr submit(const STAFString &where, const STAFString &service,
                             const STAFString &request,
                             const STAFSyncOption_t synchOption = kSTAFReqSync);
     
        // This returns the colon-length-colon delimited version of a string
        static STAFString wrapData(const STAFString &data);
     
        // This will format a string for you.  See STAFUtilFormatString() in
        // STAFUtil.h
        //
        // Note: DO NOT try to pass STAFString's into the ... portion of this
        //       function.  The only supported data types are "unsigned int" and
        //       STAFString_t.  Therefore be sure to call getImpl() on all
        //       STAFString's before passing them to this method.
     
        static STAFString formatString(STAFStringConst_t formatString, ...);
     
        // This returns the endpoint without the port (strips @nnnn from the end
        // of the endpoint, if present)
        static STAFString stripPortFromEndpoint(const STAFString &endpoint);
     
        // This method returns the data with privacy delimiters added.
        // For example, if pass in "secret", it returns "!!@secret@!!".
        static STAFString addPrivacyDelimiters(const STAFString &data);
     
        // This method removes any privacy delimiters from the data.
        // For example, if pass in "!!@secret@!!", it returns "secret".
        static STAFString removePrivacyDelimiters(const STAFString &data,
                                                  unsigned int numLevels = 0);
     
        // This method masks any private data indicated by the privacy delimiters
        // by replacing the private data with asterisks.
        // For example, if pass in "!!@secret@!!", it returns "************".
        static STAFString maskPrivateData(const STAFString &data);
        
        // This method returns the data with privacy delimiters escaped.
        // For example, if pass in "!!@secret@!!", it returns "^!!@secret^@!!".
        static STAFString escapePrivacyDelimiters(const STAFString &data);
     
        STAFHandle_t getHandle() { return fHandle; }
     
        // This call allows you to claim ownership of the underlying STAFHandle_t.
        // Once this call is made, this STAFHandle object is no longer valid, and
        // it is your responsibility to unregister the STAFHandle_t with STAF.
        STAFHandle_t adoptHandle();
     
        bool getDoUnreg() { return fDoUnreg; }
        void setDoUnreg(bool doUnreg) { fDoUnreg = doUnreg; }
     
        bool getDoUnmarshallResult() { return fDoUnmarshallResult; }
     
        void setDoUnmarshallResult(bool flag)
        {
            fDoUnmarshallResult = flag;
        }
     
        ~STAFHandle();
     
    protected:
     
        STAFHandle(STAFHandle_t handle, bool doUnreg)
            : fDoUnreg(doUnreg), fHandle(handle)
        {
            fDoUnmarshallResult = true;
        }
     
        bool fDoUnreg;
        STAFHandle_t fHandle;
        bool fDoUnmarshallResult;
     
    };
    

    Examples

    #include "STAF.h"
    #include "STAF_iostream.h"
     
    int main(void)
    {
        STAFHandlePtr handle;
        unsigned int rc  = STAFHandle::create("MyApplication", handle);
     
        if (rc != 0)
        {
            cout << "Error registering with STAF, RC: " << rc << endl;
            return 1;
        }
     
        STAFResultPtr result = handle->submit("LOCAL", "PING", "PING");
     
        cout << "PING RC: " << result->rc << ", Result: " << result->result << endl;
     
        STAFString semName("Sem name with spaces");
     
        result = handle->submit("LOCAL", "SEM", "POST EVENT " +
                                STAFHandle::wrapData(semName));
     
        cout << "Sem Post RC: " << result->rc << ", Result: " << result->result
             << endl;
     
        // Send an Asynchronous request
        result = handle->submit("LOCAL", "SERVICE", "LIST", kSTAFReqQueueRetain);
     
        cout << "Service List Request Number: " << result->result << endl;
     
        return 0;
    }
    

    6.3.2 STAFObject

    The STAFObject class is used to represent a variety of structured data types. Unlike newer languages, C++ doesn't have a reflective type system allowing us to marshall arbitrary data structures. Therefore, we introduced a class which would allow us to provide general data structures which could be reflectively marshalled. Note, that all data structure methods are provided in the one STAFObject class.

    All data types are created via static methods. Note the createReference() method. This allows you to create a reference to another object. This is important to note, as when you add an object to another object (for example, adding a string to a list) the recipient takes ownership of the object. Thus, if you want to keep ownership of the object, you will need to add a reference of the object to the other object, instead of the object itself.

    Note, when a STAFObject is destructed, all objects it contains are destructed (recursively) as well. At this point, any references to objects that were contained in that data structure are now "dangling". The only valid methods for a "dangling" reference are isRef(), type(), and destruction.

    typedef enum
    {
        kSTAFNoneObject               = 0,
        kSTAFScalarStringObject       = 1,
        kSTAFListObject               = 2,
        kSTAFMapObject                = 3,
        kSTAFMarshallingContextObject = 4
    } STAFObjectType_t;
     
    typedef enum
    {
        kSTAFMarshallingDefaults = 0x00000000
    } STAFObjectMarshallingFlags_t;
     
     
    typedef enum
    {
        kSTAFUnmarshallingDefaults = 0x00000000,
        kSTAFIgnoreIndirectObjects = 0x00000001
    } STAFObjectUnmarshallingFlags_t;
     
     
    typedef STAFRefPtr<STAFObject> STAFObjectPtr;
     
    class STAFObject
    {
    public:
        // Creation methods
     
        static STAFObjectPtr createReference(const STAFObject &source);
        static STAFObjectPtr createReference(const STAFObjectPtr &source);
        static STAFObjectPtr createReference(STAFObject_t source);
        static STAFObjectPtr createNone();
        static STAFObjectPtr createScalar(const STAFString &aString);
        static STAFObjectPtr createList();
        static STAFObjectPtr createMap();
        static STAFObjectPtr createMarshallingContext();
     
        // General methods
     
        static bool isMarshalledData(const STAFString &aString);
     
        // General object methods
     
        STAFObjectType_t type();
        unsigned int size();
     
        bool isRef();
        STAFObjectPtr reference();
     
        STAFString asString();
     
        STAFString marshall(unsigned int flags = kSTAFMarshallingDefaults);
        void marshall(STAFString &output,
                      unsigned int flags = kSTAFMarshallingDefaults);
     
        // Note: This method always returns a Marshalling Context
        static STAFObjectPtr unmarshall(const STAFString &input,
                                        unsigned int flags =
                                        kSTAFUnmarshallingDefaults);
     
        // List methods
     
        void append(const STAFObjectPtr &objPtr);
        void append(const STAFString &aString);
     
        STAFObjectIteratorPtr iterate();
     
        // Map methods
     
        bool hasKey(const STAFString &key);
     
        STAFObjectPtr get(const STAFString &key);
     
        void put(const STAFString &key, const STAFObjectPtr &objPtr);
        void put(const STAFString &key, const STAFString &aString);
     
        STAFObjectIteratorPtr keyIterator();
        STAFObjectIteratorPtr valueIterator();
     
        // Marshalling Context methods
     
        void setMapClassDefinition(const STAFMapClassDefinitionPtr &defPtr);
     
        STAFMapClassDefinitionPtr getMapClassDefinition(const STAFString &name);
     
        bool hasMapClassDefinition(const STAFString &name);
     
        STAFObjectIteratorPtr mapClassDefinitionIterator();
     
        void setRootObject(const STAFObjectPtr &objPtr);
        STAFObjectPtr getRootObject();
     
        // Destructor
     
        ~STAFObject();
    };
    

    Examples

    This example submits a request to the PROCESS service to start a command and wait for it to complete. The result from this request is a marshalled map containing the process completion information. So this example demonstrates how to get the process return code from the result object (the root object of the marshalling context for the result).

    #include "STAF.h"
    #include "STAF_iostream.h"
     
    int main(void)
    {
        STAFHandlePtr handlePtr;
     
        unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr);
     
        if (rc != 0)
        {
            cout << "Error registering with STAF, RC: " << rc << endl;
            return rc;
        }
     
        // Submit a request to start a process on a machine and wait for
        // it to complete.  For this example, simply starting the process
        // on the local machine and listing and contents of C:/temp.
     
        STAFString machine = STAFString("local");
        STAFString command = STAFString("dir C:/temp");
     
        STAFResultPtr res = handlePtr->submit(
            machine, "PROCESS", "START COMMAND " +
            STAFHandle::wrapData(command) + " RETURNSTDOUT RETURNSTDERR WAIT");
     
        if (res->rc != kSTAFOk)
        {
            cout << "PROCESS START request failed with RC=" << STAFString(res->rc)
                 << " Result=" << res->result << endl;
            return res->rc;
        }
     
        // The result buffer from a successful PROCESS START WAIT request
        // returns a marshalled map containing the process completion information.
        // The marshalling context (e.g. the unmarshalled result) is available in
        // the 'resultContext' variable of the STAFResultPtr and the root object
        // for the marshalling context (which, in this case, is a map) is available
        // in the 'resultObj' variable of the STAFResultPtr.  That is,
        //   res->resultContext = STAFObject::unmarshall(res->result);
        //   res->resultObj = res->resultContext->getRootObject();
        // assuming auto-unmarshalling has not been disabled for the handle.
        
        // Print the result from the PROCESS START WAIT request in a
        // "Pretty Print" format using the asFormattedString() method
        
        cout << "Process Result (Pretty Printed): " << endl
             << res->resultContext->asFormattedString() << endl << endl;
     
        // Check if the process RC is 0 by getting the "rc" key from the
        // process completion map
     
        if (res->resultObj->get("rc")->asString() == "0")
            cout << "Process completed successfully" << endl;
        else
            cout << "Process failed with RC="
                 << res->resultObj->get("rc")->asString() << endl;
     
        return 0;
    }
    

    6.3.3 STAFObjectIterator

    The STAFObjectIterator class represents an iterator over other objects. You can not directly create a STAFObjectIterator. You obtain a STAFObjectIterator via calling an iteration method on a STAFObject. You can iterate over the items in a list, the keys in a map, the values in a map, and the names of the map class definitions in a marshalling context.

    Definition

    typedef STAFRefPtr<STAFObjectIterator> STAFObjectIteratorPtr;
     
    class STAFObjectIterator
    {
    public:
        bool hasNext();
        STAFObjectPtr next();
     
        ~STAFObjectIterator();
    };
    

    Examples

    This example submits a request to the FS service to list the contents of a directory (in the long, detailed format). The result from this request is a marshalled list of maps, so this example demonstrates how to get list object from the result object and how to iterate through this list using the STAFObjectIterator class.

    #include "STAF.h"
    #include "STAF_iostream.h"
     
    int main(void)
    {
        STAFHandlePtr handlePtr;
     
        unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr);
     
        if (rc != 0)
        {
            cout << "Error registering with STAF, RC: " << rc << endl;
            return rc;
        }
        // Submit a request to the FS service to list the contents of a
        // directory in the long format with detailed information about
        // the entries in the directory
        
        STAFString directory = "C:/temp/staf";
     
        STAFResultPtr res = handlePtr->submit(
            machine, "FS", "LIST DIRECTORY " +
            STAFHandle::wrapData(directory) + " LONG DETAILS");
     
        if (res->rc != kSTAFOk)
        {
            cout << "FS LIST DIRECTORY " << directory << " LONG DETAILS request"
                 << " failed with RC=" << STAFString(res->rc)
                 << " Result=" << res->result << endl;
            return res->rc;
        }
     
        // The result buffer from a successful LIST DIRECTORY LONG DETAILS
        // request returns a marshalled list of maps containing information
        // about the entries in the directory.
        // The marshalling context (e.g. the unmarshalled result) is available in
        // the 'resultContext' variable of the STAFResultPtr and the root object
        // for the marshalling context (which, in this case, is a map) is available
        // in the 'resultObj' variable of the STAFResultPtr.  That is,
        //   res->resultContext = STAFObject::unmarshall(res->result);
        //   res->resultObj = res->resultContext->getRootObject();
        // assuming auto-unmarshalling has not been disabled for the handle.
        
        // Print the result in a "Pretty Print" format using the 
        // asFormattedString() method
        
        cout << endl << "LIST DIRECTORY Result (Pretty Printed): " << endl
             << res->resultContext->asFormattedString() << endl << endl;
     
        // Iterate through the result object (which is a List containing a Map
        // for each entry in the directory).
        // Check if the directory contains a file named test.txt that
        // was last modified after 20060306-00:00:00.
        
        STAFObjectIteratorPtr iter = res->resultObj->iterate();
     
        while (iter->hasNext())
        {
            STAFObjectPtr entryMap = iter->next();
     
            if (entryMap->get("name")->asString() == "test.txt")
            {
                if (entryMap->get("lastModifiedTimestamp")->asString() >
                    "20060306-00:00:00")
                {
                    cout << "Entry test.txt was modified at "
                         << entryMap->get("lastModifiedTimestamp")->asString()
                         << endl;
                }
            }
        }
     
        return 0;
    }
    

    6.3.4 STAFMapClassDefinition

    The STAFMapClassDefinition class is used to represent the metadata associated with a map class. Note, the order with which keys are added determines their display order.

    Definition

    typedef STAFRefPtr<STAFMapClassDefinition> STAFMapClassDefinitionPtr;
     
    class STAFMapClassDefinition
    {
    public:
        static STAFMapClassDefinitionPtr create(const STAFString &name);
        static STAFMapClassDefinitionPtr createReference(
            STAFMapClassDefinitionPtr source);
     
        STAFObjectPtr createInstance();
     
        STAFMapClassDefinitionPtr reference();
     
        void addKey(const STAFString &keyName);
        void addKey(const STAFString &keyName, const STAFString &displayName);
     
        void setKeyProperty(const STAFString &keyName, const STAFString &propName,
                            const STAFString &propValue);
     
        STAFObjectIteratorPtr keyIterator();
     
        STAFString name() const;
     
        STAFObjectPtr getMapClassDefinitionObject();
    };
    

    6.4 Rexx

    STAF externalizes three APIs to Rexx programs. These APIs allow you to register/unregister with STAF and submit service requests. These APIs are located in the RXStaf DLL. A Rexx program wishing to use these APIs must be sure to load them from the DLL, with the following two lines of code.

    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
    

    STAF also provides wrapper interfaces around the LOG, MONITOR, and RESPOOL services, as well as a small set of utility functions. These wrapper interfaces and utility functions are provided in Rexx Library files which have the extension .rxl. In order to incorporate these wrappers into your Rexx programs, you may do one of the following:

    The names of these libraries are as follows:

    6.4.1 STAFRegister

    Description

    The STAFRegister call is used by a Rexx program to register with STAF.

    Syntax

    call STAFRegister handleName[, handleVarName]
    

    handleName is the name by which you want this handle to be known.

    handleVarName is the name of the Variable which you want to contain the handle that you will use on all other subsequent STAF calls. If this parameter is not specified, the handle will be placed in the variable STAFHandle.

    Examples

    call STAFRegister "MyHandleName", "MyHandle"
    say "My handle is:" MyHandle
    

    or

    call STAFRegister "MyHandleName"
    say "My handle is:" STAFHandle
    

    6.4.2 STAFUnRegister

    Description

    The STAFUnRegister call is used by a Rexx program to unregister with STAF, which frees up any internal STAF resources used by the handle.

    Syntax

    call STAFUnRegister [handle]
    

    handle is the handle that you received on the call to STAFRegister. If this parameter is not specified, the handle will be retrieved from the STAFHandle variable.

    Examples

    call STAFUnRegister MyHandle
    

    or

    call STAFUnRegister
    

    6.4.3 STAFSubmit

    Description

    The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.

    Syntax

    call STAFSubmit [handle,]  where, service, request [, resultVarName]
    

    handle is the handle you received on the call to STAFRegister. If this parameter is not specified, the handle will be retrieved from the STAFHandle variable.

    where is the destination machine for the service request. This should be either LOCAL or the name of a machine.

    service is the name of the service to which you are submitting the request.

    request is the actual request that you are sending to the service.

    resultVarName is the name of a variable that will contain the result of the service request. If you specify resultVarName, you must also specify handle

    Note: The Rexx variable "STAFResult" will always be set to the result of the service request. However, resultVarName allows you to get another variable set if needed.

    Note: To define whether a submit request should be synchronous or asynchronous, the STAFSyncOption variable should be set prior to calling STAFSubmit (if it is not set, the submit will be synchronous). The possible values for STAFSyncOption are defined in STAFUtil.

    Examples

    /* myHandle was previously set by a call to STAFRegister */
     
    someMachine = "testmach1"
    service = "PING"
    request = "PING"
     
    call STAFSubmit myHandle, someMachine, service, request, "SomeVar"
    say "STAFSubmit return code     :" RESULT
    say "Service request result     :" STAFResult
    say "Also service request result:" SomeVar
    

    or

    /* STAFHandle was previously set by a call to STAFRegister */
     
    someMachine = "testmach1"
    service = "PING"
    request = "PING"
     
    call STAFSubmit someMachine, service, request
    say "STAFSubmit return code     :" RESULT
    say "Service request result     :" STAFResult
     
    call STAFSyncValues
    STAFSyncOption = STAFSync.!ReqRetain
    call STAFSubmit someMachine, service, request
    say "Asynchronous Service request number     :" STAFResult
     
    

    6.4.4 STAFMon wrapper library

    Description

    The STAFMon wrapper library provides a wrapper around the MONITOR service. The following functions are provided:

    Syntax

    call STAFMonErrorText
    call STAFMonitor <Message>[, <Extra request data>]
    

    <Message> is the message that you wish to log to the MONITOR service.

    <Extra request data> is any additional information that should be passed along with the MONITOR service LOG request, such as additional options like RESOLVEMESSAGE.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFMonErrorText
     
    do i = 1 to numLoops
        call STAFMonitor "Beginning of loop #"i
          ...
          ...
    end
    

    6.4.5 STAFLog wrapper library

    Description

    The STAFLog wrapper library provides a wrapper around the LOG service. The following functions are provided:

    Syntax

    call STAFLogErrorText
    call STAFInitLog <Reference>, <Log name>[, [Log type], [Monitor mask]]
    call STAFSetCurrentLog <Reference>
    call STAFLog <Log level>, <Message>[, <Extra request data>]
    

    <Reference> is a text string of your desire that is used to refer to a log. This facilitates switching between several different log files.

    <Log name> is the name of the log to which you wish to log messages

    [Log type] is the type of log. This should be one of GLOBAL, MACHINE, or HANDLE. The default is MACHINE.

    [Monitor mask] is a string which specifies which logging levels should also be sent to the MONITOR service. The default is "FATAL ERROR WARNING INFO STATUS"

    <Log level> is the logging level of the message to be logged, e.g. ERROR or WARNING.

    <Message> is the message that you wish to log to the LOG service.

    <Extra request data> is any additional information that should be passed along with the LOG service LOG request, such as additional options like RESOLVEMESSAGE.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFLogErrorText
     
    call STAFInitLog "Public", "Testcase1", "MACHINE"
    call STAFInitLog "Private", "Testcase1", "HANDLE", "FATAL ERROR WARNING"
     
    call STAFSetCurrentLog "Public"
    call STAFLog "INFO", "Beginning testcase 1"
     
      ...
     
    call STAFSetCurrentLog "Private"
    call STAFLog "DEBUG", "Some private debug data"
    

    6.4.6 STAFPool wrapper library

    Description

    The STAFPool wrapper library provides a wrapper around the RESPOOL service. The following functions are provided:

    Syntax

    call STAFPoolErrorText
    call STAFPoolRequest <Pool name>, <Entry variable name>[, [Entry type], [Timeout]]
    call STAFPoolRelease <Pool name>, <Entry>[, <Force>]
    

    <Pool name> is the name of the pool from which to request or release an entry.

    <Entry variable name> is the name of the variable in which to place the actual requested entry's value.

    [Entry type] is the type of entry requested. This should be either FIRST or RANDOM. The default is RANDOM.

    [Timeout] is an amount of time, in milliseconds, after which the request should timeout. The default is to wait indefinitely.

    <Force> specifies whether the entry should be forceable released. This should be either FORCE or NOFORCE. The default is NOFORCE.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFPoolErrorText
     
    call STAFPoolRequest "Pool1", "Entry1"
    say "The entry obtained was:" Entry1
     
      ...
     
    call STAFPoolRelease Entry1
    

    6.4.7 STAFUtil library

    Description

    The STAFUtil library provides some utilitiy functions for use by Rexx programs. The following functions are provided:

    Syntax

    call STAFErrorText
    call STAFSyncValues
    wrappedData = STAFWrapData(<Data>)
    serviceResult = MakeSTAFResult(<Return code>[, <Result string>])
    

    <Data> is the data for which to generate the colon delimited version.

    <Return code> is the service request's return code.

    <Result string> is the service request's result string.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFErrorText
     
    someData = "..."
    wrappedData = STAFWrapData(someData)
     
    /* The following would only be used by a service provider */
    returnCode = 0
    resultString = "..."
    serviceResult = MakeSTAFResult(returnCode, resultString)
     
    /* The following sets the STAFSyncOption variable to one of the STAFSync constants */
    STAFSyncOption = STAFSync.!ReqRetain
    

    6.5 Java

    For information on STAF's V3 support for the Java language, see the STAF Java User's Guide.


    6.6 Perl

    For information on STAF's V3 support for the Perl language, see the STAF Perl User's Guide.


    6.7 Python

    For information on STAF's V3 support for the Python language, see the STAF Python User's Guide.


    6.8 Tcl

    For information on STAF's V3 support for the Tcl language, see the STAF Tcl User's Guide.


    7.0 Services overview

    Services are what provide all the capabilities of STAF.


    7.1 General Service Syntax

    When examining the syntax statements for each service, keep the following rules in mind.

    For example,

    LOG <GLOBAL | MACHINE | HANDLE> MESSAGE <Message>
    

    indicates that option LOG is required and requires no value, option MESSAGE is required and requires a value, and exactly one of options GLOBAL, MACHINE, and HANDLE must be specified (and none of these options requires a value).

    START COMMAND <Command> [WORKLOAD <Name>]  [WAIT | ASYNC]
    
    indicates that option START is required and requires no value, option COMMAND is required and requires a value, option WORKLOAD is not required, but, if specified, requires a value, and one of the options WAIT and ASYNC may be specified, and neither requires a value.

    7.2 Option Value Formats

    Values for options may be specified in one of three ways.

    1. If the value contains no spaces or quotes, you may simply specify the value. For example,
      MESSAGE Hello
      
    2. You may enclose the value in quotes. When doing so, the backslash character is the escape character. Any character after the backslash is treated as a literal character. To specify a backslash, use two backslashes. For example,
      MESSAGE "Hello World"
      

      specifies the message Hello World

      MESSAGE "He said, \"What is that\""
      

      specifies the message He said, "What is that"

      MESSAGE "c:\\MyApp\\Some directory with spaces"
      

      specifies the message c:\MyApp\Some directory with spaces

    3. You may use a length delimited format that is of the form :<Length>:<String>. Note that the length is specified in characters, not bytes. For example,
      MESSAGE :11:Hello World
      

      specifies the message Hello World

      MESSAGE :23:He said, "What is that"
      

      specifies the message He said, "What is that"

      MESSAGE :35:c:\MyApp\Some directory with spaces
      

      specifies the message c:\MyApp\Some directory with spaces

    The first two formats are most appropriate when using the STAF command line. The third is most appropriate and easiest from within programs using one of the supplied "wrapData" functions.

    Note that when the value of an option is the same as the name of the option (or another supported option), the value must be distinguished as such either by quoting the value or by using the length delimited format. For example, if NAME is the name of an option and you also want to specify NAME as the value of the option, you should specify either NAME "NAME" or NAME :4:NAME.

    Also, note that when you want to specify an empty string for the value of an option, you must use the third format (the length delimited format) because if you specify no value or "", then the STAF command parser thinks that no value was specified for the option and this will cause an "Invalid Request String" error (RC 7) if the option requires a value. For example,

    MESSAGE :0:
    

    7.3 Private Data

    Some command options allow their values to contain private data which will be handled by the service. This will be noted in the command options that allow it.

    Private data is denoted by surrounding the private data, e.g. a password, between an opening privacy delimiter (!!@) and a closing privacy delimiter (@!!). For example, !!@password@!!. Because of this special significance of "!!@" and "@!!", if you do not want them to denote private data, use a caret (^), as an escape character for "!!@" and "@!!". Nested private data is allowed.

    Using privacy delimiters indicates that the data enclosed between opening and closing privacy delimiters should be protected so that if the private data is displayed (e.g. in a LIST or QUERY request), any private data will be masked (replaced with asterisks).

    Examples

    The Process service's START request handles private data in the COMMAND, PARMS, and/or PASSWORD options. If the command contains a password (e.g. secret) that you want to keep private, enclose the password between privacy delimiters as follows:

    START SHELL COMMAND "C:/tests/myTest.exe -password !!@secret@!!"
    
    The above command would be displayed as "myTest.exe -password ************" in a LIST or QUERY request.

    If you want to start command "TestA.exe" as another user (e.g. userid testuser and password secret), you can indicate that the password is private as follows:

    START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@secret@!!
    

    If the password in the above example actually contained !!@ or @!! (e.g. pass@!!rd), then you need to escape the privacy delimiter. For example:

    START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@pass^@!!rd@!!
    

    You can nest private data. For example the following string contains two levels of nested private data:

    !!@Top secret info: password=^!!@secret^@!!.@!!
    
    Note that a caret (^) is added to escape any !!@ and @!! characters that are nested within another set of privacy delimiters.

    When specifying private data for a command option in a program, use the method provided by STAF to add privacy delimiters. STAF also provides methods to escape privacy delimiters, to mask privacy delimiters, and to remove privacy delimiters. See the STAF API documentation for more information.


    7.4 Variable Resolution

    Most command options allow their values to contain variable references which will be resolved by the service. This will be noted in the command options that allow it. In addition, the machine and service specified when submitting a STAF request may contain variable references.

    The following potential variable pools are available for use in variable resolution in a service request:

    Unless otherwise specified, variable resolution is handled in one of two ways, based on whether the request is performed locally (i.e., on the originating system) or on another system.

    Note: Since, by definition, a delegated service request will not be handled locally, the variable pool associated with the requesting process will never be used for variable resolution in a delegated service request.


    7.5 Service Result Definition

    While all services technically return strings in the result buffer, many times this string will actually be the marshalled form of a data structure. This section describes how a service's result is defined in this documentation. See 6.1, "Marshalling Structured Data" for more information on marshalled data structures (and how they are mapped to the various languages that STAF supports).

    In the simplest case, a service will return no value or a simple string (i.e., a string which is not the marshalled form of a data structure). In this case, the service result will simple describe what the simple string contains. For example, the HANDLE service documentation (see 8.6.2, "CREATE") indicates that when creating a static handle the result buffer will simply contain the handle number that was created.

    If the service result contains the marshalled form of a data structure (which will now be referred to as "structured data"), the service documentation will describe it in terms of various structured content. The following are the types of structured data you will encounter.

    In some cases, the structured data that is returned will be one of a number of possible values. In that case, you will see the "or" symbol, '|', used to list the possible choices. Two common cases are

    <String> | <None>
    
    and
    <Map:<Class>> | <None>
    

    In the first case, this means that you will either get a string object or the special <None> object. In the second case, it means you will either get an instance of the specified map class or the special <None> object.

    To further document map classes, each map class will have an associated table defining the metadata associated with the map class. The general format of this table is as follows.


    Table 4. Definition of map class <Map Class Name>
    Description: This contains a description of the map class
    Key Name Display Name Type Format / Value
    key1 Key 1 display name
    (Key 1 short display name) if one is provided
    key1 type key1 format/value information
    ... ... ... ...
    keyX Key X display name
    (Key 1 short display name) if one is provided
    keyX type keyX format/value information
    Notes: Any notes about the definition of the map class.

    The "Display Name" field shows the display name for each key, and, optionally, a "short" display name may be specified (in parenthesis) for a key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.

    The "Format / Value" field is used predominantly to document the data present in <String> objects. When, the string will contain one of a limited set of possible values, then the set of possible values will be listed in this column. This might look like the following

    'Default' | 'Enabled' | 'Disabled'
    

    When the string will be in a particular format, the format will be documented in this column. For example, a common string value is a timestamp, which is documented in the "Format / Value" column as follows

    <YYYYMMDD-HH:MM:SS>
    


    7.6 Service Help

    All STAF services provide a HELP command that list basic service syntax information.

    It is recommended that external service writers also provide a HELP facility.


    7.7 Service list

    The following table contains a brief description of the services provided with STAF. The chapter that follows provides a detailed explanation of each service.

    Table 5. Service Descriptions
    Service name Description String Representation
    CONFIG Provides a way to save the current STAF configuration
    DELAY Provides a means to sleep a specified amount of time
    DIAG Provides diagnostics services
    ECHO Echos back a supplied message
    FS Provides file transfer between systems
    HANDLE Provides information about existing STAF handles
    HELP Provides help on STAF error codes
    LIFECYCLE Runs STAF service requests when STAFProc starts up or shuts down
    LOG Provides robust logging services
    MISC Handles miscellaneous commands such as displaying the version of STAF that is currently running
    MONITOR Provides a means to monitor the status of running programs
    PING Provides a simple is-alive message
    PROCESS Handles starting, stopping, and querying processes
    QUEUE Interacts with STAF queues
    RESPOOL Manages pools of named elements
    SEM Provides named event and mutex semaphores
    SERVICE Provides information on available STAF services
    SHUTDOWN Provides a means to shutdown STAF and register for shutdown notifications
    TRACE Provides tracing information for STAF services
    TRUST Interfaces with STAF's security
    VAR Allows inspection and manipulation of STAF variable pools
    ZIP Provides a means to zip/unzip/list/delete PKZip/WinZip compatible archives


    8.0 Service reference

    The foundation services that STAF provides are described in this chapter. For each service the following sections are listed.


    8.1 Config Service

    8.1.1 Description

    The CONFIG service is one of the internal STAF services. It provides a way to save the current STAF configuration to a file, reflecting any changes made since STAFProc was started.

    8.1.2 SAVE

    SAVE will display the current STAF configuration data or save it to a file, reflecting any changes made since STAFProc was started. This includes any dynamic changes made by:

    Syntax

    SAVE [FILE <Name>] [VARS <Current | Startup>]
    

    FILE specifies that name of a file where you want to save the current STAF configuration data. This file cannot already exist. This option will resolve variables.

    VARS specifies which STAF system and shared variables to save. This option will resolve variables. Recognized values are the following:

    Security

    This command requires trust level 3.

    However, if the DEFAULTAUTHPASSWORD has been set for the PROCESS service, this command requires trust level 5.

    Return Codes

    All return codes from SAVE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, if the FILE option is not specified, the result buffer will contain the current STAF configuration data.

    On successful return, if the FILE option is specified, the result buffer will contain no data and the current STAF configuration data will be saved to the specified file name.

    Examples


    8.2 Delay Service

    8.2.1 Description

    The DELAY service is an internal STAF service. A DELAY request simply sleeps for a specified amount of time before returning to the calling program.

    8.2.2 DELAY

    Syntax

    DELAY <Number>[s|m|h|d|w]
    

    DELAY specifies an amount of time to sleep. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated amount of time to sleep cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from DELAY are documented in Appendix A, "API Return Codes".

    Examples

    1. Goal: Delay 100 milliseconds.
        
      DELAY 100
      

    2. Goal: Delay 5 seconds.
      DELAY 5s
      

      Note that this is equivalent to:

      DELAY 5000
      

    3. Goal: Delay 1 minute.
      DELAY 1m
      

      Note that this is equivalent to:

        
      DELAY 60000
      

    4. Goal: Delay 2 hours.
      DELAY 2h
      


    8.3 Diagnostics (DIAG) Service

    8.3.1 Description

    The Diagnostics service, called DIAG, is an internal STAF service which lets you record and list diagnostics data. It provides the following commands:

    The purpose of the DIAG service is to allow you to record diagnostics data consisting of a trigger and its source. The number of times each trigger/source combination occurs is accumulated by the DIAG service. You may list the trigger(s)/source(s) and their counts, as well as clear all data from the diagnostics map.

    Note: The commands for the DIAG service and their result formats are subject to change.

    8.3.2 RECORD

    RECORD writes diagnostics data (a trigger and its source) to a diagnostics map where a count is kept of the number of times each unique trigger/source combination occurs.

    Note: You must enable diagnostics before you can record diagnostics data.

    Syntax

    RECORD TRIGGER <Trigger> SOURCE <Source>
    

    TRIGGER specifies the trigger (event) that you want to record in the diagnostics map. You can specify anything for the trigger, but we recommend that you don't specify a semi-colon (;) in the trigger to make it easier to parse the list output which uses a semi-colon to separate fields. This option will resolve variables.

    SOURCE specifies information about the originator of the trigger. It is also recorded in the diagnostics map. For example, you may want to include the originating machine's name, handle, and handle name. This option will resolve variables.

    Security

    This command requires trust level 3.

    Note: This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from RECORD are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RECORD command.

    Examples

    Goal:  Record trigger "PROCESS QUERY" and "myApp;machinea.ibm.com" as the source of the trigger in the diagnostics map.
    Syntax:  RECORD TRIGGER "PROCESS QUERY" SOURCE "myApp;machinea.ibm.com"

    8.3.3 LIST

    LIST allows you to list all the information in the diagnostics map, or just the triggers or sources, or a particular trigger or source. It also allows you to list current operational settings.

    Syntax

    LIST   <[TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES]
            [SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE]> |
           SETTINGS
    

    If no options are specified (other than a SORTBY option), it will list all the trigger/source combinations that were recorded and the number of times each was recorded.

    TRIGGER indicates you want to list all the sources for the specified trigger and the number of times each source was recorded for this trigger. This option will resolve variables.

    SOURCE indicates you want to list all the triggers for the specified source and the number of times each trigger was recorded for this source. This option will resolve variables.

    TRIGGERS indicates you want to list all the triggers that have been recorded and the number of times they were recorded.

    SOURCES indicates you want to list all the sources that have been recorded and the number of times they were recorded.

    SORTBYCOUNT specifies to sort the listing by count in descending order. This is the default.

    SORTBYTRIGGER specifies to sort the listing by trigger in ascending order.

    SORTBYSOURCE specifies to sort the listing by source in ascending order.

    SETTINGS indicate you want to list the current operational settings for the service.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the LIST request based on the options specified:

    Examples

    8.3.4 RESET

    RESET allows you to clear all data from the diagnostics map.

    Syntax

    RESET FORCE
    

    FORCE is a confirmation that you want to clear all data.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from RESET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RESET command.

    Examples

    Goal:  Remove all information in the diagnostics map.
    Syntax:  RESET FORCE

    8.3.5 ENABLE

    ENABLE allows you to enable recording diagnostics.

    Note: You may also enable diagnostics when STAF starts by setting operational parameter ENABLEDIAGS in the STAF configuration file.

    Syntax

    ENABLE
    

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from ENABLE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a ENABLE command.

    Examples

    Goal:  Enable recording diagnostics.
    Syntax:  ENABLE

    8.3.6 DISABLE

    DISABLE allows you to disable recording diagnostics.

    Syntax

    DISABLE
    

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from DISABLE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a DISABLE command.

    Examples

    Goal:  Disable recording diagnostics.
    Syntax:  DISABLE


    8.4 Echo Service

    8.4.1 Description

    The ECHO service is an internal STAF service. ECHO provides a similar service as PING. The difference is that ECHO allows you to specify the return string that STAFProc will return. ECHO can also be used to determine if STAFProc is up and running and accessible.

    8.4.2 ECHO

    Syntax

    ECHO <Message>
    

    Note: ECHO does not follow the request parsing rules described earlier. Any text after the ECHO command will be returned verbatim.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from ECHO are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain <Message> on a successful return from an ECHO command.

    Examples

    Goal: Have STAFProc return the string Hello World to you.

    ECHO Hello World
    


    8.5 File System (FS) Service

    8.5.1 Description

    The File System service, called FS, allows you to interface with the file system on STAF Clients. It provides the following commands.

    In the descriptions of these commands, three different options are used to refer to objects in the file system. FILE is used when the object in question must be a file. DIRECTORY is used when the object in question must be a directory. ENTRY is used when the object in question may be any object in the file system.

    Some of these commands (e.g. COPY DIRECTORY, LIST DIRECTORY, DELETE) allow match patterns to be specified. These patterns recognize two special characters, '*' and '?', as wildcards:

    8.5.2 COPY FILE

    COPY FILE allows you to copy one file between machines, or to another location on the same machine.

    Notes:

    1. A file copied via the FS service does not retain its system or extended attributes.
    2. If a file copied via the FS service is a symbolic link, the entry referenced by the link will be copied (not the symbolic link itself).
    3. The FS service supports copying a file whose size is less than 4 GB on most platforms, assuming the operating system supports the creation of large files, that is, files larger than 2 GB.

    Syntax

    COPY FILE <FileName> [TOFILE <Name> | TODIRECTORY <Name>] [TOMACHINE <Machine>]
         [TEXT [FORMAT <Format>]] [FAILIFEXISTS | FAILIFNEW]
    

    FILE specifies the name of the file to copy. This option will resolve variables.

    TOFILE specifies the name of the file to create. The directory path specified must already exist on the machine where the file is being copied to, or else the copy request will fail with RC 17 (File open error). If neither TOFILE nor TODIRECTORY is specified, this defaults to the same, unresolved, name as specified in FILE. This option will resolve variables. These variables will be resolved on the target machine.

    TODIRECTORY specifies the name of the directory to copy the file to. The name of the "to file" will be the same as specified in FILE. This directory must already exist on the target machine. This option will resolve variables. These variables will be resolved on the target machine.

    TOMACHINE specifies the machine to copy the file to. This defaults to the machine which originated the request. Specifying local indicates to copy the file to the same machine that the file is being copied from. Note that specifying local instead of the from machine's host name can significantly improve performance, especially if your TCP network performance is slow. This is because local (or local://local) indicates to use the local network interface versus specifying a TCP host name or IP address which indicates to use the TCP network interface. This option will resolve variables.

    TEXT specifies to convert line-ending characters in the file being copied as specified via the FORMAT option and to perform codepage conversion. This option should only be specified for a text file, not a binary file.

    FORMAT specifies the end-of-line character(s) to use. This option will resolve variables. See 8.5.6, "GET FILE" for more information on available formats.

    FAILIFEXISTS specifies that the copy should fail if TOFILE already exists. The default is to replace the file if it exists.

    FAILIFNEW specifies that the copy should fail if TOFILE does not already exist. The default is to create the file if it does not exist.

    Security

    There can be up to three machines involved in a COPY FILE request (and any of these machines can be the same machine):
    1. orgMachine - The machine that submitted (i.e. originated) the COPY FILE request
    2. sourceMachine - The machine where the file to be copied resides (this is the machine to which you submitted the COPY FILE request)
    3. toMachine - The machine where the file will be copied to

    This command requires trust level 4 as follows:

    An exception to these trust requirements is if the orgMachine is the same as the toMachine and the STRICTFSCOPYTRUST operational setting is disabled (which it is by default), then the toMachine does not have to give trust level 4 to the sourceMachine. See 4.7, "Operational parameters" for more information on the STRICTFSCOPYTRUST operational parameter.

    Return Codes

    All return codes from COPY FILE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a COPY FILE command.

    Examples

    In the following examples, assume the command is being submitted locally from machine TestSrv1.

    In the following examples, assume the command is being submitted to machine Client1 from machine TestSrv1.

    8.5.3 COPY DIRECTORY

    COPY DIRECTORY allows you to copy selected files from a directory or entire directories (including subdirectories if needed) between machines, or to another directory on the same machine. It allows you to specify wildcards (e.g. *, ?) in the NAME and/or EXT options to match patterns in file names to be copied from the specified directory and its subdirectories too if the RECURSE option is specified.

    Notes:

    1. A file system entry copied via the FS service does not retain its system or extended attributes.
    2. The types of entries supported by a COPY DIRECTORY request are files and directories.
    3. If a file system entry copied via the FS service is a symbolic link, the entry referenced by the link will be copied (not the symbolic link itself).
    4. The FS service supports copying a file whose size is less than 4 GB on most platforms, assuming the operating system supports the creation of large files, that is, files larger than 2 GB.

    Syntax

    COPY DIRECTORY <Name> [TODIRECTORY <Name>] [TOMACHINE <Machine>]
         [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
         [TEXTEXT <Pattern>... [FORMAT <Format>]]
         [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]]
         [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
    

    DIRECTORY specifies the name of the source directory to copy. This option will resolve variables.

    TODIRECTORY specifies the name of the destination directory. This defaults to the same, unresolved, name as specified in DIRECTORY. This option will resolve variables. These variables will be resolved on the target machine.

    TOMACHINE specifies the machine to copy the directory and its contents to. This defaults to the machine which originated the request. Specifying local indicates to copy the directory and its contents to the same machine that the directory is being copied from. Note that specifying local instead of the from machine's host name can significantly improve performance, especially if your TCP network performance is slow. This is because local (or local://local) indicates to use the local network interface versus specifying a TCP host name or IP address indicates to use the TCP network interface. This option will resolve variables.

    NAME specifies a pattern used to match the name of files in the specified directory (and files in its subdirectories, if RECURSE is specified). Only the files whose names match this pattern will be copied. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of files in the specified directory (and files in its subdirectories, if RECURSE is specified). Only the files whose extensions match this pattern will be copied. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    Note: The COPY DIRECTORY command recognize the "name" (NAME) portion of a filename as the character(s) that precede a period (or the entire filename if it does not include a period) and the "extension" (EXT) portion of a filename are character(s) that follow a period. For example, for filename myfile.txt the "name" portion is "myfile" and the "extension" portion is "txt". To match filenames whose name begins with "my" and whose extension is "txt", you could specify options NAME my* EXT txt.

    CASESENSITIVE specifies that the patterns specified by NAME, EXT, and TEXTEXT are to be matched in a case sensitive manner.

    CASEINSENSITIVE specifies that the patterns specified by NAME, EXT, and TEXTEXT are to be matched in a case insensitive manner.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE. Options CASESENSITIVE and CASEINSENSITIVE only have an effect if you also specify a pattern to match using at least one of the following options: NAME, EXT, or TEXTEXT.

    TEXTEXT specifies a pattern used to match the extension of text files being copied. The files whose extensions match this pattern should contain text, not binary data. The line-ending characters in the files being copied whose extensions match this pattern will be converted as specified via the FORMAT option and codepage conversion will be performed. Multiple TEXTEXT patterns are handled as an "or" condition. Match patterns may be specified using special characters '*' and/or '?' as wildcards. This option will resolve variables.

    FORMAT specifies the end-of-line character(s) to use. This option will resolve variables. See 8.5.6, "GET FILE" for more information on available formats.

    RECURSE specifies that the subdirectories in DIRECTORY will be recursively copied.

    KEEPEMPTYDIRECTORIES specifies that the empty directories are also to be created in the TODIRECTORY on the target. The default behavior is to prune the empty directories while copying files.

    ONLYDIRECTORIES specifies that the directory (empty directories and no files copied) structure is to be created in the TODIRECTORY on the target machine. Using the NAME, EXT, CASESENSITIVE and CASEINSENSITIVE options with the ONLYDIRECTORIES option will be ignored as no files will be copied.

    IGNOREERRORS specifies that errors encountered copying entries should not be returned. By default, all errors encountered while copying entries will be returned in the result buffer.

    FAILIFEXISTS specifies that the copy should fail if TODIRECTORY already exists. The default is to copy over the directory contents if it exists.

    FAILIFNEW specifies that the copy should fail if TODIRECTORY does not already exist. The default is to create the directory if it does not exist if at least one file is copied.

    Security

    There can be up to three machines involved in a COPY DIRECTORY request (and any of these machines can be the same machine):
    1. orgMachine - The machine that submitted (i.e. originated) the COPY DIRECTORY request
    2. sourceMachine - The machine where the directory to be copied resides (this is the machine to which you submitted the COPY DIRECTORY request)
    3. toMachine - The machine where the directory will be copied to

    This command requires trust level 4 as follows:

    An exception to these trust requirements is if the orgMachine is the same as the toMachine and the STRICTFSCOPYTRUST operational setting is disabled (which it is by default), then the toMachine does not have to give trust level 4 to the sourceMachine. See 4.7, "Operational parameters" for more information on the STRICTFSCOPYTRUST operational parameter.

    Return Codes

    All return codes from COPY DIRECTORY are documented in Appendix A, "API Return Codes".

    Results

    Examples

    In the following examples, assume the command is being issued locally from machine TestSrv1.

    In the following examples, assume the command is being issued locally from machine TestSrv1 and the following directory structures exist under the c:/testcase directory:

      c:\testcase
      c:\testcase\error.txt
      c:\testcase\web.exe
      c:\testcase\web.txt
      c:\testcase\web.xml
      c:\testcase\subdir
      c:\testcase\subdir\subdir_1
      c:\testcase\subdir\subdir_2
      c:\testcase\subdir\subdir_2\readme.txt
    

    In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.

    8.5.4 MOVE FILE

    MOVE FILE allows you to rename a file or move files from one directory to another directory on a machine.

    Notes:

    1. A file moved via the FS service retains its system or extended attributes.
    2. The FS service uses the operating system's move command to move files. If moving a file on Windows, the 'move' command is used. If moving a file on Unix, the 'mv' command is used.

    Syntax

    MOVE FILE <Name> <TOFILE <Name> | TODIRECTORY <Name>>
    

    FILE specifies the name of the file to move/rename. You may specify wildcards using '*' to move multiple files from one directory to another directory. This option will resolve variables.

    TOFILE specifies the new name of the file. The directory path specified must already exist, or else the move request will fail (e.g. if specify C:\Tests\Test1\test1.exe, directory C:\Tests\Test1 must already exist). Existing destination files will be overwritten. This option will resolve variables.,

    TODIRECTORY specifies the name of the directory to move the file(s) to. This directory must already exist. Existing destination files will be overwritten. This option will resolve variables.

    Security

    This command requires trust level 4

    Return Codes

    All return codes from MOVE FILE are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain no data or may contain information about the files moved (e.g. if a wildcard is specified in the FILE value). If the request failed, the result buffer may contain information about the error.

    Examples

    8.5.5 MOVE DIRECTORY

    MOVE DIRECTORY allows you to rename a directory on a machine.

    Notes:

    1. A file moved via the FS service retains its system or extended attributes.
    2. The FS service uses the operating system's move command to move files. If moving a file on Windows, the 'move' command is used. If moving a file on Unix, the 'mv' command is used.

    Syntax

    MOVE DIRECTORY <Name> TODIRECTORY <Name>
    

    DIRECTORY specifies the name of the directory to move. This option will resolve variables.

    TODIRECTORY specifies the name of the directory to move the directory to. If this directory does not already exist, the directory will be renamed to it. If this directory already exists, the directory will be moved to a new subdirectory within it. The path to the directory must already exist, or else the move request will fail (e.g. if specify C:\Tests\Test1, directory C:\Tests must already exist). This option will resolve variables.

    Security

    This command requires trust level 4

    Return Codes

    All return codes from MOVE DIRECTORY are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain no data or may contain information about the files moved. If the request failed, the result buffer may contain information about the error.

    Examples

    8.5.6 GET FILE

    GET FILE retrieves the contents of a text file.

    Notes:

    1. If the file specified is a symbolic link, the contents of the entry referenced by the link will be retrieved.

    2. Since the entire content of a returned file is stored in the result string, if you attempt to get the contents of a very large file, you may run out of memory so using the GET FILE request is not recommended for large files. To help prevent this problem, you can specify a maximum size for a file returned by this request by setting the MAXRETURNFILESIZE operational parameter in the STAF configuration file on the machine where the file resides, or by setting the STAF/MaxReturnFileSize variable in the request variable pool of the handle that submitted the request. The lowest of these two values is used as the maximum return file size (not including 0 which indicates no limit).

    Syntax

    GET FILE <FileName> [[TEXT | BINARY] [FORMAT <Format>]]
    

    FILE specifies the name of the text file to get. This option will resolve variables.

    TEXT specifies to convert line-ending characters in the file being retrieved as specified via the FORMAT option and to perform codepage conversion. This option should only be specified for a text file, not a binary file. This is the default.

    BINARY specifies to retrieve the contents of the file in binary.

    FORMAT specifies the format of the file's contents. This option will resolve variables.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from GET FILE are documented in Appendix A, "API Return Codes".

    Notes:

    1. If return code 58 (Maximum Size Exceeded) is returned, that indicates that the file size exceeded the maximum return file size specified.

    2. If return code 39 (Converter Error) is returned, see section 2.7.2, "Codepage Converter Error on a FS GET FILE Request" for more information on this error.

    Results

    On successful return, the result buffer will contain the contents of the specified file.

    Examples

    8.5.7 GET ENTRY

    GET ENTRY retrieves an attribute of a file system entry, such as its type, size, last modification time, link target, or checksum.

    Syntax

    GET ENTRY <Name> <TYPE | SIZE | MODTIME | LINKTARGET | CHECKSUM [<Algorithm>]>
    

    ENTRY specifies the name of the file system entry for which to retrieve an attribute. This option will resolve variables.

    TYPE specifies the type of the file system entry should be retrieved.

    SIZE specifies the size of the file system entry should be retrieved. Note that if the file system entry is a directory, it retrieves the size of only the directory entry, not the total size of all the entries within the directory. To get the total size of a directory, use the FS service's LIST DIRECTORY request with the SUMMARY option.

    MODTIME specifies the last modification time of the file system entry should be retrieved.

    LINKTARGET specifies the link target for the file system entry should be retrieved. If the file system entry is not a symbolic link, <None> will be returned.

    CHECKSUM specifies to calculate a fixed-size checksum of the file system entry and return its value in a hexadecimal form. Getting a file's checksum is a simple way to check to see that a file has not been tampered with or to verify that a file has been downloaded or copied correctly. You may optionally specify the cryptographic hashing algorithm used to produce a unique checksum for any file. The following algorithms are supported: MD2, MD4, MD5, RIPEMD160, SHA, SHA1 (case-insensitive). The default is MD5. Note that SHA1 (160 bits) and RIPEMD160 (160 bits) are considered more current and more secure than MD5 (128 bits), but MD5 is still widely used. You cannot retrieve the checksum for a directory. This option will resolve variables.

    If the file system entry is a symbolic link, information about the entry referenced by the link (e.g. the link target) will be provided. This includes the type, size, last modification time, or checksum of the link target.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET ENTRY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the contents of the result buffer will depend on the attribute type requested.

    Examples

    8.5.8 QUERY

    QUERY retrieves all associated attributes of a file system entry.

    Note that if the file system entry queried is a symbolic link, information about the entry referenced by the link will be retrieved.

    Syntax

    QUERY ENTRY <Name>
    

    ENTRY specifies the name of the file system entry to query. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a QUERY request will contain a marshalled <Map:STAF/Service/FS/QueryInfo> representing information about the file system entry attributes. The map is defined as follows:

    Table 18. Definition of map class STAF/Service/FS/QueryInfo
    Description: This map class represents information about a file system entry attributes.
    Key Name Display Name Type Format / Value
    name Name <String>
    linkTarget Link Target <String> | <None>
    type Type <String>
    size Size <String>
    upperSize Upper 32-bit Size <String>
    lowerSize Lower 32-bit Size <String>
    lastModifiedTimestamp Modified Date-Time <String> <YYYYMMDD-HH:MM:SS>
    Notes: The values for "Link Target", "Type", "Size", "Upper 32-bit Size", "Lower 32-bit Size", and "Last Modification Time" are formatted as specified in section 8.5.7, "GET ENTRY".

    Examples

    8.5.9 LIST DIRECTORY

    LIST DIRECTORY lists the selected contents of a directory, or provides summary information for the selected contents of a directory (e.g. total size, number of files and subdirectories).

    Syntax

    LIST DIRECTORY <Name> [RECURSE] [LONG [DETAILS] | SUMMARY] [TYPE <Types>]
         [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
         [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]     
    

    DIRECTORY specifies the name of the directory to list. This option will resolve variables.

    RECURSE specifies that any subdirectories will be recursively listed.

    LONG specifies to list the selected contents of the directory in a long format. That is, the list of child entries should include their name, type, size, last modification time, and link target. By default, it returns a list that only includes the name of the entry if neither the LONG nor SUMMARY option is specified.

    DETAILS specifies to provide more details about the child entries in the list. Specifically, the upper 32-bit size and lower 32-bit size will be shown in separate fields and the size will be shown in bytes instead of rounding the size in kilobytes or megabytes.

    SUMMARY specifies to provide only a summary of the selected contents of the directory including its total size in bytes, number of files, and number of subdirectories.

    TYPE specifies the types of child entries to return. These types are the same types described in section 8.5.7, "GET ENTRY", with the addition of '!', which, when specified along with 'D', includes the special directories '.' and '..'. You may also specify the string "ALL" to include all entry types. By default, only files and non-special directories are included. This option will resolve variables.

    NAME specifies a pattern used to match the name of child entries in the specified directory (and child entries in its subdirectories, if the RECURSE option is specified). Only child entries whose name match this pattern will be listed. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of child entries in the speciifed directory (and child entries in its subdirectories if the RECURSE option is specified). Only child entries whose extension match this pattern will be listed. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    Note: The LIST DIRECTORY command recognizes the "name" (NAME) portion of a filename as the character(s) that precede a period (or the entire filename if it does not include a period) and the "extension" (EXT) portion of a filename are character(s) that follow a period. For example, for filename myfile.txt the "name" portion is "myfile" and the "extension" portion is "txt". To match filenames whose name begins with "my" and whose extension is "txt", you could specify options NAME my* EXT txt.

    CASESENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case sensitive manner. It also affects the sorting performed by SORTBYNAME.

    CASEINSENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case insensitive manner. It also affects the sorting performed by SORTBYNAME.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE.

    SORTBYNAME specifies that the list of child entries should be sorted by their name.

    SORTBYSIZE specifies that the list of child entries should be sorted by their size.

    SORTBYMODTIME specifies that the list of child entries should be sorted by their last modification time.

    Note: If none of the sorting options is used, the default is not to sort the list. It will be in the same order as returned by the operating system, which is not guaranteed to perform any sorting of its own.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST DIRECTORY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the contents of the specified directory as follows:

    Examples

    8.5.10 LIST COPYREQUESTS

    LIST COPYREQUESTS displays the File System copy requests currently in progress.

    Syntax

    LIST   COPYREQUESTS [LONG] [INBOUND] [OUTBOUND]
           [FILE [[BINARY] [TEXT]]] [DIRECTORY[
    

    COPYREQUESTS specifies to list the COPY requests currently in progress.

    LONG specifies to list more detailed information about the copy requests, such as the copy mode and current state of the copy request.

    INBOUND specifies to list COPY requests that are copying to the machine.

    OUTBOUND specifies to list COPY requests that are copying from the machine.

    FILE specifies to list COPY FILE requests.

    BINARY specifies to list COPY FILE requests that are copying a file in binary format.

    TEXT specifies to list COPY FILE requests that are copying a file in text format.

    DIRECTORY specifies to list COPY DIRECTORY requests.

    If none of the optional options are specified (other than a LONG option), all of the copy requests currently in progress will be shown.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST COPYREQUESTS are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a list of the copy requests currently in progress as follows:

    Examples

    8.5.11 LIST SETTINGS

    LIST SETTINGS shows the operational settings for the FS service.

    Syntax

    LIST SETTINGS     
    

    SETTINGS specifies that you want to list the current operational settings for the FS service.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST SETTINGS are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a marshalled <Map:STAF/Service/FS/Settings> representing the current settings for the File System service. The map is defined as follows:

    Table 27. Definition of map class STAF/Service/FS/Settings
    Description: This map class represents the operational settings for the File System service.
    Key Name Display Name Type Format / Value
    strictFSCopyTrust Strict FS Copy Trust <String> 'Enabled' | 'Disabled'

    Examples

    8.5.12 CREATE

    CREATE creates a directory.

    Syntax

    CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
    

    DIRECTORY specifies the name of the directory to create. This option will resolve variables.

    FULLPATH specifies that any intermediate parent directories should be created if they don't exist.

    FAILIFEXISTS specifies that the request should generate an error if the specified directory already exists. By default, the request will succeed if the specified directory already exists.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from CREATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples

    8.5.13 DELETE

    DELETE deletes selected file system entries.

    Note that if a file system entry being deleted is a symbolic link, the symbolic link will be deleted, not the entry referenced by the link.

    Syntax

    DELETE ENTRY <Name> CONFIRM [RECURSE] [IGNOREERRORS]
           [ CHILDREN [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>]
                      [CASESENSITIVE | CASEINSENSITIVE] ]
    

    ENTRY specifies the name of the file system entry to delete. This option will resolve variables.

    CHILDREN specifies that only children matching NAME, EXT, and TYPE should be deleted. The entry itself will not be deleted.

    NAME specifies a pattern used to match the name of child entries. Only child entries whose name match this pattern will be deleted. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of child entries. Only child entries whose extension match this pattern will be deleted. Match patterns may be specified using special characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.

    Note: The DELETE command recognizes the "name" (NAME) portion of a file system name as the character(s) that precede a period (or the entire name if it does not include a period) and the "extension" (EXT) portion of a file system name are character(s) that follow a period. For example, for file system name myfile.txt, the "name" portion is "myfile" and the "extension" portion is "txt". To match file system names whose name begins with "my" and whose extension is "txt", you could specify options NAME my* EXT txt.

    TYPE specifies the types of child entries to delete. These types are the same types described in section 8.5.7, "GET ENTRY". You may also specify the string "ALL" to delete all entry types. By default, all entry types are deleted. This option will resolve variables.

    CASESENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case sensitive manner.

    CASEINSENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case insensitive manner.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE.

    RECURSE specifies that the entry's children will be recursively deleted.

    Note: If neither CHILDREN nor RECURSE is used, only the entry itself will be deleted. If RECURSE is specified without CHILDREN then the entry and all of its children will be deleted. If RECURSE and CHILDREN are specified, then only the children matching the specified NAME, EXT, and TYPE will be deleted (i.e., the entry itself will not be deleted).

    IGNOREERRORS specifies that errors encountered (recursively) deleting children should not be returned. By default, all errors encountered while (recursively) deleting children will be returned in the result buffer.

    CONFIRM indicates that you really want the deletion to occur.

    Security

    This command requires trust level 4. If you specify RECURSE, you must have trust level 5.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    Examples

    8.5.14 SET

    The SET command allows you to change the operational parameters for the File System service dynamically (without stopping/restarting STAF) which is important for STAF machines that must be continuously available.

    Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.

    Syntax

    SET  STRICTFSCOPYTRUST <Enabled | Disabled>
    

    See section 4.7, "Operational parameters" for a description of this option. Note that setting STRICTFSCOPYTRUST Enabled is equivalent to setting the STRICTFSCOPYTRUST operational parameter in the STAF configuration file. Setting STRICTFSCOPYTRUST Disabled is equivalent to not setting the STRICTFSCOPYTRUST operational parameter in the STAF configuration file.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a successful SET command.

    Examples


    8.6 Handle Service

    8.6.1 Description

    The HANDLE service is one of the internal STAF services. It provides the following commands.

    8.6.2 CREATE

    CREATE creates a static handle. A static handle is a handle which can be shared by several processes on the same system. This is most directly useful for shell-scripts which rely on the STAF command, and need to ensure that the same handle is used for every request. See "Using the STAF command from shell-scripts" for more information on how to use static handles with the STAF command.

    Note: Be sure to DELETE any static handles you create via the CREATE command.

    Syntax

    CREATE HANDLE NAME <Handle Name>
    

    NAME specifies the registered name of the handle.

    Security

    This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from CREATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the new handle number.

    Examples

    8.6.3 DELETE

    DELETE deletes a static handle.

    Syntax

    DELETE HANDLE <Number>
    

    HANDLE specifies the handle number to delete.

    Security

    This command requires trust level 5.

    Note: This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples

    8.6.4 LIST

    LIST allows you to display brief information about all handles, or about groups of handles by name or state. Note that if you do not specify a set of states to display, it will show only those that are in REGISTERED, INPROCESS, and STATIC states. To see all processes, specify PENDING, REGISTERED, INPROCESS, and STATIC. You can also display summary information about handles using the SUMMARY option.

    Syntax

    LIST [ HANDLES <[NAME <Handle Name>] [LONG] [PENDING] [REGISTERED]
                    [INPROCESS] [STATIC]> | [SUMMARY] ]
    

    HANDLES specifies that you want to list information about handles.

    NAME specifies that you only want information on handles with the name <Handle Name>.

    LONG specifies to list more detailed information on the handles, such as the process id (PID) used by each handle.

    PENDING shows handles that are in a pending state. A handle is in pending state when a process has been started via the PROCESS service, but that process has not yet registered with STAF.

    REGISTERED shows handles that are registered with STAF.

    INPROCESS shows handles for external services that are running within the same process as STAFProc.

    STATIC shows static handles. A static handle is a handle which was created using the CREATE command of the HANDLE service or by using the STATICHANDLENAME option when starting a process through the PROCESS service.

    SUMMARY specifies that you want summary information about handles such as the number of active handles, the total number of handles that have been created/registered since STAFProc was started, the number of times the handle number has been reset, the handle number range, and the maximum number of active handles.

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a list of the handles as follows:

    Examples

    8.6.5 QUERY

    QUERY will allow you to display detailed information about a given handle number.

    Syntax

    QUERY HANDLE <Handle>
    

    HANDLE specifies the handle number you want information on. This option will resolve variables.

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a marshalled <Map:STAF/Service/Handle/QueryHandle> representing the handles, handle name, state, last used date and time, operating system process id, authenticator, and user identifier. The map is defined as follows:

    Table 31. Definition of map class STAF/Service/Handle/QueryHandle
    Description: This map class represents status of a handle.
    Key Name Display Name Type Format / Value
    handle Handle <String>
    name Handle Name <String> | <None>
    state State <String>
    lastUsedTimestamp Last Used Date-Time
    (Last Used)
    <String> <YYYYMMDD-HH:MM:SS>
    pid PID <String>
    user User <String> <Authenticator>://<UserID>
    instanceUUID Instance UUID <String>
    Notes:
    1. The "PID" value will contain the process id assigned by the operating system. The process id for a static handle that is not associated with a process will be 0.
    2. The "User" value for handles that are not authenticated will be 'none://anonymous'.
    3. The "Instance UUID" value contains the STAF Universally Unique ID that uniquely identifies a STAF instance.

    Examples

    8.6.6 AUTHENTICATE

    AUTHENTICATE authenticates the handle submitting the request. An authenticated handle has the specified user identifier and authenticator associated with it.

    Syntax

    AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials>
                 [AUTHENTICATOR <Name>]
    

    USER specifies the user identifier to authenticate.

    CREDENTIALS specifies the credentials for the user identifier, such as a password. This option will handle private data.

    AUTHENTICATOR specifies the name of the Authenticator to use to authenticate the handle instead of the default Authenticator.

    Security

    This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from AUTHENTICATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples

    8.6.7 UNAUTHENTICATE

    UNAUTHENTICATE un-authenticates the handle submitting the request. An unauthenticated handle has user 'none://anonymous' associated with it.

    Syntax

    UNAUTHENTICATE
    

    Security

    This command requires trust level 5.

    Note: This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from UNAUTHENTICATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples


    8.7 Help Service

    8.7.1 Description

    The Help service is one of the internal STAF services. It allows you to obtain information about the return codes generated by STAF services.

    Note: Error codes of 4000 and beyond are service specific return codes, and not all external services register their return codes with the Help service. Therefore, if you don't find information on a 4000+ return code returned by a service, be sure to check the documentation provided with the service.

    The Help service provides the following commands.

    8.7.2 LIST

    Allows you to list the information managed by the Help service, including

    Syntax

    LIST SERVICES | [SERVICE <Service name>] ERRORS
    

    SERVICES will list all the services that have registered their return codes with the Help service.

    SERVICE specifies that return codes for the specified service should be listed, as opposed to the common return codes.

    ERRORS will list return codes and a short description of each.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the request based on the options specified:

    Examples

    8.7.3 ERROR

    Display help information for a particular return code.

    Syntax

    [SERVICE <Service name>] ERROR <Return code>
    

    SERVICE indicates that only information specific to the given service should be return. Otherwise, information will be returned for all services which have registered the indicated return code.

    ERROR specifies the return code about which you want information

    Security

    This command requires trust level 2.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the request based on the options specified:

    Examples

    8.7.4 REGISTER

    Allows a service to register return codes with the Help service.

    Syntax

    REGISTER SERVICE <Service name> ERROR <Return code>
             INFO <String> DESCRIPTION <String>
    

    SERVICE indicates the service for which to register information

    ERROR indicates the return code for which to register information

    INFO specifies a short description string which is displayed when using the Help service's LIST command.

    DESCRIPTION specifies the full information about the return code. This information is displayed when using the Help service's ERROR command.

    Security

    This command requires trust level 3.

    This command is only valid when issued by local services.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty.

    Examples

    8.7.5 UNREGISTER

    Allows a service to unregister return codes with the Help service.

    Syntax

    UNREGISTER SERVICE <Service name> ERROR <Return code>
    

    SERVICE indicates the service for which to unregister information

    ERROR indicates the return code for which to unregister information

    Security

    This command is only valid when issued by local services.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty.

    Examples

    8.7.6 Help Error Code Reference

    All return codes from Help are documented in Appendix A, "API Return Codes".


    8.8 LifeCycle Service

    8.8.1 Description

    The LifeCycle service is one of the internal STAF services. It allows STAF service requests to be run when STAFProc starts up or shuts down.

    The LifeCycle service provides the following commands.

    The registrations for the LifeCycle service are persistent. This means that if STAF is shutdown and restarted (or if the machine is rebooted), the prior registration information for the LifeCycle service will still exist. When STAFProc starts, it reads in the existing registration data and executes the enabled registered STAF service requests with the "Startup" phase specified. When STAFProc is shutdown, it reads in the existing registration data and executes the enabled registered STAF service requests with the "Shutdown" phase specified. The LifeCycle service's registration data is stored in file {STAF/DataDir}/service/lifecycle/lifecycle.reg.

    The STAF LifeCycle service maintains a STAF machine log where it writes information about the STAF service requests that have been registered with the LifeCycle service and that it has submitted. When debugging a problem with a registration for the LifeCycle service, be sure to check the LifeCycle service log to determine the results of STAF service requests submitted by the LifeCycle service. See 8.8.11, "LifeCycle Service Logging" for more information on the LifeCycle service log.

    8.8.2 REGISTER

    Allows you to register STAF service requests to be run either when STAFProc starts up or shuts down.

    Each STAF service request that is registered will be submitted synchronously when STAFProc starts up or shuts down, or is triggered via a TRIGGER request. This means that if you register a STAF service request that never completes (e.g. a PROCESS START WAIT request without a TIMEOUT option for a command that never completes, or a SEM MUTEX REQUEST request with a TIMEOUT option for a mutex semaphore that never becomes available), then if registered for the Startup phase, STAFProc will not complete starting up. Or, if registered for the Shutdown phase, STAFProc will not complete shutting down.

    Syntax

    REGISTER PHASE <Startup | Shutdown>
             MACHINE <Machine> SERVICE <Service> REQUEST <Request>
             [ONCE] [PRIORITY <Priority>] [DESCRIPTION <Description>]
    

    PHASE specifies when the service request will be submitted. Valid values are "Startup" and "Shutdown" (case-insensitive). Specifying "Startup" indicates to submit the service request when STAFProc starts up. Specifying "Shutdown" indicates to submit the service request when STAFProc shuts down. This option will resolve variables.

    MACHINE specifies the endpoint for a machine where the service request will be submitted.

    SERVICE specifies the name of the STAF service to which a request will be submitted.

    REQUEST specifies the request to be submitted to the specified service.

    ONCE specifies that the STAF service request should only be executed once. After the STAF service request has been submitted at Startup or Shutdown (depending on the specified phase), the ID for this request will be unregistered.

    PRIORITY specifies the priority of the registration which is used in determining the order in which the registration will be submitted (if there is more than one registration) when STAFProc starts up or shuts down. It must be a number from 1 to 99. The default is 50. Registrations with priority 1 will be submitted first, followed by registrations with priority 2, and so on. Registrations with the same priority will be submitted in order by registration ID. This option will resolve variables.

    DESCRIPTION specifies a description of the registration. It is for informational purposes only and is optional.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain the registration ID.

    Examples

    8.8.3 UNREGISTER

    Allows you to unregister STAF service requests with the LifeCycle service.

    Syntax

    UNREGISTER ID <Registration ID>
    

    ID specifies the registration ID of the STAF service request to be unregistered.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty.

    Examples

    8.8.4 UPDATE

    Allows you to update one or more fields for a registration.

    Syntax

    UPDATE ID <Registration ID> [PRIORITY <Priority>] [ONCE <True | False>]
              [MACHINE <Machine>] [SERVICE <Service>] [REQUEST <Request>]
              [PHASE <Startup | Shutdown>] [DESCRIPTION <Description>]
    

    ID specifies the registration ID of the STAF service request to be updated.

    PRIORITY specifies the priority of the registration which is used in determining the order in which the registration will be submitted (if there is more than one registration) when STAFProc starts up or shuts down. It must be a number from 1 to 99. Registrations with priority 1 will be submitted first, followed by registrations with priority 2, and so on. Registrations with the same priority will be submitted in order by registration ID. This option will resolve variables.

    ONCE specifies whether the STAF service request should only be executed once. Valid values are "True" and "False" (case-insensitive). Specifying "True" indicates to submit the STAF service request only once which means after the STAF service request has been submitted at Startup or Shutdown (depending on the specified phase), this registration will be unregistered. Specifying "False" indicates that the STAF service request should be submitted each time STAFProc starts up or shuts down (depending on the specified phase). This option will resolve variables.

    MACHINE specifies the endpoint for a machine where the service request will be submitted.

    SERVICE specifies the name of the STAF service to which a request will be submitted.

    REQUEST specifies the request to be submitted to the specified service.

    PHASE specifies when the service request will be submitted. Valid values are "Startup" and "Shutdown" (case-insensitive). Specifying "Startup" indicates to submit the service request when STAFProc starts up. Specifying "Shutdown" indicates to submit the service request when STAFProc shuts down. This option will resolve variables.

    DESCRIPTION specifies a description of the registration. It is for informational purposes only and is optional.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty.

    Examples

    8.8.5 LIST

    Allows you to list the information about the STAF service requests registered with the LifeCycle service. The registrations will be listed in the order in which they will be submitted, which is by phase (Startup registrations first, followed by Shutdown registrations), and then in ascending order by priority within the same phase, and then in ascending order by registration ID within the same phase/priority.

    Syntax

    LIST [PHASE <Startup | Shutdown>] [LONG]
    

    PHASE specifies to list only the registrations with a matching phase. Valid values for "Startup" and "Shutdown" (case-insensitive). This option will resolve variables.

    LONG specifies to include all of the registration information, including the description for each registration.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the request based on the options specified:

    Examples

    8.8.6 QUERY

    Allows you to get information about a STAF service request registered with the LifeCycle service.

    Syntax

    QUERY ID <Registration ID>
    

    ID specifies the registration ID of the STAF service request to be queried. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain a marshalled <Map:STAF/Service/LifeCycle/RegQuery> representing information about the registration. The map is defined as follows:

    Table 37. Definition of map class STAF/Service/LifeCycle/RegQuery
    Description: This map class represents information about a registration.
    Key Name Display Name Type Format / Value
    phase Phase <String> 'Startup' | 'Shutdown'
    priority Priority <String> '1' - '99'
    id ID <String>
    state State <String> 'Enabled' | 'Disabled'
    machine Machine <String>
    service Service <String>
    request Request <String> Private data will be masked
    description Description <String> | <None>
    once Once <String> 'True' | 'False'

    Examples

    8.8.7 TRIGGER

    Allows you to submit a single registered STAF service request, or to submit all STAF service requests registered to be run at the Startup or Shutdown phase. It is useful for testing the registrations without requiring that STAFProc be started or shutdown.

    Only enabled STAF requests will be submitted by a TRIGGER PHASE request. A TRIGGER ID request will submit enabled and disabled STAF requests. Each STAF service request that is triggered will be submitted synchronously (e.g. waits for the STAF service request to complete) before returning or submitting the next STAF service request if the PHASE option was specified and there are more STAF service requests registered for the specified phase. This means that if you register a STAF service request that never completes (e.g. a PROCESS START request using the WAIT option but not the TIMEOUT option, or a SEM MUTEX REQUEST request without a TIMEOUT option for a mutex semaphore that never becomes available), then the TRIGGER request will never complete. Note that if the submitted STAF service request was registered with the ONCE option, triggering the STAF command will not cause the registration to be unregistered.

    Syntax

    TRIGGER <ID <Registration ID> { PHASE <Startup | Shutdown>> CONFIRM
    

    ID specifies the registration ID of the STAF service request to be triggered. This option will resolve variables.

    PHASE specifies to trigger all the registrations with a matching phase. Valid values are "Startup" and "Shutdown" (case-insensitive). This option will resolve variables.

    CONFIRM specifies you really want to trigger submitting the STAF service requests specified by the matching registration(s).

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the request based on the options specified:

    Examples

    8.8.8 ENABLE

    Allows you to enable a registration for the LifeCycle service. This means that the STAF service request for this registration will be submitted when STAFProc starts up or shuts down (depending on the phase specified for the registration).

    Syntax

    ENABLE ID <Registration ID>
    

    ID specifies the registration ID which is to be enabled.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already enabled.

    Examples

    8.8.9 DISABLE

    Allows you to disable a registration for the LifeCycle service. This means that the STAF service request for this registration will not be submitted when STAFProc starts up or shuts down (depending on the phase specified for the registration).

    Syntax

    DISABLE ID <Registration ID>
    

    ID specifies the registration ID which is to be disabled.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already disabled.

    Examples

    8.8.10 LifeCycle Error Code Reference

    All return codes from the LifeCycle service are documented in Appendix A, "API Return Codes".

    8.8.11 LifeCycle Service Logging

    The STAF LifeCycle service maintains a STAF machine log where it writes information about the STAF service requests that have been registered with the LifeCycle service and that it has submitted. When debugging a problem with a registration for the LifeCycle service, be sure to check the LifeCycle service log to determine the results of STAF service requests submitted by the LifeCycle service.

    The logname for the STAF LifeCycle service is LIFECYCLE. Note that tags like [ID=<id>] in the log entries can be useful when querying the LifeCycle service log by using the CONTAINS option in the LOG QUERY request.

    For example:

    The LifeCycle service will log an entry when the following actions occur:


    8.9 Log Service

    8.9.1 Description

    The Log service is an external STAF service that provides the following functions:

    The purpose of the Log service is to allow a test case to easily and flexibly manage information that needs to be logged. It allows you to specify a log mask which defines which messages actually get logged to the log file. This log mask can be dynamically changed to alter the set of log messages written to the log file(s). This can greatly assist in debugging. For example, while a test case is running, you can dynamically alter the log mask to allow debug and trace log messages to start being logged. The log query mechanism allows for record selection based on many selection criteria matches.

    The Log service can be run in one of two modes. In local mode, all log requests are handled locally, and all log files are stored locally. In remote mode, all log requests are forwarded to a central system for processing. In addition, all log files are stored on the central system. While it is possible to delegate the log service to a central system, this has some unwanted side effects. The primary one being that many unwanted messages are likely to be sent over the network, consuming time and bandwidth.

    The following is an example of the major difference between delegating the Log service and using the Log service in remote logging mode.

    
    Example Delegated Log
     
                                      NETWORK
                start                    ! start
                info                     ! info
                warning                  ! warning
     +------+   trace    +-----------+   ! trace    +-------+
     ! TEST !-> debug -> !   STAF    !-> ! debug -> ! STAF  ! -> WRITE LOG
     ! CASE !   trace    ! DELEGATED !   ! trace    ! LOG   !    =========
     +------+   error    !   LOG     !   ! error    ! Mask= !    error
                debug    +-----------+   ! debug    ! Error !    fail
                trace                    ! trace    ! Fail  !
                debug                    ! debug    +-------+
                fail                     ! fail
     
     
    Example Remote Logging
     
                                     NETWORK
                start                    !
                info                     !
                warning                  !
     +------+   trace    +-----------+   !          +------+
     ! TEST !-> debug -> !  LOG      !-> ! error -> ! STAF ! -> WRITE LOG
     ! CASE !   trace    !  Mask=    !   ! fail     ! LOG  !    =========
     +------+   error    !  Error    !   !          +------+    error
                debug    !  Fail     !   !                      fail
                trace    +-----------+   !
                debug                    !
                fail                     !
    

    In the above Delegated Log service example, all the messages flowed over the network to the ultimate log server even though only error and fail conditions were selected to be logged. In the above Remote Logging example, the selection of the messages occur at the local box and only those messages that are selected get sent over the network to the ultimate log server.

    Note: When using the Log service in remote logging mode, you should have the log mask disabled (i.e. log everything) at the ultimate log server to avoid confusion and multiple log mask filtering.

    8.9.2 Registration

    The Log service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    SERVICE <Name> LIBRARY STAFLog [PARMS <Log parameters>]
    

    <Name> is the name by which the Log service will be known on this machine. The recommended name of the Log service is "LOG"

    <Log parameters> are valid log parameters described below.

    Example

    service log library STAFLog
    service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata ResolveMessage"
    

    8.9.3 Parameters

    The Log service accepts a parameter string in the following formats

    [DIRECTORY <Log Directory Root>]
    [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
    [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
    
    or
    ENABLEREMOTELOGGING REMOTELOGSERVER <Server name>
                        [REMOTELOGSERVICE <Service Name>]
    

    DIRECTORY specifies the root directory under which log files are stored. The default is {STAF/DataDir}/service/<Service Name (lower-case)>.

    Note: Previously, in STAF 2.x, the default root directory was {STAF/Config/STAFRoot}/data/log. So, if you want to continue to use the STAF 2.x log files with the current version of STAF, move the log files to the new default root directory or specify the old root directory for the DIRECTORY parameter.

    MAXRECORDSIZE specifies the maximum length (in characters) of a logged message. The default is 100000.

    DEFAULTMAXQUERYRECORDS specifies the maximum number of records that will be returned if your query criteria selects more records than this number. The default is 100. If no limit on the maximum number of records returned by a query is desired, specify 0. If a non-zero value is specified, it's equivalent to specifying LAST <Number>. This limit is only used if none of the following options are specified on a QUERY request: FIRST, LAST, ALL, TOTAL, or STATS.

    RESOLVEMESSAGE specifies that variables in log messages should be resolved by default.

    NORESOLVEMESSAGE specifies that variables in log messages should not be resolved by default. This is the default.

    ENABLERESOLVEMESSAGEVAR specifies that the log service should check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. This option will adversely affect the performance of the Log service. See below for more information.

    DISABLERESOLVEMESSAGEVAR specifies that the log service should not check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. See below for more information. This is the default.

    ENABLEREMOTELOGGING specifies that the Log service should operate in remote/forwarding mode.

    REMOTELOGSERVER specifies the server to which forwarded log requests should be sent. This machine must be running STAF V3.0.0 or later.

    Note: From a trust perspective, the tcp interface names on the remote log server and on the machine forwarding requests to it must match or the remote log server must use a wildcard to match any interface in the trust statement for the machine that is forwarding log requests to it.

    REMOTELOGSERVICE specifies the service to which forwarded log requests should be sent. The default is the same name under which the Log service was registered on the local machine.

    Note: All these parameters, with the exception of DIRECTORY, ENABLEREMOTELOGGING, REMOTELOGSERVER, and REMOTELOGSERVICE may be changed with the SET command, see 8.9.10, "SET" for more information.

    8.9.4 Variables

    The following variables will affect the behavior of the Log service.
    STAF/Service/<Name>/Mask: A string of log mask descriptions, or a 32 bit binary mask.
    STAF/Service/<Name>/ResolveMessage: Whether to resolve variables in the message

    STAF/Service/<Name>/Mask

    The variable determines what messages will and will NOT be written to the log file. You can set it to only have FATAL and ERROR messages written to the log file for example, or turn on DEBUG in the middle of a running test. This allows you to put as much informational, trace, debug, status, etc. logging messages into your testcases as you want, but based on the circumstance, dynamically alter the logging levels via configuration, not the testcase.

    See 8.9.11, "Logging Levels Reference" for a complete list of logging levels.

    The log mask contains the set of levels that will actually be logged to the log file.

    Example: set shared var "STAF/Service/Log/Mask=START STOP WARNING FATAL ERROR"
    Default: All logging levels will be logged
    Alternatively, a 32 bit binary string may be specified that determines which logging levels will be applied.
    Example: set shared var STAF/Service/Log/Mask=11111111000000000000000000000000

    STAF/Service/<Name>/ResolveMessage

    This variable determines if messages should be resolved before writing them. If message resolution is desired, then a call to the STAF variable service is made and all variables in the message are resolved. If for any reason the resolution is unsuccessful (e.g. unbalanced braces {}, infinite recursion, etc.) then an error is generated.

    Note: This variable is not checked unless the ENABLERESOLVEMESSAGEVAR option has been set.

    Example: set shared var STAF/Service/Log/ResolveMessage=1
    Default: 0 (messages are NOT resolved)
    If a message was "Machine booted from {STAF/Config/BootDrive}" and STAF/Service/<Name>/ResolveMessage was set to 1 then what would actually be logged would look like: "Machine booted from C:". If STAF/Service/<Name>/ResolveMessage was not defined or set to 0 then the original text of the message would be logged: "Machine booted from {STAF/Config/BootDrive}".

    Note: There are three places where message resolution can be affected. They are evaluated in the following order

    8.9.5 LOG

    Writes data to a log file.

    Syntax

    LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level> MESSAGE <Message>
        [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    GLOBAL indicates you want to write to a global log. The global log is intended to facilitate multiple testcases on multiple machines all writing to a common log.

    MACHINE indicates you want to write to a machine log. The machine log is intended to facilitate multiple testcases on a single machine all writing to a common machine name log.

    HANDLE indicates you want to write to a handle log. The handle log is intended to facilitate each testcase writing to a separate log (no matter how many machines and processes are involved)

    LOGNAME contains the name of the log to which you want to write. This option will resolve variables.

    LEVEL determines the level that you want to log. This can be in the form of level type such as "FATAL", "ERROR", WARNING", etc. or a 32 byte binary string such as "00000000000000000000000000000001". This option will resolve variables. See 8.9.11, "Logging Levels Reference" for a complete list of logging levels.

    MESSAGE contains the message (data) that you want to write to the log. This option will not resolve messages by default but can be configured to do so in the STAF configuration file or by using RESOLVEMESSAGE. Any private data in the message will be masked before writing to the log.

    RESOLVEMESSAGE causes the LOG service to call the STAF variable service to resolve any variables in the message before being written. This overrides any other message resolution settings.

    NORESOLVEMESSAGE causes the LOG service to not call the STAF variable service. This overrides any other message resolution settings.

    Security

    This command requires trust level 3.

    Return Codes

    Results

    The result buffer will contain no data on return from a LOG command.

    Examples

    8.9.6 QUERY

    Allows you to query records from a log based on a set of selection criteria.

    Note: A stand-alone utility also exists, called FmtLog, that can read a log file and write the data to an output file in a readable format. See 9.4, "Format Log Utility" for additional information.

    Syntax

    QUERY  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
           [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
           [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [STARTSWITH <String>]... [CSSTARTSWITH <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
           [FROMRECORD <Num>] [TORECORD <Num>]
           [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG]
           [LEVELBITSTRING]
    

    GLOBAL indicates you want to query to a global log. The global log is intended to facilitate multiple testcases on multiple machines all writing to a common log.

    MACHINE indicates you want to query to a machine log. Specify the machine nickname. The machine log is intended to facilitate multiple testcases on a single machine all writing to a common log. This option will resolve variables.

    HANDLE indicates you want to query to a handle log. The handle log is intended to facilitate each testcase writing to a separate log. This option will resolve variables.

    LOGNAME contains the name of the log you want to query. All log files have the ".log" extension automatically added to the file name. This option will resolve variables.

    LEVELMASK determines the levels that are selected. This can be in the form of "FATAL ERROR WARNING" or a 32 byte bit string such as "00000000000000000000000000000111". This option will resolve variables.

    QMACHINE selects only those records that originated from a certain machine. Multiple QMACHINE statements are handled as an "or" condition. This option will resolve variables.

    QHANDLE selects only those records that are associated with a certain handle. Multiple QHANDLE statements are handled as an "or" condition. This option will resolve variables.

    NAME selects only those records with a certain registered name. Multiple NAME statements are handled as an "or" condition. This option will resolve variables.

    USER selects only those records with a certain user. <User> format is <Authenticator>://<User Identifier> (e.g. none://anonymous, SampleAuth://johnDoe@company.com). Multiple USER statements are handled as an "or" condition. This option will resolve variables.

    ENDPOINT selects only those records with a certain endpoint. Multiple ENDPOINT statements are handled as an "or" condition. This option will resolve variables.

    CONTAINS selects only those records that contain a specified string in the message. Note that this match is case insensitive. Multiple CONTAINS statements are handled as an "or" condition. This option will resolve variables.

    CSCONTAINS selects only those records that contain a specified string in the message. Note that this match is case sensitive. Multiple CSONTAINS statements are handled as an "or" condition. This option will resolve variables.

    STARTSWITH selects only those records that start with a specified string in the message. Note that this match is case insensitive. Multiple STARTSWITH/CSSTARTSWITH statements are handled as an "or" condition. This option will resolve variables.

    CSSTARTSWITH selects only those records that start with a specified string in the message. Note that this match is case sensitive. Multiple CSSTARTSWITH/STARTSWITH statements are handled as an "or" condition. This option will resolve variables.

    FROM selects only those records that have a date and/or time from the specified format. This option will resolve variables.

    AFTER selects only those records that have a date and/or time after the specified format. This option will resolve variables.

    TO selects only those records that have a date and/or time to the specified format. This option will resolve variables.

    BEFORE selects only those records that have a date and/or time before the specified format. This option will resolve variables.

    Note: <Timestamp> format is date, @time, or date@time (e.g. 19980214, @16:30:45, 19980214@16:30:45)

    Note: The keyword TODAY can be used for the current date in the FROM, AFTER, TO, BEFORE options.

    FROMRECORD selects only those records whose record number is greater than or equal to the specified record number (which must be >= 1). This option will resolve variables.

    TORECORD selects only those records whose record number is less than or equal to the specified record number (which must be >= 1). This option will resolve variables.

    FIRST selects only the first <Num> records. This option will resolve variables.

    LAST selects only the last <Num> records. This option will resolve variables.

    ALL selects all the records that meet the query criteria.

    TOTAL display only the total number of records selected instead of the records themselves.

    STATS display the totals for each level instead of the records themselves.

    LONG displays all of the fields for each log record instead of just the timestamp, level, and message fields.

    LEVELBITSTRING displays the selected records with the level displayed as a 32 byte binary bit string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error. See 8.9.11, "Logging Levels Reference" for a complete list of logging levels.

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", QUERY also returns codes documented in 8.9.12, "Log Error Code Reference".

    Results

    If the query criteria selects more records than allowed by the DefaultMaxQueryRecords parameter/setting (and none of the following options are specified: FIRST, LAST, ALL, TOTAL, or STATS), the return code will be set to 4010 and the result buffer will contain only the 'last' default maximum number of query records.

    If successful, the result buffer will contain data based on the QUERY command:

    Examples

    Assume this example log file called STRESSTST contains the following records:

    R# Date-Time         Machine                 H# Name   User             Endpoint                          Level   Message
    -- ----------------- ----------------------  -- ------ ---------------- --------------------------------- ------- ----------------------------------
    1  20070210-18:04:00 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Start   Stress Test 1A Initiated
    2  20070210-19:37:15 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Trace   Step 1: processing time: 01:31:26
    3  20070210-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Debug   Step 1: debug: files=23 threads=37
    4  20070210-22:20:34 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Warning Step 2: File not ready, retry=3
    5  20070210-22:21:01 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Info    Step 2: File ready on retry 3
    6  20070211-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Trace   Step 2: processing time: 03:02:41
    7  20070211-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Debug   Step 2: debug: files=31 threads=54
    8  20070211-01:37:25 crazy8s.austin.ibm.com  41 Test2  none://anonymous tcp://crazy8s.austin.ibm.com@6500 Trace   Step 1: processing time: 03:11:53
    9  20070211-01:43:46 crazy8s.austin.ibm.com  41 Test2  none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug   Step 1: debug: files=43 threads=67
    10 20070211-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Error   Step 3: Sharing buffer exceeded
    11 20070211-02:54:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     User1   Step 3: Error recovery started
    12 20070211-04:32:53 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     User2   Step 3: Error recovery completed
    13 20070211-04:33:49 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Trace   Step 3: processing time: 03:10:41
    14 20070211-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Debug   Step 3: debug: files=78 threads=98
    15 20070211-08:46:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Stop    Stress Test 1A Completed
    16 20070211-08:47:21 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Pass    Stress Test 1A: Errors=1 Recover=1
    17 20070211-08:48:46 automate.austin.ibm.com 37 Test1A none://anonymous local://local                     Status  Step1=P, Step2=P, Step3=W, TC=P
    

    Note: The output for these examples are formatted for ease of reading in this document, the actual format will vary depending on whether the command is submitted via STAF.exe or via a program's submit(), etc. method.

    8.9.7 LIST

    Allows you to list the names of the log files based on a global, machine, or handle location. Also allows you to list current operational settings

    Syntax

    LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLES | HANDLE <Handle>]
    
    or
    LIST SETTINGS
    

    GLOBAL indicates you want to list all global logs.

    MACHINES indicates you want to list all the machines which have created machine logs.

    MACHINE indicates you want to list all the machine logs for the specified machine nickname. This option will resolve variables.

    HANDLES indicates you want to list all the handles that have created handle logs for the given machine.

    HANDLE indicates you want to list all the handle logs for the specified handle of the specified machine. This option will resolve variables.

    SETTINGS indicates you want to list the current operational settings.

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns codes documented in 8.9.12, "Log Error Code Reference".

    Results

    If successful, the result buffer will contain data based on the LIST command:

    Examples

    8.9.8 DELETE

    Delete a log file.

    Syntax

    DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME<Logname> CONFIRM
    

    GLOBAL indicates you want to delete a global log.

    MACHINE indicates you want to delete a machine log. Specify the machine nickname. This option will resolve variables.

    HANDLE indicates you want to delete a handle log. This option will resolve variables.

    LOGNAME contains the name of the log you want to delete. This option will resolve variables.

    CONFIRM confirms you really want to delete the log file.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", DELETE also returns codes documented in 8.9.12, "Log Error Code Reference".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples

    8.9.9 PURGE

    Purge selected records from a log file. The purge command will lock the log file during the entire purge process. It is recommended that you refrain from logging records to a log file that is being purged.

    Syntax

    PURGE  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
           CONFIRM | CONFIRMALL
           [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
           [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [STARTSWITH <String>]... [CSSTARTSWITH <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
           [FROMRECORD <Num>] [TORECORD <Num>]
           [FIRST <Num> | LAST <Num>] 
    

    GLOBAL indicates you want to purge a global log.

    MACHINE indicates you want to purge a machine log. Specify the machine nickname. This option will resolve variables.

    HANDLE indicates you want to purge a handle log. This option will resolve variables.

    LOGNAME contains the name of the log you want to purge. This option will resolve variables.

    CONFIRM confirms you really want to purge the log file, but protects you from deleting all records in the log file accidently.

    CONFIRMALL confirms you really want to purge the log file, even if your purge selection criteria selects every record in the log file.

    Note: If your purge selection criteria selects every record in the log file and you specified the CONFIRM option, you will receive an error indicating you need to use the CONFIRMALL option instead, or you can submit a DELETE request to the LOG service if you really want to delete all records in the log file.

    Purge allows almost the same selection options as Query. See 8.15.9, "QUERY" for a list of valid purge selection options with the exception of TOTAL, STATS, ALL, LONG, and LEVELBITSTRING not allowed.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", PURGE also returns codes documented in 8.9.12, "Log Error Code Reference".

    Results

    If successful, the result buffer will contain a marshalled <Map:STAF/Service/Log/PurgeStats>, representing the number of log records that were purged and the total number of log records. The map is defined as follows:

    Table 46. Definition of map class STAF/Service/Log/PurgeStats
    Description: This map class respresents the purge statistics for the log.
    Key Name Display Name Type Format / Value
    purgedRecords Purged Records <String>
    totalRecords Total Records <String>

    For example, suppose you submitted a PURGE request for a log that contained 129 records and 21 of the records met the purge criteria you specified. If the PURGE request was submitted from the command line, the result could look like:

    Purged Records: 21
    Total Records : 129
    

    Examples

    8.9.10 SET

    The SET command allows you to change the operation parameters of the Log service.

    Syntax

    SET  [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
         [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
         [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    See section 8.9.3, "Parameters" for a description of these options.

    Security

    This command requires trust level 5.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", SET also returns codes documented in 8.9.12, "Log Error Code Reference".

    Results

    The result buffer will contain no data on return from a successful SET command.

    Examples 

    8.9.11 Logging Levels Reference

    Logging levels consist of a 32 byte binary string that represents the level type of each record. You can use the 32 byte binary string or the description of the level type when referencing a level. The following are the valid logging levels along with their appropriate 32 byte binary string:


    Table 47. Logging Levels Reference
    Level Definition 32 Byte Bit String Representation
    Fatal 00000000000000000000000000000001
    Error 00000000000000000000000000000010
    Warning 00000000000000000000000000000100
    Info 00000000000000000000000000001000
    Trace 00000000000000000000000000010000
    Trace2 00000000000000000000000000100000
    Trace3 00000000000000000000000001000000
    Debug 00000000000000000000000010000000
    Debug2 00000000000000000000000100000000
    Debug3 00000000000000000000001000000000
    Start 00000000000000000000010000000000
    Stop 00000000000000000000100000000000
    Pass 00000000000000000001000000000000
    Fail 00000000000000000010000000000000
    Status 00000000000000000100000000000000
    <Reserved1> 00000000000000001000000000000000
    <Reserved2> 00000000000000010000000000000000
    <Reserved3> 00000000000000100000000000000000
    <Reserved4> 00000000000001000000000000000000
    <Reserved5> 00000000000010000000000000000000
    <Reserved6> 00000000000100000000000000000000
    <Reserved7> 00000000001000000000000000000000
    <Reserved8> 00000000010000000000000000000000
    <Reserved9> 00000000100000000000000000000000
    User1 00000001000000000000000000000000
    User2 00000010000000000000000000000000
    User3 00000100000000000000000000000000
    User4 00001000000000000000000000000000
    User5 00010000000000000000000000000000
    User6 00100000000000000000000000000000
    User7 01000000000000000000000000000000
    User8 10000000000000000000000000000000

    Note: The User1-8 logging levels have been set aside for the user of STAFLog to implement as deemed necessary. You may decide that for a testcase or test suite that you want to log a certain behavior as "User1" for example. This will enable you to easily extract log records associated with level "User1".

    Note: The <Reserved1-8> levels cannot be used and as the name implies, they are reserved by STAF for future use. If you would like to see a common logging level added to this list, please contact the document owners for discussion.

    8.9.12 Log Error Code Reference

    In addition to the common STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Log return codes are defined:

    Table 48. Log Service Return Codes
    Error Code Meaning Comment
    4004 Invalid level An invalid logging level was specified. See 8.9.11, "Logging Levels Reference" for a complete list of logging levels.
    4007 Invalid file format An invalid/unknown record format was encountered while reading the log file.
    4008 Unable to purge all log records Your purge criteria selected every record in the log file. Use CONFIRMALL instead of CONFIRM if you really want to delete every record (or submit a DELETE request to the LOG service). Or, modify your purge criteria if you don't want to delete every record.
    4010 Exceeded default maximum query records Your query criteria selected more records than allowed by the DefaultMaxQueryRecords setting. Use the FIRST <Num> or LAST <Num> option to specify the number of records or the ALL option if you really want all of the records.


    8.10 Misc Service

    8.10.1 Description

    The MISC service is one of the internal STAF services. It provides a home for miscellaneous commands.

    8.10.2 VERSION

    VERSION will display the STAF version number that is currently running.

    Syntax

    VERSION
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from VERSION are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the version number.

    Examples

    8.10.3 WHOAMI

    WHOAMI will display information about who a system thinks you are. This can be useful in debugging trust issues and other problems.

    Syntax

    WHOAMI
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from WHOAMI are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a WHOAMI request will contain a marshalled <Map:STAF/Service/Misc/Whoami> representing information about who a system thinks you are. The map is defined as follows:

    Table 49. Definition of map class STAF/Service/Misc/Whoami
    Description: This map class represents information about who a system thinks you are.
    Key Name Display Name Type Format / Value
    instanceName Instance Name <String>
    instanceUUID Instance UUID <String>
    requestNumber Request Number <String>
    interface Interface <String>
    logicalID Logical ID <String>
    physicalID Physical ID <String>
    endpoint Endpoint <String>
    machine Macine <String>
    machineNickname Machine Nickname <String>
    isLocalRequest Local Request <String> 'Yes' | 'No'
    handle Handle <String>
    handleName Handle Name <String>
    user User <String>
    trustLevel Trust Level <String>
    Notes:
    1. The "Instance Name" value contains the STAF instance name that identifies the instance of STAF to which the request is communicating (in case multiple instances of STAF are running. The default STAF instance name is "STAF".
    2. The "Instance UUID" value contains the STAF Universally Unique ID that uniquely identifies a STAF instance.
    3. The format for the "Endpoint" value is <Interface>://<Logical ID>[@<Port>].
    4. The format for the "User" value is <Authenticator>://<User ID>.

    Examples

    8.10.4 WHOAREYOU

    WHOAREYOU will display information about a system, such as the STAF instance name, instance UUID, machine name (the value of the STAF/Config/Machine system variable for the machine), machine nickname, (the value of the STAF/Config/MachineNickname variable for the machine) and if it's the same system as the machine who submitted the request.

    Syntax

    WHOAREYOU
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from WHOAREYOU are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a WHOAREYOU request will contain a marshalled <Map:STAF/Service/Misc/WhoAreYou> representing information about a system. The map is defined as follows:

    Table 50. Definition of map class STAF/Service/Misc/WhoAreYou
    Description: This map class represents information about a system.
    Key Name Display Name Type Format / Value
    instanceName Instance Name <String>
    instanceUUID Instance UUID <String>
    machine Macine <String>
    machineNickname Machine Nickname <String>
    isLocalRequest Local Request <String> 'Yes' | 'No'
    currentTimestamp Current Date-Time <String> <YYYYMMDD-HH:MM:SS>
    Notes:
    1. The "Instance Name" value contains the STAF instance name that identifies the instance of STAF to which the request is communicating (in case multiple instances of STAF are running. The default STAF instance name is "STAF".
    2. The "Instance UUID" value contains the STAF Universally Unique ID that uniquely identifies a STAF instance.

    Examples

    8.10.5 LIST

    LIST allows you to obtain information about the interfaces (aka connection providers) that are enabled for a system, or you can list the current operational settings for STAF, or you can show the cached endpoints used by automatic interface cycling or, or you can list the STAF install properties.

    Syntax

    LIST INTERFACES | SETTINGS | ENDPOINTCACHE | PROPERTIES
    

    INTERFACES specifies that you want information for interfaces.

    SETTINGS specifies that you want to list the current operational settings for STAF.

    ENDPOINTCACHE specifies that you want to show the cached endpoints used by automatic interface cycling.

    PROPERTIES specifies that you want to list the install properties for STAF.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    Examples

    8.10.6 QUERY

    QUERY allows you to obtain detailed information about an enabled interface (aka connection provider).

    Syntax

    QUERY INTERFACE <Name>
    

    INTERFACE specifies the name of the interface you want information on. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a QUERY INTERFACE request will contain a marshalled <Map:STAF/Service/Misc/Interface> representing the specified interface (aka connection provider). The map is defined as follows:

    Table 55. Definition of map class STAF/Service/Misc/Interface
    Description: This map class represents an interface.
    Key Name Display Name Type Format / Value
    name Interface Name <String>
    library Library <String>
    optionMap Options <Map> of <String>
    Notes:
    1. The option names are the keys in the option map.
    2. Valid option names for TCP interfaces are: Port, Protocol, Secure, and ConnectTimeout
    3. Valid option names for the local interface are: IPCName and IPCMethod

    Examples

    8.10.7 SET

    The SET command allows you to change the operational parameters for STAF dynamically (without stopping/restarting STAF) which is important for STAF machines that must be continuously available.

    Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.

    Syntax

    SET  [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
         [MAXQUEUESIZE <Number>] [HANDLEGCINTERVAL <Number>[s|m|h|d]]
         [INTERFACECYCLING <Enabled | Disabled>]
         [DEFAULTINTERFACE <Name>]  [DEFAULTAUTHENTICATOR <Name>]
         [RESULTCOMPATIBILITYMODE <Verbose | None>]
    

    See section 4.7, "Operational parameters" for a description of these options.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a successful SET command.

    Examples

    8.10.8 PURGE

    The PURGE command allows you to purge one or more (or all) of the endpoints from the endpoint cache used by automatic interface cycling.

    Syntax

    PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM>
    

    ENDPOINTCACHE indicates that you want to purge one or more endpoints from the endpoint cache.

    ENDPOINT specifies the endpoint that you want to purge. This option will resolve variables.

    CONFIRM indicates that you really want to purge the entire contents of the endpoint cache.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from PURGE are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain a marshalled <Map:STAF/Service/Misc/PurgeStats>, representing the number of endpoints that were purged and the number of endpoints remaining in the endpoint cache. The map is defined as follows:

    Table 56. Definition of map class STAF/Service/Misc/PurgeStats
    Description: This map class represents the purge statistics for the endpoint cache.
    Key Name Display Name Type Format / Value
    numPurged Purged Endpoints <String>
    numRemaining Remaining Endpoints <String>

    Examples


    8.11 Monitor Service

    8.11.1 Description

    The Monitor service is an external STAF service that provides the following functions: The purpose of the Monitor service is to give a test case the ability to write status messages. This allows someone to query a process or workload and easily get the current status. The status messages are stored based on a combination of the originating machine and the process handle (where only the process can update the status message), or on a combination of the originating machine and a specified monitor name (where any process on the originating machine can update the named monitor). The Monitor service only keeps the last monitor message it receives from a particular machine and process/name. A "centralized network clipboard" is a term that could be used to describe the Monitor service. All Monitor service status messages are lost when STAFProc is shutdown or the Monitor service is dynamically removed.

    8.11.2 Registration

    The Monitor service is written in C and since it is an external service, it must be registered with the SERVICE configuration statement. The syntax is:
    SERVICE <Name> LIBRARY STAFMon PARMS <Parms>
    

    <Name> is the name by which the Monitor service will be known on this machine.

    <Parms> is any parameters that are accepted at initialization time. The same parameters for the Monitor SET command can be specified during initialization time. See the Monitor SET command for details on the available parameters.

    Example

    service Monitor library STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 512"
    

    8.11.3 Variables

    The following variables are defined in the STAF configuration file and Monitor will query their values:
    STAF/Service/<Name>/ResolveMessage: Whether to resolve variables in the message

    STAF/Service/<Name>/ResolveMessage

    This flag determines if messages should be resolved before writing them. If message resolution is desired, then a call to the STAF variable service is made and all variables are resolved. If for any reason the resolution is unsuccessful (i.e. unbalanced braces {}, infinite recursion, etc.) then an error code will be returned.

    Note: Note that this variable will only be examined if the ENABLERESOLVEMESSAGEVAR option is set either during the Monitor registration (via the PARMS options) or by use of the SET ENABLERESOLVEMESSAGEVAR Monitor command.

    Note: The default if STAF/Service/<Name>/ResolveMessage is not specified, is not to resolve messages. This is due to the fact that you can resolve variables yourself before logging messages and the fact that the messages could be quite large. This can be overridden on a per message basis by using the RESOLVEMESSAGE or NORESOLVEMESSAGE option.

    Example: var STAF/Service/<Name>/ResolveMessage=1
    Default: 0
    An example would be a monitor message of "Machine booted from {STAF/Config/BootDrive}", if STAF/Service/<Name>/ResolveMessage was set to 1 then what would actually be logged would look like: "Machine booted from C:". If STAF/Service/Monitor/ResolveMessage was set to 0 then the original text of the message would be logged: "Machine booted from {STAF/Config/BootDrive}".

    8.11.4 LOG

    Writes monitor data.

    Syntax

    LOG MESSAGE <Message> [NAME <Name>] [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    MESSAGE contains the message (data) that you want to write to the monitor. This option will not resolve messages by default but can be configured to do so in the STAF configuration file or by using RESOLVEMESSAGE. Any private data in the message will be masked before writing to the monitor.

    NAME indicates that the status message should be written to the specified named monitor. This option will be resolved for variables. If this option is not specified, the status message will be written to the originating handle's monitor.

    RESOLVEMESSAGE causes the MONITOR service to call the STAF variable service to resolve any variables in the message before being written.

    NORESOLVEMESSAGE causes the MONITOR service to not call the STAF variable service to resolve any variables in the message.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from LOG are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a LOG command.

    Examples

    LOG MESSAGE :33:Testcase aborted with error "255"
    LOG MESSAGE "Step1 in Test1 initiated on bootdrive {STAF/Config/BootDrive}"
    LOG MESSAGE "TestW: Step 32 of 109" NAME ActiveXYZRequests
    LOG MESSAGE Recovered

    8.11.5 QUERY

    Allows you to query a message from a monitor based on the machine nickname and process handle that generated the monitor message.

    Syntax

    QUERY MACHINE <Machine Nickname> < HANDLE <Handle> | NAME <Name> >
    

    MACHINE determines what machine the monitor message originated from. This option will resolve variables.

    HANDLE determines the process handle that originated the message. This option will resolve variables.

    NAME determines the name of the message. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a marshalled <Map:STAF/Service/Monitor/MonitorInfo>, representing the last monitor message generated by the specified machine/handle or for the specified machine/name.. The map is defined as follows:

    Table 57. Definition of map class STAF/Service/Monitor/MonitorInfo
    Description: This map class represents a monitor message.
    Key Name Display Name Type Format / Value
    timestamp Date-Time <String> <YYYYMMDD-HH:MM:SS>
    message Message <String>
    Notes: The "Date-Time" is the date/time at which the last monitor message was logged.

    Examples

    8.11.6 LIST

    Allows you to list Monitor settings, the names of the machines that have logged monitor data, or the monitor information for a given machine.

    Syntax

    LIST <MACHINES | MACHINE <Machine> [NAMES] | SETTINGS>
    

    MACHINES indicates you want list all the machine nicknames that have created monitor data.

    MACHINE indicates you want to list the monitor data for the specified machine nickname. This option will resolve variables. If the NAMES option is specified, only the monitor data for named monitors will be displayed; otherwise, the monitor data for (un-named) process handles will be displayed.

    NAMES indicates you want to list the named monitors for the specified machine nickname. This option will resolve variables.

    SETTINGS returns the Monitor settings.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain data based on the LIST command:

    Examples

    8.11.7 DELETE

    The DELETE command will delete handle/named monitor files and directories. You can specify whether to delete all monitor data, all monitor data recorded prior to a specified timestamp, or a specific named monitor.

    Syntax

    DELETE [BEFORE <Timestamp> | MACHINE <Machine> NAME <Name>] CONFIRM
    

    BEFORE specifies that you only want to delete monitor data recorded prior to the specified timestamp. If BEFORE is not specified, all handle/name monitor data will be removed. The keyword TODAY can be used for <Timestamp> to delete all data prior to the current system date.

    MACHINE is the machine nickname for the named monitor to be deleted.

    NAME is the named monitor to be deleted.

    CONFIRM confirms you really want to delete the monitor data.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples

    8.11.8 SET

    Sets monitor service options.

    Syntax

    SET  [RESOLVEMESSAGE | NORESOLVEMESSAGE]
         [MAXRECORDSIZE <Size>]
         [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
    

    RESOLVEMESSAGE causes the MONITOR service to call the STAF variable service to resolve any variables in Monitor Log messages before being written.

    NORESOLVEMESSAGE causes the MONITOR service to not call the STAF variable service to resolve any variables in Monitor Log messages before being written. This is the default.

    MAXRECORDSIZE <Size> sets the Maximum record size for Monitor data. The default is 1024 bytes.

    ENABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to be queried for every Monitor Log command, to determine if variables in the Monitor Log command should be resolved.

    DISABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to not be queried for every Monitor Log command. This is the default.

    The highest priority in defining whether variables in a Monitor Log command are to be resolved will be the RESOLVEMESSAGE/NORESOLVEMESSAGE specified directly in the Log command. If the Monitor Log command contains neither option, then if ENABLERESOLVEMESSAGEVAR is set, the variable STAF/Service/<Name>/ResolveMessage will be examined to determine whether to resolve the message. If DISABLERESOLVEMESSAGEVAR is set, then the RESOLVEMESSAGE/NORESOLVEMESSAGE option (set via the PARMS options or by use of the SET RESOLVEMESSAGE/NORESOLVEMESSAGE Monitor command) will be honored.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a successul SET command.

    Examples

    8.11.9 Monitor Error Code Reference

    No additional return codes are defined for the Monitor service. The Monitor service uses only the STAF return codes (see Appendix A, "API Return Codes" for additional information).


    8.12 Ping Service

    8.12.1 Description

    The PING service is an internal STAF service. PING provides a service similar to the TCP/IP PING service. This 'are you there' request can be used to determine if STAFProc is up and running and accessible.

    8.12.2 PING

    Syntax

    PING [MACHINE <Machine>]
    

    MACHINE specifies the endpoint for a machine to be pinged. This option allows you to check if the machine you are submitting the PING request to can communicate via STAF to another machine. It can be useful when trying to determine if there is a firewall issue or other network problem. This option will resolve variables.

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from PING are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain PONG on a successful return from a PING command.

    Examples

    The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.).


    8.13 Process Service

    8.13.1 Description

    The PROCESS service is one of the internal STAF services. It provides the following commands

    8.13.2 START

    START allows you to start a process. Processes may be started synchronously or asynchronously. You may also specify to which workload they belong, parameters to pass to them, their working directory, any process specific STAF variables to set for them, as well as any environment variables they may need.

    Syntax

    START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>]  [WORKDIR <Directory>]
          [VAR <Variable=Value>]...  [ENV <Variable=Value>]... [USEPROCESSVARS]
          [WORKLOAD <Name>]  [TITLE <Title>]  [WAIT [<Number>[s|m|h|d|w]] | ASYNC]
          [STOPUSING <Method>]  [STATICHANDLENAME <Name>]
          [NEWCONSOLE | SAMECONSOLE]  [FOCUS <Background | Foreground | Minimized>]
          [USERNAME <User name> [PASSWORD <Password>]]
          [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH]
          [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
          [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
          [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
          [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>]  [MACHINE <Machine>]
          [PRIORITY <Priority>] [KEY <Key>]]
    

    WORKLOAD allows you to specify the name of the workload for which this process is a member. This may be useful in conjunction with other PROCESS commands. The default is no workload name. This option will resolve variables using the IGNOREERRORS option.

    TITLE allows you to specify 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. This option will resolve variables using the IGNOREERRORS option.

    COMMAND specifies the actual command that you want to start. If the path to the command is not specified, the system PATH will be searched for the command. Only actual executable files, such as .EXEs, can be STARTed. Rexx files cannot be STARTed directly. On Windows systems, they need to be started through REXX.EXE. This option will resolve variables using the IGNOREERRORS option. This option will handle private data.

    PARMS specifies any parameters that you wish to pass to the command. This option will resolve variables using the IGNOREERRORS option. This option will handle private data.

    SHELL specifies that COMMAND should be started via a separate shell. Using a separate shell allows complex commands involving pipelines to be readily executed. This option will resolve variables using the IGNOREERRORS option. Note, if COMMAND and PARMS are both specified they will be concatenated with a space between them, and the resulting string is what will be executed. You may specify an optional shell, which overrides any defaults specified in the STAF configuration file. See 4.7, "Operational parameters" for more information on how to specify the shell.

    WORKDIR specifies the directory from which the command should be executed. If you do not specify WORKDIR, the command will be started from whatever directory STAFProc is currently in. This option will resolve variables using the IGNOREERRORS option.

    WAIT specifies that the START request should not return until the process has finished executing. You may specify an optional time duration, after which the request should return. If no time duration is specified, the request will wait indefinitely until the process has finished executing. If the WAIT does not timeout, the process termination information will not be saved after the process ends, and no FREE is necessary. This option will resolve variables. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated timeout cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    ASYNC specifies that the process should be started asynchronously, and that the START request should return to the caller as soon as the process has begun execution. In this case, the process termination will be saved after the process ends, and will later need to be FREE'd. This is the default.

    VAR allows you to specify variables that go into the process specific variable pool.

    ENV allows you to specify 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 all in uppercase. This option will resolve variables using the IGNOREERRORS option.

    USEPROCESSVARS specifies that variable references should try to be resolved from the variable pool associated with the process being started first. If the variable is not found in this pool, originating handle's pool, originator's shared pool, and originator's system pool should be searched if the request came from local, otherwise originator's handle's pool, originator's shared pool, remote shared pool and remote system pool should be searched.

    STOPUSING allows you to specify the method by which this process will be STOPed, if not overridden on the STOP command. See 8.13.3, "STOP" for more information. This option will resolve variables using the IGNOREERRORS option.

    NEWCONSOLE specifies that the process should get a new console window. So, if a process's stdout/stderr is not redirected, it will be unavailable. This is the default for Windows systems.

    SAMECONSOLE specifies that the process should share the STAFProc console. So, if a process's stdout/stderr is not redirected, it will be written to STAFProc's stdout/stderr. This is the default for Unix systems.

    FOCUS specifies the focus that is to be given to new windows opened when starting a process on a Windows system. The window(s) it effects depends on whether you are using the default command mode or the shell command mode. If the process is started using the default command mode (no SHELL option), 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 option only has effect on Windows systems. This option will resolve variables using the IGNOREERRORS option. This option was added in STAF V3.1.4. Recognized values are the following:

    USERNAME specifies the username under which the process should be started. This option will resolve variables using the IGNOREERRORS option.

    Note: The PROCESSAUTHMODE operational parameter must be enabled in the STAF configuration file on the system where the process is run under a different username. See 4.7, "Operational parameters" for more information on how to enable the PROCESSAUTHMODE operational parameter. There are additional requirements that must be met to run a process under a different username on a Windows system. See "Starting a Process Under a Different User on Windows" for more information.

    PASSWORD specifies the password with which to authenticate the user specified with USERNAME. This option will handle private data. This option will resolve variables.

    DISABLEDAUTHISERROR specifies that an error should be returned if a USERNAME/PASSWORD is specified but authentication has been disabled. This option overrides any default specified in the STAF configuration file.

    IGNOREDISABLEDAUTH specifies that any USERNAME/PASSWORD specified on the request is ignored if authentication is disabled. This option overrides any default specified in the STAF configuration file.

    STATICHANDLENAME specifies that a static handle should be created for this process. The name specified for this option 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. See "Using the STAF command from shell-scripts" for more information on static handles. This option will resolve variables using the IGNOREERRORS option.

    STDIN specifies the name of the file from which standard input will be read. This option will resolve variables using the IGNOREERRORS option.

    STDOUT specifies the name of the file to which standard output will be redirected. If the file already exists, it will be replaced. If the directory path specified for the file does not exist, it will be created. This option will resolve variables using the IGNOREERRORS option.

    STDOUTAPPEND specifies the name of the file to which standard output will be redirected. If the file already exists, the process' standard output will be appended to it. If the directory path specified for the file does not exist, it will be created. This option will resolve variables using the IGNOREERRORS option.

    STDERR specifies the name of the file to which standard error will be redirected. If the file already exists, it will be replaced. If the directory path specified for the file does not exist, it will be created. This option will resolve variables using the IGNOREERRORS option.

    STDERRAPPEND specifies the name of the file to which standard error will be redirected. If the file already exists, the process' standard error will be appended to it. If the directory path specified for the file does not exist, it will be created. This option will resolve variables using the IGNOREERRORS option.

    STDERRTOSTDOUT specifies that standard error should be redirected to the same file to which standard output is being redirected. This option is valid only if STDOUT or STDOUTAPPEND or RETURNSTDOUT is specified.

    RETURNSTDOUT specifies that the contents of the file to which standard output was redirected should be returned when the process completes. If STDOUT is not specified, standard output will be redirected to a temporary file. If STDERRTOSTDOUT is specified, the file returned will contain both standard output and standard error. This information is only available if using the WAIT or NOTIFY options.

    RETURNSTDERR specifies that the contents of the file to which standard error was redirected should be returned when the process completes. If STDERR is not specified, standard error will be redirected to a temporary file. This information is only available if using the WAIT or NOTIFY options.

    RETURNFILE specifies that the contents of the specified file should be returned when the process completes. This information is only available if using the WAIT or NOTIFY options. This option will resolve variables using the IGNOREERRORS option.

    NOTIFY ONEND specifies that you wish to send a notification when this process ends. See 8.13.8, "NOTIFY REGISTER/UNREGISTER" for the content of the notification message.

    MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables using the IGNOREERRORS option.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    KEY specifies a key that will be included in the notification message. This option will resolve variables using the IGNOREERRORS option.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables using the IGNOREERRORS option.

    Notes

    1. On Windows systems, if you are redirecting stdin/out/err and are not using SAMECONSOLE, it is recommended that you redirect all three input/output streams. If one or two streams are redirected, but not all three, the non-redirected streams will not be available to the application. For example, if stdout and stderr are redirected, but not stdin, then the application will receive errors if it tries to read from standard input. As another example, if stdin and stdout are redirected, but not stderr, then you will not see any of the standard error output displayed in the console window. This problem only occurs when using NEWCONSOLE, which is the default. You may freely redirect any combination of stdin, stdout, and stderr when using SAMECONSOLE. This problem is due to a known limitation in the Windows API.

    2. A STAF handle variable for the process named STAF/Service/Process/OrgEndpoint is set that contains the endpoint for the system that originated the PROCESS START request. The process can use this variable if it needs to communicate back to the machine that started the process.

    3. Since the entire contents of returned files are stored in the result string, if you attempt to return the contents of a very large file, you may run out of memory so it is not recommended that you use the RETURNSTDOUT, RETURNSTDERR, or RETURNFILE options to return large files. To help prevent this problem, you can specify a maximum size for a file returned by this request by setting the MAXRETURNFILESIZE operational parameter in the STAF configuration file on the machine where the process is run, or by setting the STAF/MaxReturnFileSize variable in the request variable pool of the handle that submitted the request. The lowest of these two values is used as the maximum return file size (not including 0 which indicates no limit).

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from START are documented in Appendix A, "API Return Codes".

    Results

    Examples

    The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.) or via a <process> element in a STAX job.

    The following examples show the goal and the syntax of the request to submit to the PROCESS service but not the results.

    Starting a Process Under a Different User on Windows

    To start a process under a different user name on a Windows system, the following requirements must be met:

    1. The PROCESSAUTHMODE operational parameter must be set to WINDOWS on the system where the process is run. See 4.7, "Operational parameters" for more information on how to enable the PROCESSAUTHMODE operational parameter.

    2. The Windows system where the process is run must be Windows 2000 or later.

    3. The user currently logged on the system where the process is specified to run must be a member of the Administrators group and must have the following user rights: See "Changing User Rights Assignments" for more information on how to change user rights assignments.

    4. On Windows XP systems, the user name specified when starting a process must have a password.

    5. On Windows Vista and Windows Server 2008 systems, STAFProc.exe must be run as an administrator to start a process as another user. Otherwise, submitting a STAF PROCESS START request specifying the USERNAME/PASSWORD options to start a process as another user will fail with RC 10 "LoadUserProfile failed with OS RC 1314: A required privilege is not held by the client" even though you assigned the "Replace a process level token" user right to the administrator account. On Windows Vista, STAFProc is run using the least amount of privileges (e.g. that of a standard user) even though you are logged in as an administrator. In order to start a process as another user, you must run STAFProc as an administrator. There are several ways to do this:

    There are operating system limitations on how many processes can run concurrently under a different user in the same desktop. If you get RC 10 with OS RC 1816, and the user name that the process is being run under is not a member of the Administrator group, then you may want to give it the "Increase quotas" user right so that more processes can run concurrently. See "Changing User Rights Assignments" for more information on how to change user rights assignments.

    If you are having problems starting a process under a different user name, use the Trace service to enable error and warning trace points to see if you get more information.

    Changing User Rights Assignments

    This information is provided to help you change user rights assignments as needed to start a process under a different user name.

    On Windows Vista systems, to view or modify user rights assignments in the local security policy, perform the following:

    1. Open the Control Panel, from the Classic view, double click on "Administrative Tools".
    2. Double click on "Local Security Policy".
    3. Double click on "Local Policies".
    4. Click on "User Rights Assignment".
    5. Double click on the user right you want to view or modify.
    6. Add any users or groups you require.
    7. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.

    On Windows XP systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:

    1. Open the Control Panel, from the Classic view, double click on "Administrative Tools".
    2. Double click on "Local Security Policy".
    3. Click on "User Rights Assignment".
    4. Double click on the user right you want to view or modify.
    5. Add any users or groups you require.
    6. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.
    On Windows 2000 systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:
    1. Click on Start -> Settings -> Control Panel and double click on "Administrative Tools".
    2. Double click on "Local Security Policy" and double click on "Local Policies".
    3. Double click on "User Rights Assignment".
    4. Double click on the user right you want to view or modify.
    5. Add any user names you require.
    6. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.

    8.13.3 STOP

    STOP allows you to stop a process that was started via STAF (e.g. a process that was started by submitting a START request to the PROCESS service). You may stop a single process, all processes that are part of a given workload, or all processes started by STAF.

    Syntax

    STOP <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
    

    ALL specifies that you want to stop all running processes that STAF has STARTed. If you wish to do this, you must also specify the CONFIRM option.

    WORKLOAD specifies that you want to stop all processes that are part of a given workload. This option will resolve variables.

    HANDLE specifies that only the specified handle should be stopped. This option will resolve variables.

    USING specifies the method used to stop the process. This option will resolve variables. The following methods are supported:

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from STOP are documented in Appendix A, "API Return Codes".

    Results

    Examples

    8.13.4 KILL

    KILL allows you to kill any process (even a process not started by STAF), except for the STAFProc process. Instead, use the SHUTDOWN service to shut down the STAFProc process.

    Note: If you want to kill a process that you started via STAF, in most cases, you probably want to use the STOP request to kill the process rather than using the KILL request.

    Warning: Be very careful when using this command to specify the correct pid for the process you want to kill so that you don't accidently kill a process that you didn't intend to kill.

    Syntax

    KILL PID <Pid> CONFIRM [USING <Method>]
    

    PID specifies the process id (e.g. pid) of the process that should be killed. This option will resolve variables.

    CONFIRM confirms that you really want to kill this process.

    USING specifies the method used to kill the process. This option will resolve variables. The following methods are supported:

    If the USING option is not specified, it will use the default stop method for the PROCESS service. You can list the settings for the PROCESS service, including the default stop method by submitting a LIST SETTINGS request to the PROCESS service.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from KILL are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will be empty.

    Examples

    8.13.5 LIST

    LIST allows you to obtain information about all of the processes started via STAF, or only those processes started via STAF that are currently running, or only those processes started via STAF that have completed. You may get information about any process started in WAIT mode that is still running and/or about any process started in ASYNC mode that has not yet been freed.

    You can also list the operational settings for the Process service.

    Syntax

    LIST [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG] 
    
    or
    LIST SETTINGS
    

    HANDLES specifies that you want information for process handles.

    RUNNING specifies that you only want information for processes that are currently running.

    COMPLETED specifies that you only want information for processes started in ASYNC mode that have completed, but have not yet been freed.

    WORKLOAD specifies that you want information for processes that are part of a given workload. This option will resolve variables.

    LONG specifies that you want to list more detailed information for the processes.

    SETTINGS specifies that you want to list the current operational settings for the Process service.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return:

    Examples

    8.13.6 QUERY

    QUERY allows you to obtain detailed information about a process with a specified handle that was started via STAF.

    Syntax

    QUERY HANDLE <Handle>
    

    HANDLE specifies the handle number of the process you want information on. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a marshalled Map:STAF/Service/Process/ProcessInfo>, representing information about the process specified to be queried. The map is defined as follows:

    Table 67. Definition of map class STAF/Service/Process/ProcessInfo
    Description: This map class represents a process.
    Key Name Display Name Type Format / Value
    handle Handle <String>
    handleName Handle Name <String> | <None>
    title Title <String> | <None>
    workload Workload <String> | <None>
    shell Shell <String> | <None> <Default Shell> if no value is specified
    command Command <String> Private data will be masked.
    parms Parms <String> | <None> Private data will be masked.
    workdir Workdir <String> | <None>
    focus Focus <String> 'Background' | 'Foreground' | 'Minimized'
    userName User Name <String> | <None>
    key Key <String> | <None>
    pid PID <String>
    startMode Start Mode <String> 'Async' | 'Wait'
    startTimestamp Start Date-Time <String> <YYYYMMDD-HH:MM:SS>
    endTimestamp End Date-Time <String> | <None> <YYYYMMDD-HH:MM:SS>
    rc Return Code <String> | <None>
    Notes:
    1. The value for "PID" will be the process ID assigned by the operating system.
    2. The value for "End Date-Time" and "Return Code" will be <None> if the process is still running.

    Examples

    8.13.7 FREE

    When processes are STARTed asynchronously, the termination timestamp and return code are stored by STAF for later retrieval. In order to free these values, you use the PROCESS FREE command. You may only free information for processes that are already stopped. You may free the termination information for a single process, all the stopped processes of a given workload, or all stopped processes that have been started by STAF.

    Syntax

    FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>>
    

    ALL specifies that you want to free the termination information for all stopped processes.

    WORKLOAD specifies that you want to free the termination information for all processes that are part of a given workload. This option will resolve variables.

    HANDLE specifies that only the termination information for the specified handle should be freed. This option will resolve variables.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from FREE are documented in Appendix A, "API Return Codes".

    Results

    Examples

    8.13.8 NOTIFY REGISTER/UNREGISTER

    NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when a given process ends.

    Syntax

    NOTIFY <REGISTER | UNREGISTER> ONENDOFHANDLE <Handle> [MACHINE <Machine>]
           [PRIORITY <Priority>]  [HANDLE <Handle> | NAME <Name>]
    

    REGISTER indicates you want to register for a notification when a process ends. The queued message will have type "STAF/Process/End" and its message will contain a marshalled <Map> which represents the completion information for the process. See tables Table 69 and Table 70 for the map definitions of a process completion message.

    UNREGISTER indicates you want to unregister a process end notification.

    ONENDOFHANDLE indicates the handle of the process for which you wish to receive the notification. This option will resolve variables.

    MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables.

    Table 69. Definition of map for "STAF/Process/End" type message
    Description: This map represents process completion information.
    Key Name Type Format / Value
    handle <String>
    endTimestamp <String> <YYYYMMDD-HH:MM:SS>
    rc <String>
    key <String>
    fileList <List> of <Map>. See Table 70 for the map definition.
    Notes: The value for "fileList" will contain a list of information about the files requested to be returned. Files will be returned in the order of standard output, then standard error, then any files specified with the RETURNFILE option. The value for "fileList" will be empty if none of the options RETURNSTDOUT, RETURNSTDERR, or RETURNFILE were specified when the process was started.

    Table 70. Definition of map for returned files for a process
    Description: This map class represents a file returned by the process.
    Key Name Type Format / Value
    rc <String>
    data <String>
    Notes: For each file, a standard STAF return code indicating the success or failure of retrieving the file's contents is provided. If the file's return code is 0, then the data contained in the file is also provided. If the file's return code is 58 (Maximum Size Exceeded), that indicates that the file size exceeded the maximum return file size.

    For example, suppose a PROCESS START COMMAND "java TestA" request was submitted by handle 43, and assume that the process completed successfully at 20041019-17:03:48 and returned a process return code of 0. The queued STAF/PROCESS/END message will be a map that could look like the following:

    {
      handle      : 43
      endTimestamp: 20041019-17:03:48
      rc          : 0
      key         : <None>
      fileList    : []
    }
    

    For example, suppose a PROCESS START COMMAND "java TestA" KEY 10 RETURNSTDOUT RETURNSTDERR request is submitted by handle 26 with key 10, and assume that the process completed successfully at 20041029-09:30:16 and returned a process return code of 3 and that the standard output of the process was simply "Success !!!", and that the standard error of the process was blank. The queued STAF/PROCESS/END message will be a map that could look like the following:

    {
      handle      : 26
      endTimestamp: 20041029-09:30:16
      rc          : 3
      key         : 10
      fileList    : [
        {
          rc  : 0
          data: Success !!!
        }
        {
          rc  : 0
          data: 
        } 
      ]
    }
    

    Security

    These commands require trust level 3.

    Return Codes

    All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.

    Examples

    8.13.9 NOTIFY LIST

    NOTIFY LIST allows you to view the process end notification list for a given process.

    Syntax

    NOTIFY LIST ONENDOFHANDLE <Handle>
    

    ONENDOFHANDLE indicates the handle of the process for which you wish to view the notification list. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a marshalled <List> of <Map:STAF/Service/Process/Notifiee>, representing the registered notifiees. The map is defined as follows:

    Table 71. Definition of map class STAF/Service/Process/Notifiee
    Description: This map class represents a registered notifiee.
    Key Name Display Name Type Format / Value
    priority Priority
    (P)
    <String>
    machine Machine <String>
    notifyBy Notify By <String> 'Name' | 'Handle'
    notifiee Notifiee <String>
    Notes: If the "Notify By" value is 'Name', the "Notifiee" value will be the handle name. Otherwise, if the "Notify By" value is 'Handle', the "Notifiee" value will be the handle number.

    Examples

    8.13.10 SET

    The SET command allows you to change the operational parameters for the Process service dynamically (without stopping/restarting STAF) which is important for STAF machines that must be continuously available.

    Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.

    Syntax

    SET  [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>]
         [DEFAULTFOCUS <Background | Foreground | Minimized>]
         [PROCESSAUTHMODE <Auth Mode>]
         [DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>]
         [DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>]
         [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
    

    See section 4.7, "Operational parameters" for a description of these options. All of these options will resolve variables.

    Note that the DEFAULTAUTPASSWORD option will handle private data.

    Note that setting DEFAULTCONSOLE New is equivalent to setting the DEFAULTNEWCONSOLE operational parameter in the STAF configuration file. Similarly, setting DEFAULTCONSOLE Same is equivalent to setting the DEFAULTSAMECONSOLE operational parameter in the STAF configuration file.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a successful SET command.

    Examples


    8.14 Queue Service

    8.14.1 Description

    The QUEUE service is one of the internal STAF services. It provides the following commands to manipulate the contents of a handle's queue:

    8.14.2 QUEUE

    QUEUE allows you to queue a message to a given process handle or to any process registered with a given name.

    Syntax

    QUEUE MESSAGE <Message>
          [HANDLE <Handle> | NAME <Name>] [PRIORITY <Priority>] [TYPE <Type>]
    

    MESSAGE specifies the message to be queued. This option will not resolve variables.

    HANDLE specifies the process handle to which the message should be queued. If the request is made locally, the default is the handle which originated the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the message should be queued. This option will resolve variables.

    Note: If the request is made to a remote machine then you must specify either HANDLE or NAME.

    PRIORITY specifies the priority of the message to be queued. The default is 5. This option will resolve variables.

    TYPE specifies the type for the message to be queued. The default is no type. This option will resolve variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from QUEUE are documented in Appendix A, "API Return Codes".

    If a message is attempted to be queued to a handle whose queue already contains the maximum number of messages allowed, the message will not be queued to that handle and return code 28 (Queue Full) will be returned.

    Results

    On successful return:

    If unsuccessful due to attempting to queue a message to a handle whose queue already contains the maximum number of messages allowed, the message will not be sent to that handle's queue and return code 28 (Queue full) will be returned and the result buffer will be set as follows:

    Examples

    8.14.3 GET/PEEK

    GET allows you to retrieve and remove one or more elements from the queue of the handle submitting the GET request to the QUEUE service.

    PEEK allows you to retrieve one or more elements from the queue of the handle submitting the PEEK request without removing the element(s) from the queue.

    By default, only one element will be retrieved/removed from the queue if you don't specify the ALL or FIRST option.

    For security reasons, you are only allowed to retrieve messages from your own handle's queue, not from any other handle's queue. So, a GET/PEEK request only retrieves messages from the queue of the handle that submitted the GET/PEEK request to the QUEUE service. Note that you can use the LIST request to list messages that are in another handle's queue.

    Syntax

    GET  [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
         [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
         [CONTAINS <String>]... [ICONTAINS <String>]...
         [FIRST <Number> | ALL]
         [WAIT [<Number>[s|m|h|d|w]] ]
     
    PEEK [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
         [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
         [CONTAINS <String>]... [ICONTAINS <String>]...
         [FIRST <Number> | ALL]
         [WAIT [<Number>[s|m|h|d|w]] ]
    

    PRIORITY specifies that you want to retrieve/remove message(s) with the given priority. The default is the highest priority message (i.e., the one with the lowest priority number). You may specify this option multiple times. This option will resolve variables.

    MACHINE specifies that you want to retrieve/remove message(s) originating from the given machine's endpoint. The default is any machine. You may specify this option multiple times. This option will resolve variables. The format for a machine's endpoint is:

      <Interface>://<System Identifier>[@<Port>]
    
    where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".

    NAME specifies that you want to retrieve/remove message(s) originating from a process with the given registered name. The default is any name. You may specify this option multiple times. This option will resolve variables. Note that this option does not specify the handle name for the handle whose queue you want to retrieve messages from as you can only retrieve messages from the queue of the handle that submitted the GET/PEEK request to the QUEUE service.

    HANDLE specifies that you want to retrieve/remove message(s) originating from a process with the given handle number. The default is any handle. You may specify this option multiple times. This option will resolve variables. Note that this option does not specify the handle number for the handle whose queue you want to retrieve messages from as you can only retrieve messages from the queue of the handle that submitted the GET/PEEK request to the QUEUE service.

    USER specifies that you want to retrieve/remove a message originating from a process with a handle that has been authenticated with the specified user. The format for <User> is:

      <Authenticator>://<User Identifier>
    
    where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the User Identifier. The default is any user. You may specify this option multiple times. This option will resolve variables.

    TYPE specifies that you want to retrieve/remove message(s) with the given type. The match is case insensitive. You may specify this option multiple times. This option will resolve variables.

    CONTAINS specifies that you want to retrieve/remove message(s) containing the given string. The search is case sensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    ICONTAINS specifies that you want to retrieve/remove message(s) containing the given string. The search is case insensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    ALL specifies that you want to retrieve/remove all appropriate messages that meet the specified criteria. If you don't specify the ALL or FIRST option, the default is to retrieve/remove one appropriate message.

    FIRST specifies that you want to retrieve/remove the first <Number> of appropriate messages that meet the specified criteria, where <Number> must be an integer greater than 0. If there are fewer appropriate messages on the queue that meet the specified criteria than the number you specified for the FIRST option, then fewer messages will be returned than the number you specified. If you don't specify the ALL or FIRST option, the default is to retrieve/remove one appropriate message. This option will resolve variables.

    WAIT specifies that the request should not return until an appropriate message is available. You may specify an optional time duration after which the request should return. If no time duration is specified, the request will wait indefinitely until an appropriate message is available. This option will resolve variables. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated timeout cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    Security

    These commands are only valid with respect to the submitting process' queue and if submitted to the local machine.

    Return Codes

    All return codes from GET/PEEK are documented in Appendix A, "API Return Codes".

    For example:

    Results

    Examples

    8.14.4 DELETE

    DELETE allows you to delete a set of messages from a queue.

    Syntax

    DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
           [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
           [CONTAINS <String>]... [ICONTAINS <String>]...
    

    PRIORITY specifies that you want to delete messages with the given priority. The default is any priority. You may specify this option multiple times. This option will resolve variables.

    MACHINE specifies that you want to delete messages originating from the given machine's endpoint. The default is any machine. You may specify this option multiple times. This option will resolve variables. The format for a machine's endpoint is:

      <Interface>://<System Identifier>[@<Port>]
    
    where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".

    NAME specifies that you want to delete messages originating from a process with the given registered name. The default is any name. You may specify this option multiple times. This option will resolve variables.

    HANDLE specifies that you want to delete messages originating from a process with the given handle. The default is any handle. You may specify this option multiple times. This option will resolve variables.

    USER specifies that you want to delete messages originating from a process with a handle that has been authenticated with the specified user. The format for <User> is:

      <Authenticator>://<User Identifier>
    
    where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the <User Identifier> value. The default is any user. You may specify this option multiple times. This option will resolve variables.

    TYPE specifies that you want to delete messages with the given type. The match is case insensitive. You may specify this option multiple times. This option will resolve variables.

    CONTAINS specifies that you want to delete messages containing the given string. The search is case sensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    ICONTAINS specifies that you want to delete messages containing the given string. The search is case insensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    Security

    This command is only valid with respect to the submitting process' queue and if submitted to the local machine.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the number of messages deleted.

    Examples

    8.14.5 LIST

    LIST allows you to retrieve the contents of the queue of a given handle.

    Syntax

    LIST [HANDLE <Handle>]
    

    HANDLE specifies the handle of the process for which you want the queue contents. The default is the handle of the submitting process. This option will only default if the request was submitted locally. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Queue/Entry>, representing the queued messages, sorted in ascending order by priority. The map is defined as follows:

    Table 75. Definition of map class STAF/Service/Queue/Entry
    Description: This map class represents a queued message.
    Key Name Display Name Type Format / Value
    priority Priority <String>
    timestamp Date-Time <String> <YYYYMMDD-HH:MM:SS>
    machine Machine <String>
    handleName Handle Name <String> | <None>
    handle Handle <String>
    type Type <String> | <None>
    message Message <Any> Private data will be masked.

    Examples


    8.15 Resource Pool (ResPool) Service

    8.15.1 Description

    The Resource Pool service is an external STAF service that allows you to manipulate resource pools and contents of the resource pools via the following functions.: The purpose of the Resource Pool service is to manage exclusive access to the entries within resource pools. For example, if you had a group of VM UserIDs and passwords for a particular VM system that needed to be shared amongst numerous testcases, you could create a resource pool for them and then testcases that required a logon to that VM system could request a UserID and password from this resource pool, perform the test, and then release the UserID and password back to the resource pool.

    8.15.2 Registration

    The Resource Pool service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    SERVICE <Name> LIBRARY STAFPool [PARMS <Parameters>]
    

    <Name> is the name by which the Resource Pool service will be known on this machine.

    <Parameters> are valid Resource Pool parameters described below.

    Example

    service respool library STAFPool
    service respool library STAFPool parms "Directory {STAF/Config/BootDrive}/STAF/ResPool"
    

    8.15.3 Parameters

    The Resource Pool service accepts a parameter string in the following format:

    [DIRECTORY <Resource Pool Directory Root>]
    

    DIRECTORY specifies the root directory under which resource pool files are stored. The default is {STAF/DataDir}/service/<Service Name (lower-case)>.

    Note: Previously, in STAF 2.x, the default root directory was {STAF/Config/STAFRoot}/data/<Service Name (lower-case)>. So, if you want to continue to use the STAF 2.x resource pools with the current version of STAF, move the resource pool files to the new default root directory or specify the old root directory for the DIRECTORY parameter.

    8.15.4 LIST

    LIST displays a list of resource pools and their descriptions.

    Syntax

    LIST [POOLS | SETTINGS]
    

    POOLS indicates to list the resource pools. This is the default.

    SETTINGS indicates to list the operational settings for the Resource Pool service.

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    Examples

    8.15.5 CREATE

    Creates a resource pool.

    Syntax

    CREATE POOL <PoolName> DESCRIPTION <Description>
    

    POOL specifies the name of the resource pool you want to create. This option will resolve variables.

    Note that the pool name will be used in the name of a file that will be created in the resource pool directory root, (e.g. <ResourcePoolDirectoryRoot>/<PoolName>.rpl). So, avoid specifying a character that the file system doesn't allow in a file name such as the following characters: < > : " / \ | ? *

    DESCRIPTION specifies the description of the resource pool. This option will resolve variables.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", CREATE also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from a CREATE command.

    Examples

    8.15.6 DELETE

    Deletes a resource pool and all its entries.

    Syntax

    DELETE POOL <PoolName> CONFIRM [FORCE]
    

    POOL specifies the name of the resource pool you want to delete. This option will resolve variables.

    CONFIRM confirms you really want to delete the resource pool.

    FORCE allows you to force the deletion of the resource pool, even if there are pending requests. If this option is not specified, you will receive an error if you try to delete a resource pool which has pending requests.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", DELETE also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from a DELETE command.

    Examples

    8.15.7 ADD

    ADD allows you to add a resource entry to an existing resource pool. You may add multiple entries to a resource pool with a single request. Note, a resource pool may not contain duplicate entries. If one or more duplicate entries are specified with a single request, none of the entries specified are added.

    Syntax

    ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
    

    POOL specifies the name of the resource pool to which you want to add a resource entry. This option will resolve variables.

    ENTRY specifies the actual entry to be added to the resource pool.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", ADD also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the ADD command.

    Examples

    8.15.8 REMOVE

    REMOVE removes a resource entry from an existing resource pool. The resource entry may only be removed if the resource is not in use or if the FORCE option is specified. Note, you may remove multiple entries from a resource pool with a single request. If one or more invalid entries are specified with a single request, none of the entries specified are removed.

    Syntax

    REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
    

    POOL specifies the name of the resource pool from which you want to remove an entry. This option will resolve variables.

    ENTRY specifies the actual entry to be removed.

    CONFIRM confirms you really want to remove the resource entry.

    FORCE allows you to force the removal of a resource entry which is currently owned. By default, you may only remove a resource entry if it is not currently owned.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", REMOVE also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the REMOVE command.

    Examples

    8.15.9 QUERY

    Allows you to get information on a resource pool, including a list of entries in the pool and the status of each entry, as well as a list of the pending requests for entries in the resource pool. The pending requests will shown in ascending order by priority, and within the same priority by the request timestamp.

    Syntax

    QUERY POOL <PoolName>
    

    POOL specifies the name of the resource pool you want to query. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", QUERY also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer for a QUERY request will contain a marshalled <Map:STAF/Service/ResPool/PoolInfo>, representing information about the specified resource pool.

    The maps used in representing a resource pool are defined as follows:

    Table 78. Definition of map class STAF/Service/ResPool/PoolInfo
    Description: This map class represents a resource pool.
    Key Name Display Name Type Format / Value
    description Description <String>
    requestList Pending Requests <List> of <Map:STAF/Service/ResPool/Request>
    resourceList Resources <List> of <Map:STAF/Service/ResPool/Resource>
    Notes: For each pending request in the request list for the pool, information about the priority, the requested timestamp, the requested entry (if any), and the originator of the pending request is provided. For each entry in the resource list for the pool, the resource entry and owner information is provided.

    Table 79. Definition of map class STAF/Service/ResPool/Request
    Description: This map class represents a pending request for a resource in a resource pool
    Key Name Display Name Type Format / Value
    priority Priority <String> | <None> '1' - '99'
    requestedTimestamp Date-Time Requested <String> <YYYYMMDD-HH:MM:SS>
    requestedEntry Requested Entry <String> | <None>
    machine Machine <String>
    handleName Handle Name <String>
    handle Handle <String>
    user User <String> <Authenticator>://<User ID>
    endpoint Endpoint <String> <Interface>://<System Identifier>[@<Port>]
    gc Perform Garbage Collection <String> 'Yes' | 'No'
    Notes:

    1. The "Priority" field contains the priority of the pending request.

    2. The "Date-Time Requested" contains the timestamp when the pending request was submitted.

    3. The "Requested Entry" contains the specified entry if the ENTRY option was specified to request a particular entry in a resource pool (instead of the first or a random entry). Otherwise, it will be <None>.

    4. The "Machine", "Handle Name", "Handle", "User", and "Endpoint" fields provide information about who submitted (aka originated) the request.

    5. The "Perform Garbage Collection" field indicates whether or not garbage collection will be performed when the handle that submitted the request no longer exists.

    Table 80. Definition of map class STAF/Service/ResPool/Resource
    Description: This map class represents a resource in the pool
    Key Name Display Name Type Format / Value
    entry Entry <String>
    owner Owner <None> |
    <Map:STAF/Service/ResPool/ResourceOwner>

    Notes: If the resource entry is not owned, the owner will be <None>.

    Table 81. Definition of map class STAF/Service/ResPool/ResourceOwner
    Description: This map class represents a owner of a resource
    Key Name Display Name Type Format / Value
    machine Machine <String>
    handleName Handle Name <String>
    handle Handle <String>
    user User <String> <Authenticator>://<User ID>
    endpoint Endpoint <String> <Interface>://<System Identifier>[@<Port>]
    requestedTimestamp Date-Time Requested <String> <YYYYMMDD-HH:MM:SS>
    acquiredTimestamp Date-Time Acquired <String> <YYYYMMDD-HH:MM:SS>
    gc Perform Garbage Collection <String> 'Yes' | 'No'

    Examples

    8.15.10 REQUEST

    Obtains exclusive access to an entry from the resource pool.

    If an entry is available that meets the specified criteria in the request, then the entry will become owned by the STAF handle on the machine that submitted the REQUEST POOL request to the RESPOOL service. If an entry is not currently available that meets the specified criteria in the request, the request will be added to the "Pending Requests" list in ascending order by "priority" and then by the timestamp when the request was submitted.

    Understanding how Garbage Collection effects Resource Pools

    The STAF handle on the machine that submitted a REQUEST POOL request to the RESPOOL service will be the "owner" of the resource pool entry. Note that when a STAF handle that requested a resource is deleted, STAF performs garbage collection for the handle by default, unless you specified not to perform garbage collection when requesting a resource. Performing garbage collection means when a handle that requested a resource is deleted, the RESPOOL service will be notified, and it will release any resource pool entries that handle owns and will remove any pending requests for resources submitted by that handle.

    If you submit a REQUEST POOL request to the RESPOOL service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:

    So, when using the STAF command executable to submit a REQUEST POOL request to the RESPOOL service, in order to retain ownership of the resource pool entry (due to garbage collection), you either need to specify not to perform garbage collection or you need to use a static handle when submitting the request. See "Command Line Example" for examples of how to do this.

    Syntax

    REQUEST POOL <PoolName>
            [FIRST | RANDOM | ENTRY <Value> [RELEASE]] [PRIORITY <Number>]
            [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
    

    POOL specifies the name of the resource pool from which you are requesting a resource. This option will resolve variables.

    TIMEOUT specifies a timeout duration indicating the longest you are willing to wait for a resource to become available. If this option is not specified, the request will wait indefinitely until a resource is available. This option will resolve variables. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated timeout cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    FIRST specifies that the first available entry in the resource list should be returned.

    RANDOM specifies that a random available entry should be returned. This is the default.

    ENTRY specifies a particular entry in the resource list that should be returned.

    RELEASE specifies to release the entry after requesting it (i.e. performs an atomic release and request). This option can only be specified when requesting an entry that is already owned by the handle submitting the request. This can be useful when you want to re-gain ownership of the entry before any lesser-priority pending requests.

    PRIORITY specifies the priority of the request. It must be a number from 1 to 99, where 1 indicates the highest priority. The default is 50. If an entry is not currently available that meets the specified criteria in the request, the request will be added to the "Pending Requests" list in ascending order by "priority" and then by the timestamp when the request was submitted. Pending requests with priority 1 will be satisfied first if possible, followed by pending requests with priority 2, and so on. This option will resolve variables.

    GARBAGECOLLECT specifies whether to perform garbage collection when the STAF handle that requested a resource is deleted. Valid values are Yes and No, not case-sensitive. The default is Yes which means that garbage collection will be performed for the handle that requested the resource. This option will resolve variables.

    For example, if you need a resource to be owned for a long period of time and the STAF handle that you're going to use to submit the request may not exist for that period of time, then you must specify not to perform garbage collection when requesting a resource. This ensures that the resource will not be released until a RELEASE ENTRY request for that resource pool entry is submitted.

    Security

    This command requires trust level 3.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", REQUEST also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    On successful return, the result buffer will contain the entry given to the process.

    Examples

    Command Line Example

    Say you had a resource pool named MachinePool that contained two entries and you submit a REQUEST POOL request to the RESPOOL service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't specify not to perform garbage collection and if you didn't use a static handle, the resource entry obtained by the REQUEST POOL request would show up as available (Unowned) when submitting a QUERY POOL request to the RESPOOL service because when the STAF command deleted the handle it created to submit the REQUEST POOL request, that triggered garbage collection to be performed.

    C:\>STAF local RESPOOL REQUEST POOL MachinePool
    Response
    --------
    machine1
     
    C:\>STAF local RESPOOL QUERY POOL MachinePool
    Response
    --------
    {
      Description     : Test Machine Pool
      Pending Requests: []
      Resources       : [
        {
          Entry: machine1
          Owner: <None>
        }
        {
          Entry: machine2
          Owner: <None>
        }
      ]
    }
    

    Instead, you need to specify not to perform garbage collection when submitting the REQUEST POOL request to the RESPOOL service using the STAF command. Here's an example shown using the STAF command from a Windows command prompt:

    C:\>STAF local RESPOOL REQUEST POOL MachinePool GARBAGECOLLECT No
    Response
    --------
    machine1
     
    C:\>STAF local RESPOOL QUERY POOL MachinePool
    Response
    --------
    {
      Description     : Test Machine Pool
      Pending Requests: []
      Resources       : [
        {
          Entry: machine1
          Owner: {
            Machine                   : client1.company.com
            Handle Name               : STAF/Client
            Handle                    : 49
            User                      : none://anonymous
            Endpoint                  : local://local
            Date-Time Requested       : 20070430-14:11:18
            Date-Time Acquired        : 20070430-14:11:18
            Perform Garbage Collection: Yes
          }
        }
        {
          Entry: machine2
          Owner: <None>
        }
      ]
    }
    

    Or, you need to first create a static handle and set environment variable STAF_STATIC_HANDLE to the static handle's number before submitting a REQUEST POOL request to the RESPOOL service using the STAF command so that the static handle can retain ownership of the resource entry until it releases the entry (or until you delete the static handle). See "Using the STAF command from shell-scripts" for more information on special environment variable STAF_STATIC_HANDLE. Here's an example shown using the STAF command from a Windows command prompt:

    C:\>STAF local HANDLE CREATE HANDLE NAME ResourcePoolHandle
    Response
    --------
    51
     
    C:\>set STAF_STATIC_HANDLE=51
     
    C:\>STAF local RESPOOL REQUEST POOL MachinePool
    Response
    --------
    machine1
     
    C:\>STAF local RESPOOL QUERY POOL MachinePool
    Response
    --------
    {
      Description     : Test Machine Pool
      Pending Requests: []
      Resources       : [
        {
          Entry: machine1
          Owner: {
            Machine                   : client1.company.com
            Handle Name               : ResourcePoolHandle
            Handle                    : 51
            User                      : none://anonymous
            Endpoint                  : local://local
            Date-Time Requested       : 20070430-14:15:18
            Date-Time Acquired        : 20070430-14:15:18
            Perform Garbage Collection: Yes
          }
        }
        {
          Entry: machine2
          Owner: <None>
        }
      ]
    }  
    

    8.15.11 RELEASE

    RELEASE allows you to release exclusive access of a resource entry in a resource pool.

    Syntax

    RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
    

    POOL specifies the name of the resource pool to which you are releasing exclusive access of an entry. This option will resolve variables.

    ENTRY specifies the actual entry to which you are releasing exclusive access.

    FORCE allows you to force the release of the resource entry. By default, only the owner of the resource entry (e.g. the handle on the machine that submitted the REQUEST POOL request) may RELEASE the entry.

    Security

    Command RELEASE requires trust level 3.

    Command RELEASE FORCE requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", RELEASE also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the RELEASE command.

    Examples

    8.15.12 CANCEL

    Cancels a pending request for a resource pool entry. By default, it cancels the last pending request in the Pending Requests list (which is sorted in ascending order by priority, and then by the request timestamp) that was submitted by the same handle/machine submitting the CANCEL request. You may specify additional selection criteria (such as machine, handle number or name, entry, priority, or first) to specify to cancel a different pending request.

    Syntax

    CANCEL POOL <PoolName>
           [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]]
           [ENTRY <Value>] [PRIORITY <Number>] [FIRST | LAST]
    

    POOL specifies the name of the resource pool from which you want to cancel a request in its Pending Requests list. This option will resolve variables.

    FORCE allows you to force cancelling the pending request. By default, only the requester (e.g. the handle on the machine that submitted the REQUEST POOL request) may CANCEL the pending request unless the FORCE option is specified, along with the MACHINE and/or HANDLE/NAME options.

    MACHINE specifies the machine that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the machine submitting the CANCEL request. This option will resolve variables.

    HANDLE specifies the handle number that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the number of the handle submitting the CANCEL request. This option will resolve variables.

    NAME specifies the name of a handle that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the name of the handle submitting the CANCEL request. This option will resolve variables.

    ENTRY specifies a resource entry that matches the "Requested Entry" field in the Pending Requests list for the request that you want to cancel. It can be specified only if a particular resource entry was specified by the REQUEST request that you want to cancel.

    PRIORITY specifies the priority of the request you want to cancel. It must be a number from 1 to 99, where 1 indicates the highest priority. This option will resolve variables.

    FIRST specifies to cancel the first entry in the Pending Requests list (which is sorted in ascending order by priority and then by the request timestamp) that matches the selection criteria.

    LAST specifies to cancel the last entry in the Pending Requests list (which is sorted in ascending order by priority and then by the request timestamp) that matches the selection criteria. This is the default.

    Security

    Command CANCEL requires trust level 3.

    Command CANCEL FORCE requires trust level 4 if you are not the requester (e.g. the handle on the machine that submitted the REQUEST POOL request that you are trying to cancel).

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", CANCEL also returns the return codes documented in 8.15.13, "Resource Pool Error Code Reference".

    Results

    On successful return, the result buffer will contain no data.

    Examples

    8.15.13 Resource Pool Error Code Reference

    In addition to STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Resource Pool return codes are defined:

    Table 82. Resource Pool Service Return Codes
    Error Code Meaning Comment
    4005 Not entry owner You are not the owner of the entry you are trying to RELEASE. Use the FORCE option if you are sure that the correct entry is specified.
    4006 Pool has pending requests The resource pool you are trying to DELETE has pending requests. If necessary, use the FORCE option.
    4007 No entries available The resource pool has no entries.
    4008 Create pool path error The directory specified by the DIRECTORY parameter when registering the service or the default directory could not be created.
    4009 Invalid pool file format An error occurred reading the resource pool file due to an error in the file format. If you are using the latest version of the Resource Pool service, contact the STAF authors.
    4010 Entry is owned A resource pool entry you specified to REMOVE is owned. Use the FORCE option if you are sure that the correct entry is specified.
    4011 Not pending requester You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.


    8.16 Semaphore (SEM) Service

    8.16.1 Description

    The SEM service is one of the internal STAF services that allows you to manipulate and manage two kinds of semaphores:

    The SEM service provides the following commands:

    8.16.2 REQUEST

    REQUEST allows you to request exclusive access of a mutex semaphore. Your request is blocked until all prior pending REQUESTs have been RELEASEd. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait to gain access to the semaphore. If no timeout is specified, the request will block indefinitely. The semaphore is created if it does not exist.

    Understanding how Garbage Collection effects Mutex Semaphores

    The STAF handle on the machine that submitted the REQUEST MUTEX request to the SEM service will be the "owner" of the mutex semaphore. Note that when a STAF handle that requested a mutex semaphore is deleted, STAF performs garbage collection for the handle by default, unless you specified not to perform garbage collection when requesting a mutex semaphore. Performing garbage collection means when a handle that requested a mutex semaphore is deleted, the SEM service will be notified, and it will release any mutex semaphores that handle owns and will remove any pending requests for mutex semaphores submitted by the handle.

    If you submit a REQUEST MUTEX request to the SEM service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:

    So, when using the STAF command executable to submit a REQUEST MUTEX request to the SEM service, in order to retain ownership of the mutex semaphore (due to garbage collection), you either need to specify not to perform garbage collection or you need to use a static handle when submitting the request. See "Command Line Example" for examples of how to do this.

    Syntax

    REQUEST MUTEX <Name> [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
    

    MUTEX specifies the name of the mutex semaphore which you want to request. The semaphore is created if it does not exist. This option will resolve variables.

    TIMEOUT specifies a timeout duration indicating the longest you are willing to wait to gain access to the semaphore. If this option is not specified, the request will wait indefinitely until the semaphore is available. This option will resolve variables. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated timeout cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    GARBAGECOLLECT specifies whether to perform garbage collection when the STAF handle that requested a mutex semaphore is deleted. Valid values are Yes and No, not case-sensitive. The default is Yes which means that garbage collection will be performed for the handle that requested the mutex semaphore. This option will resolve variables.

    For example, if you need a mutex semaphore to be owned for a long period of time and the STAF handle that you're going to use to submit the request may not exist for that period of time, then you must specify not to perform garbage collection when requesting a mutex semaphore. This ensures that the mutex semaphore will not be released until a RELEASE MUTEX request for that semaphore is submitted.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a REQUEST command.

    Examples

    Command Line Example

    Say you submitted a REQUEST MUTEX request to the SEM service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't specify not to perform garbage collection and if you didn't use a static handle, the mutex semaphore would show up as available (Unowned) when submitting a QUERY MUTEX request to the SEM service because when the STAF command deleted the handle it created to submit the REQUEST MUTEX request, that triggered garbage collection to be performed.

    C:\>STAF local SEM REQUEST MUTEX Mutex1
    Response
    --------
     
     
    C:\>STAF local SEM QUERY MUTEX Mutex1
    Response
    --------
    {
      State           : Unowned
      Owner           : <None>
      Pending Requests: []
    }
    

    Instead, you need to specify not to perform garbage collection when submitting the REQUEST MUTEX request to the SEM service using the STAF command. Here's an example shown using the STAF command from a Windows command prompt:

    C:\>STAF local SEM REQUEST MUTEX Mutex1 GARBAGECOLLECT No
    Response
    --------
     
    C:\>STAF local SEM QUERY MUTEX Mutex1
    Response
    --------
    {
      State           : Owned
      Owner           : {
        Machine                   : client1.company.com
        Handle Name               : STAF/Client
        Handle                    : 80
        User                      : none://anonymous
        Endpoint                  : local://local
        Date-Time Requested       : 20070430-15:31:24
        Date-Time Acquired        : 20070430-15:31:24
        Perform Garbage Collection: No
      }
      Pending Requests: []
    }
    

    Or, you need to first create a static handle and set environment variable STAF_STATIC_HANDLE to the static handle's number before submitting a REQUEST MUTEX request to the SEM service using the STAF command so that the static handle can retain ownership of the mutex semaphore until it releases the mutex semaphore (or until you delete the static handle). See "Using the STAF command from shell-scripts" for more information on special environment variable STAF_STATIC_HANDLE. Here's an example shown using the STAF command from a Windows command prompt:

    C:\>STAF local HANDLE CREATE HANDLE NAME MyHandle
    Response
    --------
    82
     
    C:\>set STAF_STATIC_HANDLE=82
     
    C:\>STAF local SEM REQUEST MUTEX Mutex1
    Response
    --------
     
     
    C:\>STAF local SEM QUERY MUTEX Mutex1
    Response
    --------
    {
      State           : Owned
      Owner           : {
        Machine                   : client1.company.com
        Handle Name               : MyHandle
        Handle                    : 82
        User                      : none://anonymous
        Endpoint                  : local://local
        Date-Time Requested       : 20070430-15:32:34
        Date-Time Acquired        : 20070430-15:32:34
        Perform Garbage Collection: Yes
      }
      Pending Requests: []
    }
    

    8.16.3 RELEASE

    RELEASE allows you to release exclusive access to a mutex semaphore. Normally, only the owning handle may release the mutex semaphore. Specifying FORCE allows you to force the release of the semaphore.

    Note: Any thread in the owning handle's process may RELEASE the semaphore. This is in contrast to other semaphore systems, where only the REQUESTing thread may release the semaphore.

    Syntax

    RELEASE MUTEX <Name> [FORCE]
    

    MUTEX specifies the name of the mutex semaphore which you want to release. This option will resolve variables.

    FORCE allows you to force the release of the semaphore even if you are not the owner.

    Security

    This command requires trust level 3.

    Note: If the FORCE option is specified, trust level 4 is required.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RELEASE command.

    Examples

    8.16.4 CANCEL

    CANCEL allows you to cancel a pending request for a mutex semaphore. By default, it cancels the last pending request in the Pending Requests list (which is sorted in ascending order by the request timestamp) that was submitted by the same handle/machine submitting the CANCEL request. You may specify additional selection criteria (such as machine, handle number or name, or first) to specify to cancel a different pending request.

    Syntax

    CANCEL MUTEX <Name>
           [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]]
           [FIRST | LAST]
    

    MUTEX specifies the name of the mutex semaphore for which you want to cancel a request in its Pending Requests list. This option will resolve variables.

    FORCE allows you to force canceling the pending request for the semaphore. By default, only the requester (e.g. the handle on the machine that submitted the REQUEST MUTEX request) may CANCEL the pending request unless the FORCE option is specified, along with the MACHINE and/or HANDLE/NAME options.

    MACHINE specifies the machine that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the machine submitting the CANCEL request. This option will resolve variables.

    HANDLE specifies the handle number that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the number of the handle submitting the CANCEL request. This option will resolve variables.

    NAME specifies the name of a handle that submitted a request in the Pending Requests list that you want to cancel. If not specified, it defaults to the name of the handle submitting the CANCEL request. This option will resolve variables.

    FIRST specifies to cancel the first entry in the Pending Requests list (which is sorted in ascending order by the request timestamp) that matches the selection criteria.

    LAST specifies to cancel the last entry in the Pending Requests list (which is sorted in ascending order by the request timestamp) that matches the selection criteria. This is the default.

    Security

    Command CANCEL requires trust level 3.

    Command CANCEL FORCE requires trust level 4 if you are not the requester (e.g. the handle on the machine that submitted the REQUEST MUTEX request that you are trying to cancel).

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain no data.

    Examples

    8.16.5 POST

    POST allows you to post an event semaphore to signal that an event has happened. It is valid to post an event semaphore that is already posted.

    Syntax

    POST EVENT <Name>
    

    EVENT specifies the name of the event semaphore which you want to post. The semaphore is created if it does not exist. This option will resolve variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a POST command.

    Examples

    8.16.6 RESET

    RESET allows you to reset an event semaphore in preparation for the next event. It is valid to reset an event semaphore that is already reset.

    Syntax

    RESET EVENT <Name>
    

    EVENT specifies the name of the event semaphore which you want to post. The semaphore is created if it does not exist. This option will resolve variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RESET command.

    Examples

    8.16.7 PULSE

    PULSE allows you to post and then reset an event semaphore as a single atomic action. It is valid to pulse a semaphore regardless of whether it is currently posted or reset. The semaphore will be in the reset state after the pulse.

    Syntax

    PULSE EVENT <Name>
    

    EVENT specifies the name of the event semaphore which you want to pulse. The semaphore is created if it does not exist. This option will resolve variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a PULSE command.

    Examples

    8.16.8 WAIT

    WAIT allows you to wait for an event semaphore. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait for an event semaphore. If no timeout is specified, the request will block indefinitely.

    Syntax

    WAIT EVENT <Name> [TIMEOUT <Number>[s|m|h|d|w]]
    

    EVENT specifies the name of the event semaphore which you want to wait for. The semaphore is created if it does not exist. This option will resolve variables.

    TIMEOUT specifies a timeout duration indicating the longest you are willing to wait for the semaphore. If this option is not specified, the request will wait indefinitely for the semaphore. This option will resolve variables. The time duration may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and indicates milliseconds unless one of the following case-insensitive suffixes is specified:

    Note that the calculated timeout cannot exceed 4294967294 milliseconds. So, the maximum values in each time category that can be specified are:

    Security

    This command requires trust level 3.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a WAIT command.

    Examples

    8.16.9 DELETE

    DELETE allows you to delete a mutex or event semaphore.

    Syntax

    DELETE MUTEX <Name> | EVENT <Name>
    

    MUTEX specifies the name of the mutex semaphore which you want to delete. A mutex semaphore may only be deleted if there are no pending REQUESTs. This option will resolve variables.

    EVENT specifies the name of the event semaphore which you want to delete. An event semaphore may only be deleted if there are no processes WAITing for it. This option will resolve variables.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a DELETE command.

    Examples

    8.16.10 QUERY

    QUERY allows you to get information on a mutex or event semaphore, such as the current owner and pending REQUESTSs. if it is a mutex semaphore or whether the semaphore is posted or reset if it is an event semaphore.

    Syntax

    QUERY MUTEX <Name> | EVENT <Name>
    

    MUTEX specifies the name of the mutex semaphore which you want to query. This option will resolve variables.

    EVENT specifies the name of the event semaphore which you want to query. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain information about the specified mutex or event semaphore:

    Examples

    8.16.11 LIST

    LIST allows you to obtain a list of the mutex or event semaphores.

    Syntax

    LIST <MUTEX | EVENT>
    

    MUTEX specifies that you want a list of the mutex semaphores.

    EVENT specifies that you want a list of the event semaphores.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a list of the desired mutex or event semaphores:

    Examples


    8.17 Service Service

    8.17.1 Description

    The SERVICE service is one of the internal STAF services. It provides the following commands.

    8.17.2 LIST

    LIST will display information about the services, service loaders, or authenticators available on the machine, or requests that have been submitted on the machine.

    Syntax

    LIST [ SERVICES | SERVICELOADERS | AUTHENTICATORS |
           REQUESTS <[PENDING] [COMPLETE] [LONG]> | [SUMMARY] ]
    

    SERVICES specifies that you want a list of services that are registered.

    SERVICELOADERS specifies that you want a list of the service loaders that are registered.

    AUTHENTICATORS specifies that you want a list of the authenticators that are registered.

    REQUESTS specifies that you want a list of requests.

    PENDING specifies that the request list should include pending requests, i.e. requests which are still being processed.

    COMPLETE specifies that the request list should include completed requests which have not yet been FREEd.

    LONG specifies that the request list should include more detailed information about each request.

    If neither PENDING nor COMPLETE is specified the default is PENDING.

    SUMMARY specifies that you want summary information about requests such as the number of active requests, the total number of requests that have been submitted since STAFProc was started, the number of times the request number has been reset, the request number range, and the maximum number of active requests.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain information about the request based on the options specified:

    Examples

    8.17.3 QUERY

    QUERY will display information about a service, authenticator, or service loader available on the machine, or about a request that has been submitted on the machine.

    Syntax

    QUERY SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> |
          AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number>
    

    SERVICE specifies the name of the service to be queried.

    SERVICELOADER specifies the name of the service loader to be queried.

    AUTHENTICATOR specifies the name of the authenticator service to be queried.

    REQUEST specifies the number of the request to be queried.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer will contain the following based on the request:

    Examples

    8.17.4 ADD

    ADD will add (register and initialize) the specified external service and make it available on the machine.

    Syntax

    ADD SERVICE <Service Name> LIBRARY <Library Name> [EXECUTE <Executable>]
        [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

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

    LIBRARY specifies the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See section 4.4.2, "JSTAF service proxy library" for information regarding the JSTAF service proxy library. Otherwise, see the documentation provided by the service proxy library.

    OPTION specifies a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See section 4.4.2, "JSTAF service proxy library" for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service during initialization.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from ADD are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain nothing.

    Examples

    8.17.5 REMOVE

    REMOVE will remove (unregister and terminate) the specified external service, making it no longer available on the machine.

    Note: If pending requests for the service exist, it may take up to a minute or so after the REMOVE request has completed in order for the service to complete its termination process. This can be especially true for a service that is registered using a service proxy library such as JSTAF which is used when registering Java services as it may take another minute or so for the JVM that this service was running in to be terminated (assuming that the Java service being removed is the only Java service running in this JVM).

    Syntax

    REMOVE SERVICE <Service Name>
    

    SERVICE specifies the name of the service to remove.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from REMOVE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain nothing.

    Examples

    8.17.6 FREE

    FREE returns the results of a completed request that was submitted using the kSTAFReqQueue or kSTAFReqQueueRetain options (see 6.2.5, "STAFSubmit2" for more information). This command also removes the request from the request list.

    Syntax

    FREE REQUEST <Request Number> [FORCE]
    

    REQUEST specifies which request should be freed.

    FORCE must be specified if any process other than the originating process tries to FREE the request's results.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from FREE are documented in Appendix A, "API Return Codes".

    Results

    If successful, the result buffer for a FREE request will contain a marshalled <Map:STAF/Service/Service/FreeRequestInfo> representing the results of the completed request. The map is defined as follows:

    Table 95. Definition of map class STAF/Service/Service/QueryRequest
    Description: This map class represents the results of a completed request.
    Key Name Display Name Type Format / Value
    rc Return Code <String>
    result Result <String>
    Notes:
    1. The value for "Return Code" is the return code from the request.
    2. The value for "Result" is the result buffer from the request.

    Examples


    8.18 Shutdown Service

    8.18.1 Description

    The SHUTDOWN service is an internal STAF service. It provides the following commands.

    8.18.2 SHUTDOWN

    SHUTDOWN, as the name implies, shuts down the STAFProc program.

    Syntax

    SHUTDOWN
    

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SHUTDOWN are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a SHUTDOWN command.

    8.18.3 NOTIFY REGISTER/UNREGISTER

    NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when the STAF Process is SHUTDOWN.

    Syntax

    NOTIFY <REGISTER | UNREGISTER> [MACHINE <Machine>]  [PRIORITY <Priority>]
           [HANDLE <Handle> | NAME <Name>]
    

    REGISTER indicates you want to register a shutdown notification. The type of the notification message will be STAF/Shutdown with a blank message.

    UNREGISTER indicates you want to unregister a shutdown notification

    MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables.

    Security

    These commands require trust level 3.

    Return Codes

    All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.

    Examples

    Goal: Register the current process for a priority 3 shutdown notification.

    NOTIFY REGISTER PRIORITY 3
    

    Goal: Register to have a shutdown notification sent to all processes with registered name ShutdownCatcher on machine EventSrv1.

    NOTIFY REGISTER MACHINE EventSrv1 NAME ShutdownCatcher
    

    Goal: Unregister the shutdown notification for handle 43.

    NOTIFY UNREGISTER HANDLE 43
    

    8.18.4 NOTIFY LIST

    NOTIFY LIST allows you to view the shutdown notification list.

    Syntax

    NOTIFY LIST
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a NOTIFY LIST request will contain a marshalled <List> of <Map:STAF/Service/Shutdown/Notifiee> representing a list of all the registered notifiees. The map is defined as follows:

    Table 96. Definition of map class STAF/Service/Shutdown/Notifiee
    Description: This map class represents a registered shutdown notifiee.
    Key Name Display Name Type Format / Value
    priority Priority <String> 'Stdout' | 'Stderr' or a file name
    machine Machine <String> 'Enabled' | 'Disabled'
    notifyBy Notify By <String> 'Name' | 'Handle'
    notifiee Notifiee <String>
    Notes: If the "Notify By" value is 'Name', the notifiee will be notified by handle name and the "Notifiee" value will be the handle name. Otherwise, if the "Notify By" value is 'Handle', the notifiee will be notified by handle and the "Notifiee" value will be the handle number.

    Examples


    8.19 Trace Service

    8.19.1 Description

    The TRACE service is one of the internal STAF services. It provides the following trace commands.

    The purpose of the Trace service is to allow you to control the trace messages recorded for STAF services. For example, if you are experiencing a problem with a STAF service or a request to a STAF service, you can specify various STAF trace points and/or STAF service(s) to be enabled for tracing to record additional trace messages which can help you resolve the problem.

    Note: If you enable one or more of the "service" tracepoints (e.g. ServiceRequest, ServiceResult, ServiceError, ServiceAccessDenied, or RemoteRequests), these trace messages will only be reported for the services you have enabled for tracing.

    Format of Trace Messages

    The format of each trace message is the following

    <Timestamp>;<Thread>;<Trace Point>;<Message>
    

    where:

    <Timestamp> is the date/time of the message.

    <Thread> is the thread on which the message originated.

    <Trace Point> is the hexadecimal representation of the message's trace point. See table 8.19.2, "Trace Points Reference" for a list of trace points.

    <Message> is the actual trace message. Private data will be masked.

    Examples of Trace Messages

    Here's an example of a ServiceManagement trace message:

    20050811-16:20:50;1;00000010;Service HELP: Initializing
    

    Here's an example of a Warning trace message:

    20050811-10:10:50;4836;00000400;STAFConnectionManager::makeConnection - Attempt 
    #1 of 2 (Delay 41 milliseconds), RC: 16, Result: STAFConnectionProviderConnect: 
    Timed out connecting to endpoint: select() timeout: 22, Endpoint: client1
    

    Here's an example of ServiceRequest and ServiceResult trace messages:

    20050811-10:33:54;4836;00000001;PROCESS Service Request - Client: local://local,
     Handle: 30, Process: STAF/Client, Request: start command date returnstdout wait
     
    20050811-10:33:54;4836;00000002;PROCESS Service Result (0) - Client: local://loc
    al, Handle: 30, Process: STAF/Client, Request: start command date returnstdout w
    ait, Result: {
      Return Code: 0
      Key        : <None>
      Files      : [
        {
          Return Code: 0
          Data       : Thu Aug 11 10:33:54 CDT 2005
     
        }
      ]
    }
    

    8.19.2 Trace Points Reference

    The following are the valid trace points along with their hexadecimal representation and their descriptions. The hexadecimal representation of a trace point is logged in each trace message. Trace points are not case sensitive.

    Table 97. Trace point hexadecimal representation

    Hex Trace point Description
    00000001 ServiceRequest The trace point which causes a trace message to be generated for every incoming service request before it is processed by the service.
    00000002 ServiceResult The trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. Note that the trace message will include the return code and result for the service request. This tracepoint overrides the ServiceComplete, ServiceError and ServiceAccessDenied tracepoints.
    00000004 ServiceError The trace point which causes a trace message to be generated for every incoming service request which results in a non-zero error code. Note that the trace message will include the return code and result for the service request. This tracepoint overrides the ServiceAccessDenied tracepoint.
    00000008 ServiceAccessDenied The trace point which causes a trace message to be generated for every incoming service request which results in an "Insufficient Trust Level" (aka "Access Denied") error code.
    00000010 ServiceManagement The trace point which causes a trace message to be generated for service management operations such as service initialization and termination.
    00000020 RemoteRequests The trace point which enables trace message to be generated for requests destined for other machines.
    00000100 Error The trace point which causes a trace message to be generated for error conditions that STAF detects, such as broken communication connections and fatal STAF Service errors. The Error trace point is turned on by default.
    00000200 Registration The trace point which causes a trace message to be generated for every registration or unregistration done by a process.
    00000400 Warning The trace point which causes a trace message to be generated for warning conditions that STAF detects.
    00000800 Info The trace point which causes a trace message to be generated for information conditions that STAF detects.
    00001000 Deprecated The trace point which causes a trace message to be generated for deprecated options that STAF detects. A deprecated option is not recommended for use, generally due to improvements, and a replacement option is usually given. Deprecated options may be removed in future implementations. The Deprecated trace point is turned on by default.
    00002000 Debug The trace point which causes a trace message to be generated for debug conditions that STAF detects.
    00004000 ServiceComplete The trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. Note that the trace message will include the return code and result length for the service request, but not the result data. This tracepoint overrides the ServiceError and ServiceAccessDenied tracepoints.

    8.19.3 Enable

    ENABLE allows you to enable trace points and STAF services for tracing. See table 8.19.2, "Trace Points Reference" for a list of valid trace points.

    Note: You can enable services that aren't currently registered and they will begin tracing when they are registered with STAF.

    Syntax

    ENABLE ALL  [ TRACEPOINTS | SERVICES ]
    ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    ENABLE TRACEPOINT <Trace point> [ TRACEPOINT <Trace point> ]...
    ENABLE SERVICE <Service> [ SERVICE <Service> ]...
    

    ALL indicates to enable tracing for all trace points and/or services

    TRACEPOINTS indicates a list of trace points to be enabled for tracing. The trace points in the list should be separated by spaces. This option will resolve variables.

    SERVICES indicates a list of services to be enabled for tracing. The services in the list should be separated by spaces. This option will resolve variables.

    TRACEPOINT indicates which trace point should be enabled for tracing. This option will resolve variables.

    SERVICE indicates which service should be enabled for tracing. This option will resolve variables.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from ENABLE are documented in Appendix A, "API Return Codes".

    Results

    For ENABLE the result buffer will be empty if there are no errors

    Examples

    8.19.4 Disable

    DISABLE allows you to disable trace points and STAF services for tracing. See table 8.19.2, "Trace Points Reference" for a list of valid trace points.

    Syntax

    DISABLE ALL  [ TRACEPOINTS | SERVICES ]
    DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    DISABLE TRACEPOINT <Trace point> [ TRACEPOINT <Trace point> ]...
    DISABLE SERVICE <Service> [ SERVICE <Service> ]...
    

    ALL indicates to disable tracing for all trace points and/or services

    TRACEPOINTS indicates a list of trace points to be disabled for tracing. The trace points in the list should be separated by spaces. This option will resolve variables.

    SERVICES indicates a list of services to be disabled for tracing. The services in the list should be separated by spaces. This option will resolve variables.

    TRACEPOINT indicates which trace point should be disabled for tracing. This option will resolve variables.

    SERVICE indicates which service should be disabled for tracing. This option will resolve variables.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from DISABLE are documented in Appendix A, "API Return Codes".

    Results

    For DISABLE the result buffer will be empty if there are no errors

    Examples

    8.19.5 Purge

    PURGE removes all unregistered services from the service list

    Syntax

    PURGE
    

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from PURGE are documented in Appendix A, "API Return Codes".

    Results

    For PURGE the result buffer will be empty if there are no errors.

    Examples

    8.19.6 List

    LIST Returns a list of current settings including trace destination and default service state, and a list of the current tracing statuses for all tracepoints and services

    Syntax

    LIST [SETTINGS]
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer for a LIST request will contain a marshalled <Map:STAF/Service/Trace/TraceInfo> representing the current trace settings. The maps are defined as follows:

    Table 98. Definition of map class STAF/Service/Trace/TraceInfo
    Description: This map class represents the current trace settings.
    Key Name Display Name Type Format / Value
    tracingTo Tracing To <String> | <List> of <String>
    fileMode File Mode <String> | <None> 'Replace' | 'Append'
    defaultServiceState Default Service State <String> 'Enabled' | 'Disabled'
    maxServiceResultSize Maximum Service Result Size <String>
    tracePoints Trace Points <Map:STAF/Service/Trace/Tracepoint>
    services Services <Map:STAF/Service/Trace/Service>
    Notes:
    1. "Tracing To" indicates the current trace output destination. If there is only one trace output destination, it will be set to either 'Stdout', 'Stderr', or the file name. If there is more than one trace output destination, it will be set to a marshalled <List> of <String> with the first entry containing 'Stdout' or 'Stderr' and the second entry containing the file name.
    2. If the current trace output destination is set to a file, "File Mode" indicates whether the file will be replaced or appended to. "File Mode" will be set to <None> if the trace output destination is Stdout or Stderr.

    Table 99. Definition of map class STAF/Service/Trace/Tracepoint
    Description: This map class represents the tracepoints and their trace states.
    Key Name Display Name Type Format / Value
    INFO Info <String> 'Enabled' | 'Disabled'
    WARNING Warning <String> 'Enabled' | 'Disabled'
    ERROR Error <String> 'Enabled' | 'Disabled'
    SERVICEREQUEST ServiceRequest <String> 'Enabled' | 'Disabled'
    SERVICERESULT ServiceResult <String> 'Enabled' | 'Disabled'
    SERVICEERROR ServiceError <String> 'Enabled' | 'Disabled'
    SERVICEACCESSDENIED ServiceAccessDenied <String> 'Enabled' | 'Disabled'
    REMOTEREQUESTS RemoteRequests <String> 'Enabled' | 'Disabled'
    REGISTRATION Registration <String> 'Enabled' | 'Disabled'
    DEPRECATED Deprecated <String> 'Enabled' | 'Disabled'
    DEBUG Debug <String> 'Enabled' | 'Disabled'

    Table 100. Definition of map class STAF/Service/Trace/Service
    Description: This map class represents the services and their trace states.
    Key Name Display Name Type Format / Value
    <ServiceName> <ServiceName> <String> 'Enabled' | 'Disabled'
    Notes: This map is dynamically generated at the time of the LIST request based on the services in the trace status list at that time. It's keys will be the names of the internal services plus any external services that have been registered and any other services for which tracing has been explicitly set.

    Examples

    8.19.7 Set

    Allows you to set the destination for the tracing information, the default tracing state for new services, or the maximum size (in characters) of the service result string to write to the trace output when the ServiceResult tracepoint is enabled.

    Syntax

    SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] >
    SET DEFAULTSERVICESTATE < Enabled | Disabled >
    SET MAXSERVICERESULTSIZE <Number>[k|m]
    

    DESTINATION TO indicates to set the destination for the tracing information. Note that you must specify at least one of STDOUT, STDERR, or FILE. You can specify both STDOUT and FILE or both STDERR and FILE.

    STDOUT indicates that trace messages should be sent to the standard output device (Stdout). Note that you can specify that trace messages should be sent to both Stdout and a file.

    STDERR indicates that trace messages should be sent to the standard error device (Stderr). Note that you can specify that trace messages should be sent to both Stderr and a file.

    FILE indicates that trace messages should be sent to the indicated file. Note that the path to the file must already exist. This option will resolve variables.

    APPEND indicates that destination trace file will be appended to if it exists. If this option is not specified, the destination trace file will be replaced if it exists. This option can only be specified if the FILE option was specified.

    DEFAULTSERVICESTATE sets the default tracing state for services that have not yet registered with STAF. The default tracing state for services is enabled. This option will resolve variables.

    MAXSERVICERESULTSIZE specifies the maximum size (in characters) of the service result string to write to the trace output when the ServiceResult tracepoint is enabled. If not specified, the default is 0 (which indicates to write the entire service result string to the trace output). This value may be expressed in bytes, kilobytes, or megabytes. Its format is <Number>[k|m] where <Number> is an integer >= 0 and indicates bytes unless one of the following case-insensitive suffixes is specified: k (for kilobytes) or m (for megabytes). The calculated value cannot exceed 4294967295 bytes. Examples of valid values include 100000, 500k, or 5m.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    For SET the result buffer will be empty

    Examples


    8.20 Trust Service

    8.20.1 Description

    The TRUST Service is one of the internal STAF services. It allows you to query and set the trust entries. It provides the following commands.

    8.20.2 SET

    SET will set the default trust level or the trust level for a specific machine or user.

    Syntax

    SET <MACHINE <Machine> | USER <User> | DEFAULT> LEVEL <Level>
    

    MACHINE indicates a machine for which to set a trust level. This option will resolve variables. The format for <Machine> is:

      [<Interface>://]<System Identifier>
    
    where:

    Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).

    Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).

    Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.

    Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)

    USER indicates a user for which to set a trust level. This option will resolve variables. The format for <User> is:

      [<Authenticator>://]<User Identifier>
    
    where:

    Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).

    DEFAULT specifies that you want to set the default trust level.

    LEVEL specifies the level of trust you wish to set. This option will resolve variables.

    Notes:

    1. If multiple trust specifications match the same user, STAF will rank the matching specifications as documented in section "How to determine Effective Trust for a User" and use the match with the highest (i.e. lowest numbered) rank. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.
    2. If multiple trust specifications match the same system, STAF will rank the matching specifications as documented in section "How to determine Effective Trust for a Machine" and use the match with the highest (i.e. lowest numbered) rank. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.
    3. User trust specifications override machine trust specifications.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a SET command.

    Examples

    8.20.3 GET

    GET will return the effective trust level of a specific machine and, optionally, for a specific user.

    Syntax

    GET MACHINE <Machine> [USER <User>]
    

    MACHINE specifies the machine for which to return the effective trust level. This option will resolve variables. The format for <Machine> is:

      [<Interface>://]<System Identifier>
    
    where:

    Wildcard patterns, '*' and '?', should not be specified. If a port is included (e.g. @6500) at the end of the machine value, it will be removed.

    If the machine has a matching MACHINE trust entry, the effective trust level is the level specified in the MACHINE trust entry. Otherwise, the effective trust level is the default trust level.

    USER specifies the user for which to return the effective trust level. This option will resolve variables. The format for <User> is:

      [<Authenticator>://]<User Identifier>
    
    where:

    Wildcard patterns, '*' and '?', cannot be specified.

    If the user has a matching USER trust entry, the effective trust level is the level specified in the USER trust entry. Otherwise, if the machine has a matching MACHINE trust entry, the effective trust level is the level specified in the MACHINE trust entry. Otherwise, the effective trust level is the default trust level.

    Notes:

    1. If multiple trust specifications match the same user, STAF will rank the matching specifications as documented in section "How to determine Effective Trust for a User" and use the match with the highest (i.e. lowest numbered) rank. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.
    2. If multiple trust specifications match the same system, STAF will rank the matching specifications as documented in section "How to determine Effective Trust for a Machine" and use the match with the highest (i.e. lowest numbered) rank. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.
    3. User trust specifications override machine trust specifications.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the effective trust level of the given machine.

    Examples

    For the following examples, assume the trust entries for machines and users are as follows with tcp as the default network interface and SampleAuth as the default authenticator:

    Type    Entry                         Trust Level
    ------- ----------------------------- -----------
    Default <None>                        1
    Machine *://*.austin.ibm.com          2
    Machine *://client1.austin.ibm.com    5
    Machine *://client3.austin.ibm.com    3
    Machine local://local                 5
    Machine tcp://client2.austin.ibm.com  0
    User    SampleAuth://*@company.com    3
    User    SampleAuth://Jane@company.com 4
    User    SampleAuth://John@company.com 5
    

    Here are some GET requests and their results:

    Request:  GET MACHINE client1.austin.ibm.com
    Result :  5
    

    Request:  GET MACHINE tcp://client2.austin.ibm.com
    Result :  0
    

    Request:  GET MACHINE client3.austin.ibm.com
    Result :  3
    

    Request:  GET MACHINE client4.austin.ibm.com
    Result    2
    

    Request:  GET MACHINE server1.raleigh.ibm.com
    Result:   1
    

    Request:  GET USER John@company.com MACHINE client3.austin.ibm.com
    Result :  5
    

    Request:  GET USER SampleAuth://Jane@company.com MACHINE client1.austin.ibm.com
    Result :  4
    

    Request:  GET USER Henry@company.com MACHINE client1.austin.ibm.com
    Result :  3
    

    Request:  GET USER Sally@mybusiness.com MACHINE client1.austin.ibm.com
    Result :  5
    

    Request:  GET USER Sally@mybusiness.com MACHINE server1.raleigh.ibm.com
    Result :  1
    

    8.20.4 LIST

    LIST will return the default trust level and a list of the trust entries for machines and users.

    Syntax

    LIST
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a marshalled <List> of <Map:STAF/Service/Trust/Entry>, representing all the trust entries. The first trust entry in the list will be for the default trust entry, followed by trust entries for machines, and then followed by trust entries for users. The map is defined as follows:

    Table 101. Definition of map class STAF/Service/Trust/Entry
    Description: This map class represents a trust entry.
    Key Name Display Name Type Format / Value
    type Type <String> 'Default' | 'Machine' | 'User'
    entry Entry <String> | <None> <Machine Spec> | <User Spec)
    trustLevel Trust Level <String> '0' - '5'
    Notes:
    1. The value for "Entry" will be <None> for the default trust entry.
    2. Each trust entry for a machine, aka <Machine Spec>, has the following format:
      <Interface>://<System Identifier>
    3. Each trust entry for a user, aka <User Spec>, has the following format:
      <Authenticator>://<User Identifier>

    Examples

    8.20.5 DELETE

    DELETE will remove the explicit trust entry for the specified machine or user.

    Syntax

    DELETE MACHINE <Machine> | USER <User>
    

    MACHINE specifies the machine for which you wish to delete the specific trust entry. This option will resolve variables. The format for <Machine> is:

      [<Interface>://]<System Identifier>
    
    where:

    If a port is included (e.g. @6500) at the end of the machine value, it will be removed.

    USER specifies the user for which you wish to delete the specific trust entry. This option will resolve variables. The format for <User> is:

      [<Authenticator>://]<User Identifier>
    
    where:

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples


    8.21 Variable (VAR) Service

    8.21.1 Description

    The Variable Service, called VAR, is one of the internal STAF services. It allows you to manage the system, shared, and per-process variable pools. It provides the following commands.

    8.21.2 SET

    SET will set a variable to a certain value. The variable is created if it does not exist.

    Note that you may SET multiple variables with a single request.

    Syntax

    SET [SYSTEM | SHARED | HANDLE <Handle>] [FAILIFEXISTS]
        VAR <Name=Value> [VAR <Name=Value>]...
    

    SYSTEM specifies that you want to set the value of the variable in the system variable pool.

    SHARED specifies that you want to set the value of the variable in the shared variable pool.

    HANDLE indicates that you want to set the value of the variable in the variable pool associated with the specified handle.

    If options SYSTEM, SHARED, and HANDLE are not specified, the variable will be set in the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be set in the system variable pool.

    FAILIFEXISTS specifies that the set request should fail with return code 49 (Already Exists) if the variable already exists in the specified variable pool and its current value will be returned in the result. If this option is not specified and the variable already exists, the variable's value will be updated.

    VAR specifies the name of a variable and the value to which it should be set. Its format must be Name=Value. You can specify this option multiple times to set multiple variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    If multiple variables are set via a single SET request and all variables were set successfully, the return code will be 0. If one or more variables were not set successfully, the return code will be set to the return code of the first variable that could not be set successfully. Note that all variables specified will be attempted to be set.

    Results

    If successful, the result buffer will contain no data.

    If the request failed, the result buffer's contents are based on whether the VAR option was specified once or multiple times as follows:

    Examples

    8.21.3 GET

    GET will retrieve the value of a variable.

    Note: You almost never want to use the GET command. Instead, you should use RESOLVE to retrieve the value of a variable.

    Syntax

    GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name>
    

    SYSTEM specifies that you want to get the value of the variable from the system variable pool.

    SHARED specifies that you want to get the value of the variable from the shared variable pool.

    HANDLE indicates that you want to get the value of the variable from the variable pool associated with the specified handle.

    If options SYSTEM, SHARED, and HANDLE are not specified, the value of the variable will be retrieved from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be retrieved from the system variable pool.

    VAR specifies the name of the variable whose value you want to get.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the value of the variable.

    Examples

    8.21.4 LIST

    LIST will return a list of all variables and their values.

    Syntax

    LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]]
    

    SYSTEM specifies that you want the list of variables from the system variable pool only.

    SHARED specifies that you want the list of variables from the shared variable pool only.

    HANDLE specifies that you want the list of variables from the handle variable pool only.

    ASHANDLE indicates that you want the list of a merged set of variables from the specified handle's variable pool, its system's shared variable pool, and its system's system variable pool. Variables in a pool earlier in the list override variables in a pool later in the list.

    REQUEST with a request number indicates that you want a list of a merged set of variables which will use variables from the originating handle's pool associated with the request number, the originating system's shared pool, the local system's shared pool, and the local system's system pool if the request came from remote; otherwise, will use the originating handle's pool associated with the request number, the local system's shared pool, and the local system's system pool if the request came from local. Variables in a pool earlier in the list override variables in a pool later in the list.

    If a LIST REQUEST request is made without specifying a request number, the list is constructed in the context of the LIST REQUEST request, itself.

    If a LIST request is made without specifying SYSTEM, SHARED, HANDLE, ASHANDLE, and REQUEST, the behavior will be identical to a LIST REQUEST request being made with no request number specified.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a marshalled <Map:STAF/Service/Var/VarInfo> with an entry for each variable. The map is defined as follows:

    Table 103. Definition of map class STAF/Service/Var/VarInfo
    Description: This map class represents the variables.
    Key Name Display Name Type Format / Value
    <Variable Name> <Variable Name> <String>
    Notes: This map is dynamically generated with the key being a variable name and the value being the value for the variable.

    If the request is submitted from the command line, the result, in default format, could look like:

    Bad String                      : SYS3175
    Good String                     : Command completed successfully
    STAF/Config/BootDrive           : C:
    STAF/Config/CodePage            : IBM-437
    STAF/Config/ConfigFile          : C:\staf\bin\STAF.cfg
    STAF/Config/DefaultAuthenticator: AuthSample
    STAF/Config/DefaultInterface    : tcp
    STAF/Config/InstanceName        : STAF
    STAF/Config/Machine             : client1.company.com
    STAF/Config/MachineNickname     : client1
    STAF/Config/Mem/Physical/Bytes  : 804175872
    STAF/Config/Mem/Physical/KB     : 785328
    STAF/Config/Mem/Physical/MB     : 766
    STAF/Config/OS/MajorVersion     : 5
    STAF/Config/OS/MinorVersion     : 0
    STAF/Config/OS/Name             : Win2000
    STAF/Config/OS/Revision         : 2195
    STAF/Config/Processor/NumAvail  : 1
    STAF/Config/Sep/Command         : & 
    STAF/Config/Sep/File            : \
    STAF/Config/Sep/Line            :
     
    STAF/Config/Sep/Path            : ;
    STAF/Config/STAFRoot            : C:\STAF
    STAF/Config/StartupTime         : 20080421-14:15:37
    STAF/DataDir                    : C:\STAF\data\STAF
    STAF/Env/ALLUSERSPROFILE        : C:\Documents and Settings\All Users
    STAF/Env/APPDATA                : C:\Documents and Settings\Administrator\Application Data
    STAF/Env/CLASSPATH              : .;C:\STAF\lib\JSTAF.jar
    STAF/Env/CommonProgramFiles     : C:\Program Files\Common Files
    STAF/Env/COMPUTERNAME           : CLIENT1
    STAF/Env/ComSpec                : C:\WINNT\system32\cmd.exe
    STAF/Env/CVS_RSH                : ssh
    STAF/Env/HOMEDRIVE              : C:
    STAF/Env/HOMEPATH               : \Documents and Settings\Administrator
    STAF/Env/INCLUDE                : C:\Program Files\ObjREXX\API
    STAF/Env/LIB                    : C:\Program Files\ObjREXX\API
    STAF/Env/LOGONSERVER            : \\CLIENT1
    STAF/Env/NUMBER_OF_PROCESSORS   : 1
    STAF/Env/OS                     : Windows_NT
    STAF/Env/Os2LibPath             : C:\WINNT\system32\os2\dll;
    STAF/Env/Path                   : C:\ibmjdk1.4.2\bin;C:\STAF\bin;C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\cygwin\bin;
    STAF/Env/PATHEXT                : .COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.RB;.RBW
    STAF/Env/PD_SOCKET              : 6874
    STAF/Env/PDBASE                 : C:\PROGRA~1\IBM\INFOPR~1
    STAF/Env/PDHOST                 :
    STAF/Env/PROCESSOR_ARCHITECTURE : x86
    STAF/Env/PROCESSOR_IDENTIFIER   : x86 Family 15 Model 2 Stepping 7, GenuineIntel
     
    STAF/Env/PROCESSOR_LEVEL        : 15
    STAF/Env/PROCESSOR_REVISION     : 0207
    STAF/Env/ProgramFiles           : C:\Program Files
    STAF/Env/PROMPT                 : $P$G
    STAF/Env/SOUNDPATH              : C:\WINNT
    STAF/Env/SystemDrive            : C:
    STAF/Env/SystemRoot             : C:\WINNT
    STAF/Env/TEMP                   : C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp
    STAF/Env/TMP                    : C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp
    STAF/Env/USERDOMAIN             : CLIENT1
    STAF/Env/USERNAME               : Administrator
    STAF/Env/USERPROFILE            : C:\Documents and Settings\Administrator
    STAF/Env/windir                 : C:\WINNT
    STAF/Service/NC/Persist         : True
    STAF/Version                    : 3.3.0
    WebServer                       : testsrv1.test.austin.ibm.com
    

    Examples

    8.21.5 RESOLVE

    RESOLVE allows you to have all variable references in a string resolved to their values. A variable reference is denoted by surrounding the variable in curly braces, for example, {WebServer}. Recursive and compound variable references are allowed (see the examples).

    Note that you may RESOLVE multiple strings with a single request.

    Because of this special significance of "{", if you do not want variable substitution performed, use a caret, "^", as an escape character for "{" and "^", or specify the IGNOREERRORS option. Note that a caret cannot be used as an escape character within a variable reference (see the examples).

    Syntax

    RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] 
            STRING <String> [STRING <String>]... [IGNOREERRORS]
    

    SYSTEM specifies that only variables from the system variable pool should be used to resolve a variable reference.

    SHARED specifies that only variables from the shared variable pool should be used to resolve a variable reference.

    HANDLE specifies that only variables from the handle variable pool should be used to resolve a variable reference.

    ASHANDLE indicates the variable reference should try to be resolved from the specified handle's variable pool, its system's shared variable pool, and its system's system variable pool. Variables in a pool earlier in the list override variables in a pool later in the list.

    REQUEST with a request number indicates the variable reference should try to be resolved from the originating handle's pool associated with the specified request number, the originating system's shared pool, the local system's shared pool, and the local system's system pool if the request came from remote; otherwise, will use the originating handle's pool associated with the specified request number, the local system's shared pool, and the local system's system pool if the request came from local. Variables in a pool earlier in the list override variables in a pool later in the list.

    If the REQUEST option is specified without specifying a request number, variable resolution is done in the context of the RESOLVE request itself. Also, if you don't specify the SYSTEM, SHARED, HANDLE, ASHANDLE, or REQUEST option, the behavior will be the same as when you specify the REQUEST option without specifiying a request number.

    STRING specifies a string that may contain one or more variable references.

    IGNOREERRORS specifies to not assume that every "{" in the string being resolved denotes a reference to a STAF variable. When using this option, you will not get a RC 13 (Variable Does Not Exist) or RC 15 (Invalid Resolve String) error because:

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from RESOLVE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain results based on whether the STRING option was specified once or multiple times:

    Examples

    For the following examples, assume the following variables are in System1's system variable pool

    a=Partridge
    b=Doves
    c=Hens
    d=Birds
    e=Rings
    
    the following variables are in System1's shared variable pool
    a=Happy
    b=Sleepy
    
    the following variables are in System1's originating handle variable pool
    a=One
    
    the following variables are in System2's system variable pool
    a=Geese
    b=Swans
    c=Maids
    d=Ladies
    e=Lords
    
    the following variables are in System2's shared variable pool
    d=Grumpy
    e=Dopey
    
    and the following variables are in the System1's variable pool associated with handle 71
    a=Dogs 
    b=Cats
    
    Let's assume the following requests are done from System1:

    The following examples show the use of a caret (^) as an escape character for "{" and "^". Assume the following variables are in the system variable pool for these examples:

    h=Hi
    Hi=HI
    ^Hi=Hello
    

    Note that {^{h}} shows that a caret cannot be used as an escape character within a variable reference.

    Here's an example of resolving multiple strings in a single RESOLVE request.

    Here's an example of using the IGNOREERRORS option on a VAR RESOLVE request:

    8.21.6 DELETE

    DELETE will remove the given variable from the appropriate variable pool.

    Note that you may DELETE multiple variables with a single request.

    Syntax

    DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]...
    

    SYSTEM specifies that you want to delete the variable from the system variable pool.

    SHARED specifies that you want to delete the variable from the shared variable pool.

    HANDLE indicates that you want to delete the variable from the variable pool associated with the specified handle.

    If options SYSTEM, SHARED, and HANDLE are not specified, the variable will be deleted from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be deleted from the system variable pool.

    VAR specifies the name of the variable you want to delete.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    If multiple variables are deleted via a single DELETE request and all variables were deleted successfully, the return code will be 0. If one or more variables were not deleted successfully, the return code will be set to the return code of the first variable that could not be deleted successfully. Note that all variables specified will be attempted to be deleted.

    Results

    If successful, the result buffer will contain no data.

    If the request failed, the result buffer's contents are based on whether the VAR option was specified once or multiple times as follows:

    Examples


    8.22 Zip Service

    8.22.1 Description

    The Zip service is an external STAF service that provides the following functions:

    The purpose of the Zip service is to allow a test case to easily work with Zip archives.

    By using of Zlib compression library, the Zip service can create, extract, delete and manage PKZip, WinZip and Jar compatible archives.

    The Zip service supports the following features: create / extract PKZip, WinZip, and Jar compatible archives; save / restore owner, group and permission information on files and directories; delete file(s) from a Zip archive; list content of a Zip archive, append file / directory to an existing Zip archive, etc.

    8.22.2 Registration

    The Zip service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    SERVICE <Name> LIBRARY STAFZip
    

    <Name> is the name by which the Zip service will be known on this machine. The recommended name of the Zip service is "ZIP".

    Example

    service ZIP library STAFZip
    

    8.22.3 UNZIP

    Extract all entries (or specified files and/or directories) from a Zip archive to a specified directory.

    Syntax

    UNZIP  ZIPFILE <Name> TODIRECTORY <Name>
           [FILE <Name>]... [DIRECTORY <Name>]...
           [RESTOREPERMISSION] [REPLACE]
    

    ZIPFILE contains the fully qualified ZIP archive name.

    TODIRECTORY contains the fully qualified output directory name.

    FILE contains the fully qualified file name in the ZIP archive to be unzipped.

    DIRECTORY contains the fully qualified directory name in the ZIP archive to be unzipped. Subdirectories in the directory are recursively unzipped.

    RESTOREPERMISSION indicates that the owner, group and permission attributes of the file will be restored.

    REPLACE indicates that the files/directories will be over written they already exist in the specified output directory.

    Note: If you specify multiple FILE and/or DIRECTORY options, the files specified will be unzipped, followed by the directories specified. If an error occurs while unzipping a file or directory, the unzip request will not continue unzipping any remaining files/directories and will return an error.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", UNZIP also returns codes documented in 8.22.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a UNZIP command.

    Examples

    8.22.4 ADD (aka ZIP)

    Adds a file or directory into a Zip archive file. If the Zip archive file does not exist, it will be created and the file or directory will be added to it. If the Zip archive file already exists, the file or directory will be added to it.

    Syntax

    ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
        [RELATIVETO <Directory>]
    
    or
    ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
        [RELATIVETO <Directory>]
    

    An ADD request performs the same function as a ZIP request. An ADD request is preferred. The ZIP request is deprecated and will generate a trace message with a Deprecated tracepoint.

    ZIPFILE contains the fully qualified name of a Zip archive file. If the Zip archive file does not exist, it will be created, but the directory path specified for it must already exist.

    FILE contains the fully qualified file name you want to add into the ZIP archive.

    DIRECTORY contains the fully qualified directory name you want to add info the ZIP archive.

    RELATIVETO contains the prefix to be excluded from the fully qualified file name or directory name that is to be added into the ZIP archive.

    RECURSE indicates that the all the files and subdirectories in the given directory will be added recursively.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", Zip also returns codes documented in 8.22.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a ZIP command.

    Examples

    8.22.5 DELETE

    Delete one or more files from ZIP archive.

    Syntax

    DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
    

    ZIPFILE contains the fully qualified ZIP archive name.

    FILE contains the fully qualified file name to be deleted from the zip archive.

    CONFIRM confirms you really want to delete the file from zip archive.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", Delete also returns codes documented in 8.22.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a DELETE command.

    Examples

    8.22.6 LIST

    List the content of a ZIP archive.

    Syntax

    LIST ZIPFILE <Name>
    

    ZIPFILE contains the fully qualified ZIP archive name.

    Security

    This command requires trust level 3.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns codes documented in 8.22.7, "Zip Error Code Reference"

    Results

    On successful return, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Zip/ZipInfo> representing content of the Zip archive. The map is defined as follows:

    Table 106. Definition of map class STAF/Service/Zip/ZipInfo
    Description: This map class represents an entry in Zip archive.
    Key Name Display Name Type Format / Value
    length Length <String>
    method Method <String>
    size Size <String>
    ratio Ratio <String>
    date Date <String>
    time Time <String>
    crc-32 CRC-32 <String>
    name Name <String>
    Notes:
    1. The "Length" value is the uncompressed size of the file.
    2. The "Method" value is compression method, often in the format of <Compression Method>:<Compression level> used to compress the file. For example "Defl:X", "Defl" stands for "Deflated", "X" stands for "Maximum compression". Compression level can also contain the following values: "N" stands for "Normal compression", "F" stands for "Fast and Super fast compression". Compression method can also contain the following values: "Stored" stands for "No compression", "Unkn." stands for "Unknown compression method".
    3. The "Size" value is the compressed size of the file.
    4. The "Ratio" value is the compression ratio of the file.
    5. The "Date" value is the date stamp of the original file.
    6. The "Time" value is the time stamp of the original file.
    7. The "CRC-32" value is the CRC-32 value of the file.
    8. The "Name" value is the relative name of the file.

    Examples

    8.22.7 Zip Error Code Reference

    In addition to the common STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Zip return codes are defined:

    Table 107. Zip Service Return Codes
    Error Code Meaning Comment
    4001 General zip error A general error occurred, additional error message can be found in result buffer.
    4002 Not enough memory There is not enough memory in the system.
    4003 Change file size error: <file> Error changing the file size.
    4004 Error creating directory: <dir> Error creating directory in the file system.
    4005 Invalid zip file: <file> Invalid zip file format.
    4006 Bad CRC Bad CRC in the zip archive.
    4007 Invalid owner group Invalid owner / group on the system when restore permission.
    4008 Invalid file mode Invalid file mode.


    9.0 Log Utilities

    Some utilities are provided to assist in viewing and formatting STAF log files and the JVM Log files.


    9.1 STAF Log Viewer Class

    9.1.1 Description

    The STAFLogViewer class provides a Java GUI that can display any STAF log on any machine currently running STAF. A STAF log is a binary log file that has been created by the STAF Log service. This Java class submits requests to STAF, so STAF has to be running.

    This Java class can be run as an application via the command line or can be run via another Java program.

    For more information on how to use the STAFLogViewer class, see section "3.6.1 Class STAFLogViewer" in the STAF Java User's Guide.


    9.2 JVM Log Viewer Class

    9.2.1 Description

    The STAFJVMLogViewer class provides a Java GUI that can display a JVM Log for any STAF Java service that is currently registered. Each Java service that is registered with STAF runs in a JVM (Java Virtual Machine). A JVM Log is a text log file that is associated with each JVM created by STAF. Note that more than one Java service may use the same JVM (and thus share the same JVM Log file) depending on the options used when registering the service. Section 4.4, "Service Registration" provides more information on registering STAF Java services using the JSTAF library.

    A JVM Log file contains JVM start information such as the date/time when the JVM was created, the JVM executable, and the J2 options used to start the JVM. It also any other information logged by the JVM. This includes any errors that may have occurred while the JVM was running and any debug information output by a Java service. Also, the JVM Log for the STAX service contains the output from any print statements that are used within a <script> element in a STAX xml job file which is useful when debugging Python code contained in a <script> element. When a problem occurs with a STAF Java service, you should always check it's JVM Log as it may contain information to help debug the problem.

    STAF stores JVM Log files in the {STAF/DataDir}/lang/java/jvm/<JVMName> directory. STAF retains a configurable number of JVM Logs (five by default) for each JVM. The current JVM log file is named JVMLog.1 and older saved JVM log files, if any, are named JVMLog.2 to JVMLog.<MAXLOGS>. When a JVM is started, if the size of the JVMLog.1 file exceeds the maximum configurable size (1M by default), the JVMLog.1 file is copied to JVMLog.2 and so on for any older JVM Logs, and a new JVMLog.1 file will be created.

    When using the STAFJVMLogViewer, you can specify the machine where the STAF JVM log resides (e.g. where the Java service is registered) and you can specify/select the name of the STAF service whose JVM Log you want to display. This Java class submits requests to STAF, so STAF has to be running. This Java class can be run as an application via the command line or can be run via another Java program.

    Note that the STAX Monitor Java application uses the STAFJVMLogViewer class to display the JVM log for the STAX service and for other services.

    For more information on how to use the STAFJVMLogViewer class, see section "3.6.2 Class STAFJVMLogViewer" in the STAF Java User's Guide.


    9.3 STAF Log Formatter Class

    9.3.1 Description

    The STAFLogFormatter class allows you to format a STAX log (which is a binary file that has been created by the STAF Log service) as html or text.

    This Java class can be run as an application via the command line or can be run via another Java program. When run as an application, it submits the specified Log query request to query a STAF log on any machine currently running STAF and then formats the output as either html or text. Or, when run via a Java program that has already submitted a LOG QUERY request, you can use the STAFLogFormatter class to format the log query result as either html or text. You can specify various options including whether you want the formatted output written to a file.

    For more detailed information on using the STAFLogFormatter class, see section "3.6.3 Class STAFLogFormatter" in the STAF Java User's Guide.


    9.4 Format Log Utility

    9.4.1 Description

    The FmtLog utility will read a STAF log file and format and write the data to an output file in a readable format. A STAF log file is a binary log file that has been created by the STAF Log service.

    9.4.2 FORMAT

    Format data from a log file to an output file in a readable (non-compressed) format. Note that this utility does not interact with STAF (i.e. STAF does not have to be running on the machine).

    Syntax

    FmtLog FORMAT LOGFILE <Logfile> NEWFILE <Newfile> [LEVELBITSTRING]  [FIELDSEP <Char>]
    

    LOGFILE contains the name of the log you want to read. This must be the complete path and filename.

    NEWFILE contains the name of the output file where you want to write the results. This must be the complete path and filename.

    LEVELBITSTRING displays the selected records with the level displayed as the 32 byte binary bit string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error. See 8.9.11, "Logging Levels Reference" for a complete list of logging levels.

    FIELDSEP is the character that separates each record field, the default is "|".

    Directory Structure

    If the log directory was defined as C:\STAF\data\STAF\service\log (the default log directory name on Windows) then the following is an example of how the log directory structure could look:
    C:\STAF\data\STAF\service\log\                                        <-Global Top
    C:\STAF\data\STAF\service\log\GLOBAL\                                 <--Global Dir
      STRESSTST.LOG                                                       <---Global Log
      SUITE100.LOG                                                        <---Global Log
    C:\STAF\data\STAF\service\log\MACHINE\                                <-Machine Top
    C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\            <--clieot1 Top
    C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\GLOBAL\     <---client1 Global Top
      TESTLOG1.LOG                                                        <----client1 Global Logs
    C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\     <--client1 Handle Top
    C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\100\ <---Handle 100 Top
      TESTLOG2.LOG                                                        <---Handle 100 Log
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\                       <--AUTOMATE Top
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\GLOBAL\                <---AUTOMATE Global Top
      AUTOGLOB.LOG                                                        <----AUTOMATE Global Log
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\                <---AUTOMATE Handle Top
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\42\             <----Handle 42 Top
      HANDLOG1.log                                                        <-----Handle 42 Log
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\43\             <----Handle 43 Top
      HANDLOG2.log                                                        <-----Handle 43 Log
      HANDLOG3.log                                                        <-----Handle 43 Log
    C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\44\             <----Handle 44 Top
      HANDLOG4.log                                                        <-----Handle 44 Log
    C:\STAF\data\STAF\service\log\MACHINE\automate\HANDLE\45\             <----Handle 45 Top
      HANDLOG5.log                                                        <-----Handle 45 Log
    

    Result

    A line will be written to the specified file for each record in the specified logfile in the following format (assuming the default field separator, '|', is used):
    Date-Time|Machine|Handle|Handle Name|User|Endpoint|Level|Message
    

    Example

    C:\>FmtLog FORMAT LOGFILE C:/STAF/data/STAF/service/LOG/MACHINE/client1/GLOBAL/STAX_Job_4_User.log NEWFILE C:/myLog.txt
    Formatted 10 record(s) to C:/myLog.txt
    

    The contents of C:/myLog.txt could look like the following:

    20041029-15:42:03|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|TestMachines=['client1.company.com']
    20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|JobHandle=78
    20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAXMachineNickname=client1
    20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAXMachine=client1.company.com
    20041029-15:42:08|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|Test machine: client1.company.com  OS type: Win2000  STAFRoot: C:\STAF
    20041029-15:42:08|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing started on machine client1.company.com
    20041029-15:44:28|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing completed on machine client1.company.com
    20041029-15:44:28|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing completed in 146 seconds
    20041104-18:27:07|client1.company.com|50|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT
    20041105-11:22:51|client1.company.com|89|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT
    


    Appendix A. API Return Codes

    Note: In some shell environments, return codes above 255 may be returned modulo 256. This can, in particular, cause service return codes (which range from 4000 upward) to be mistaken for (possibly) non-existent common STAF return codes. For example, if a service returned the return code 4010, this might appear to be the return code 170 (4010 modulo 256) in a shell environment.

    Table 108. STAF API Return Codes
    Error Code Meaning Comment
    0 No error
    1 Invalid API This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors.
    2 Unknown Service You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service.
    3 Invalid Handle You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF.
    4 Handle already exists This indicates that you are trying to register a process with one name when that process has already been registered with a different name. If you register the same process multiple times, ensure that you use the same name on each registration call.

    Note: If you receive this error code when trying to perform an operation other than registering a service, report it to the authors.

    5 Handle does not exist You are trying to perform an operation on a handle that does not exist. For example, you may be trying to stop a process, but you are specifying the wrong handle.
    6 Unknown Error An unknown error has occurred. This error is usually an indication of an internal STAF error. If this error occurs, report it the authors.
    7 Invalid Request String You have submitted an improperly formatted request to a service. See the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.

    Note: Additional information regarding the exact syntax error may be provided in the result passed back from the submit call.

    8 Invalid Service Result This indicates an internal error with the service to which a request was submitted. If this error occurs, report it to the authors and the service provider.
    9 Rexx Error This indicates an internal error in an external Rexx service. If this error occurs, report it to the authors and the service provider.

    Note: The actual Rexx error code will be returned in the result passed back from the submit call.

    10 Base OS Error This indicates that a base operating system error was encountered.

    Note: The actual base operating system error code, and possibly additional information about the error, will be returned in the result passed back from the submit call.

    11 Process Already Complete You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification.
    12 Process Not Complete You are trying to free process information for a process that is still executing.
    13 Variable Does Not Exist You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call.
    14 UnResolvable String You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions.
    15 Invalid Resolve String The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces.
    16 No Path To Endpoint This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. target machine). This error usually indicates one or more of the following:

    1. STAFProc is not running on the target machine.
    2. The requested endpoint is not valid.
    3. The network interface or port for the requested endpoint is not supported.
    4. A firewall is blocking communication via the port for the requested endpoint.
    5. A secure network interface is being used to communicate to a machine that doesn't have a secure network interface configured with the same certificate.
    Alternatively, you may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg file.
    17 File Open Error This indicates that there was an error opening the requested file. Some possible explanations are that the file/path does not exist, contains invalid characters, or is locked.

    Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call.

    18 File Read Error This indicates that there was an error while trying to read data from a file.

    Note: Additional information regarding which file could not be read from may be provided in the result passed back from the submit call.

    19 File Write Error This indicates that there was an error while trying to write data to a file.

    Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call.

    20 File Delete Error This indicates that there was an error while trying to delete a file or directory.

    Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call.

    21 STAF Not Running This indicates that STAFProc is not running on the local machine with the same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix machine).

    Notes:

    1. If the STAF_INSTANCE_NAME environment variable is not set, it defaults to "STAF".
    2. On Unix, if the STAF_TEMP_DIR environment variable is not set, it defaults to "/tmp". This environment variable is not used on Windows.
    3. This error can also occur when submitting a request using the local IPC interface on a Unix machine if the socket file that the local interface uses has been inadvertently deleted.
    4. To get more information on this error, set special environment variable STAF_DEBUG_21=1 and resubmit your local STAF service request.
    22 Communication Error This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request. This can also indicate that the requested endpoint is not valid (e.g. it has an invalid network interface and port combination such as a non-secure tcp interface with the port for a secure ssl interface).
    23 Trustee Does Not Exist You have requested to delete a trustee, and the trustee does not exist. Verify that you have specified the correct trustee.
    24 Invalid Trust Level You have attempted to set a machine or default trust level to an invalid level. The valid trust levels are from zero to five.
    25 Insufficient Trust Level You have submitted a request for which you do not have the required trust level to perform the request.

    Note: Additional information regarding the required trust level may be provided in the result passed back from the submit call.

    26 STAF Registration Error This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured.
    27 Service Configuration Error This indicates an error with the configuration of an external service. One possible explanation is that the LIBRARY you specified when configuring the service does not exist. Or, if you specified the EXECUTE option, verify that the executable exists and has the execute permission. Or, if you specified the PARMS option, verify that all of the service configuration are valid. Consult the appropriate documentation for the service to verify whether you have configured the service properly, or contact the service provider.

    Note: Additional information regarding why the service configuration failed may be provided in the result passed back from the submit call.

    28 Queue Full This indicates that you are trying to queue a message to a handle's queue, but the queue is full. The maximum queue size can be increased by using the MAXQUEUESIZE statement in the STAF Configuration File.
    29 No Queue Element This indicates that you tried to GET or PEEK a particular element in a queue, but no such element exists, or the queue is empty.
    30 Notifiee Does Not Exist This indicates that you are trying to remove a message notification for a machine/process/priority combination which does not exist in the notification list.
    31 Invalid API Level This indicates that a process has tried to call an invalid level of an internal STAF API. If this error occurs, report it to the authors.
    32 Service Not Unregisterable This indicates that you are trying to unregister a service that is not unregisterable. Note that internal services are not unregisterable.
    33 Service Not Available This indicates that the service you requested is not currently able to accept requests. The service may be in the process of initializing or terminating.
    34 Semaphore Does Not Exist This indicates that you are trying to release, query, or delete a semaphore that does not exist.
    35 Not Semaphore Owner This indicates that you are trying to release a semaphore for which your process is not the current owner.
    36 Semaphore Has Pending Requests This indicates that you are trying to delete either a mutex semaphore that is currently owned or an event semaphore that has waiting processes.
    37 Timeout This indicates that you submitted a request with a timeout value and the request did not complete within the requested time.
    38 Java Error This indicates an error performing a Java native method call. A description of the error will be returned in the result passed back from the submit call.
    39 Converter Error This indicates an error performing a codepage conversion. The most likely cause of this error is that STAF was not properly installed. However, it is possible that you are currently using a codepage that was not present or specified during STAF installation.
    40 Move Error This indicates that there was an error while trying to move a file or directory.

    Note: Additional information regarding the error may be provided in the result passed back from the submit call.

    41 Invalid Object This indicates that an invalid object was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
    42 Invalid Parm This indicates that an invalid parameter was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
    43 Request Number Not Found This indicates that the specified Request Number was not found. The specified Request Number may be invalid, or the request's information may no longer be available from the Service Service (for example, if the SERVICE FREE command had previously been issued for the request number).
    44 Invalid Asynch Option This indicates that an invalid Asynchronous submit option was specified.
    45 Request Not Complete This indicates that the specified request is not complete. This error code would be returned, for example, if you requested the result of a request which has not yet completed.
    46 Process Authentication Denied This indicates that the userid/password you specified could not be authenticated. The userid/password may not be valid or authentication may be disabled.
    47 Invalid Value This indicates that an invalid value was specified. This is closely related to the Invalid Request String return code, but indicates that a specific value in the request is invalid. For example, you may not have specified a number where a number was expected.

    Note: Additional information regarding which value is invalid may be provided in the result passed back from the submit call.

    48 Does Not Exist This indicates that the item you specified does not exist.

    Note: Additional information regarding which item could not be found may be provided in the result passed back from the submit call.

    49 Already Exists This indicates that the item you specified already exists.

    Note: Additional information regarding which item already exists may be provided in the result passed back from the submit call.

    50 Directory Not Empty This indicates that you have tried to delete a directory, but that directory is not empty.

    Note: Additional information specifying the directory which could not be deleted may be provided in the result passed back from the submit call.

    51 Directory Copy Error This indicates that you have tried to copy a directory, but errors occurred during the copy.

    Note: Additional information specifying the entries which could not be copied may be provided in the result passed back from the submit call.

    52 Diagnostics Not Enabled This indicates that you tried to record diagnostics data, but diagnostics have not been enabled. You must enable diagnostics before you can record diagnostics data.
    53 Handle Authentication Failed This indicates that the user, credentials, and/or authenticator you specified could not be authenticated. The user/credentials may not be valid or the authenticator may not be registered.

    Note: Additional information specifying why authentication was denied may be provided in the result passed back from the submit call.

    54 Handle Already Authenticated This indicates that the handle is already authenticated. The handle must be unauthenticated in order to be authenticated.
    55 Invalid STAF Version This indicates that the version of STAF (or the version of a STAF service) is lower than the minimum required version.
    56 Request cancelled This indicates that the request has been cancelled.

    Note: Additional information specifying why the request was cancelled may be provided in the result passed back from the submit call.

    57 Create Thread Error This indicates that a problem occurred creating a new thread. One possible explanation is that there's not enough memory available to create a new thread.

    Note: Additional information specifying why creating a new thread failed may be provided in the result passed back from the submit call.

    58 Maximum Size Exceeded This indicates that the size of a file exceeded the maximum size allowed (e.g. per the MAXRETURNFILESIZE operational parameter or per the MAXRETURNFILESIZE setting for the STAX service). A maximum file size is usually set to prevent the creation of result strings that require more memory than is available which can cause errors or crashes.

    Note: Additional information specifying why this error occurred may be provided in the result passed back from the submit call.

    59 Maximum Handles Exceeded This indicates that a new handle could not be created/registered because the maximum number of active handles allowed by STAF has been exceeded. You need to delete one or more handles that are no longer being used. The Handle service's LIST HANDLES SUMMARY request provides information on the maximum number of active STAF handles and this may be helpful in better understanding why this error occurred.
    60 Not Pending Requester You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.
    4000+ Service Defined Error codes of 4000 and beyond are service specific error codes. Either see the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.


    Appendix B. Service Command Reference


    Table 109. STAF Service Command Reference
    Command Syntax
    CONFIG Provides a way to save the current STAF configuration to a file, reflecting any changes made since STAFProc was started

    SAVE [FILE <Name>] [VARS <Current | Startup>]
     
    HELP
    
    DELAY Delay (or sleep) for a specified amount of time.

    DELAY <Number>[s|m|h|d|w]
     
    HELP
    
    DIAG Allows diagnostics to be recorded, listed, enabled, disabled, and reset.

    RECORD TRIGGER <Trigger> SOURCE <Source>
     
    LIST   < [TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES]
             [SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE] > |
           SETTINGS
     
    RESET  FORCE
     
    ENABLE
     
    DISABLE
     
    HELP
    
    ECHO Echo a return string from other STAF clients.

    ECHO <Message>
     
    HELP
    
    FS Allows you to manipulate files and directories and get information about file system entries.

    COPY   FILE <Name> [TOFILE <Name> | TODIRECTORY <Name>]  [TOMACHINE <Machine>]
           [TEXT [FORMAT <Format>]]  [FAILIFEXISTS | FAILIFNEW]
     
    COPY   DIRECTORY <Name> [TODIRECTORY <Name>]  [TOMACHINE <Machine>]
           [NAME <Pattern>]  [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
           [TEXTEXT <Pattern>... [FORMAT <Format>]]
           [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]]
           [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
     
    MOVE   FILE <Name> <TOFILE <Name> | TODIRECTORY <Name>>
     
    MOVE   DIRECTORY <Name> TODIRECTORY <Name>
     
    GET    FILE <Name> [[TEXT | BINARY] [FORMAT <Format>]]
     
    GET    ENTRY <Name> <TYPE | SIZE | MODTIME | LINKTARGET |
                         CHECKSUM [<Algorithm>]>
    QUERY  ENTRY <Name>
     
    CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
     
    LIST   DIRECTORY <Name> [RECURSE] [LONG [DETAILS] | SUMMARY] [TYPE <Types>]
           [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
           [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]     
     
    LIST   COPYREQUESTS [LONG] [INBOUND] [OUTBOUND]
           [FILE [[BINARY] [TEXT]]] [DIRECTORY]
     
    LIST   SETTINGS
     
    DELETE ENTRY <Name> CONFIRM [RECURSE] [IGNOREERRORS]
           [ CHILDREN [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>]
                      [CASESENSITIVE | CASEINSENSITIVE] ]
                      
    SET    STRICTFSCOPYTRUST <Enabled | Disabled>
     
    HELP
    
    HANDLE Allows you to query information on various process handles and to manage static handles.

    CREATE HANDLE NAME <Handle Name>
     
    DELETE HANDLE <Number>
     
    QUERY HANDLE <Handle>
     
    LIST [ HANDLES <[NAME <Handle Name>] [LONG] [PENDING] [REGISTERED]
                    [INPROCESS] [STATIC]> | [SUMMARY] ]
     
    LIST NOTIFICATIONS [HANDLE <Handle> | MACHINE <Machine>] [LONG]
     
    AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials>
                 [AUTHENTICATOR <Authenticator Name>]
     
    UNAUTHENTICATE
     
    HELP
    
    HELP List and query STAF return codes. Allows services to register their own return codes.

    REGISTER   SERVICE <Name> ERROR <Number> INFO <String> DESCRIPTION <String>
     
    UNREGISTER SERVICE <Name> ERROR <Number>
     
    [SERVICE <Name>] ERROR <Number>
     
    LIST SERVICES | [SERVICE <Name>] ERRORS
     
    HELP
    
    LIFECYCLE Allows STAF service requests to be submitted automatically when STAFProc starts up or shuts down. Also, allows managing registration of the STAF service requests to be submitted.

    REGISTER   PHASE <Startup | Shutdown>
               MACHINE <Machine> SERVICE <Service> REQUEST <Request>
               [ONCE] [PRIORITY <Priority>] [DESCRIPTION <Description>]
     
    UNREGISTER ID <Registration ID>
     
    UPDATE     ID <Registration ID> [PRIORITY <Priority>] [ONCE <True | False>]
               [MACHINE <Machine>] [SERVICE <Service>] [REQUEST <Request>]
               [PHASE <Startup | Shutdown>] [DESCRIPTION <Description>]
     
    LIST       [PHASE <Startup | Shutdown>] [LONG]
     
    QUERY      ID <Registration ID>
     
    TRIGGER    <ID <Registration ID> | PHASE <Startup | Shutdown>> CONFIRM
     
    ENABLE     ID <Registration ID>
     
    DISABLE    ID <Registration ID>
     
    HELP
    
    LOG Allows for robust data-logging and log file querying and manipulation.

    LOG    <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level>
           MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    QUERY  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
           [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
           [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [STARTSWITH <String>]... [CSSTARTSWITH <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
           [FROMRECORD <Num>] [TORECORD <Num>]
           [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG]
           [LEVELBITSTRING]
     
    LIST   GLOBAL | MACHINES | MACHINE <Machine> [HANDLE <Handle> | HANDLES] |
           SETTINGS
     
    DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]>
            LOGNAME <Logname> CONFIRM
     
    PURGE  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
           CONFIRM | CONFIRMALL
           [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
           [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [STARTSWITH <String>]... [CSSTARTSWITH <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
           [FROMRECORD <Num>] [TORECORD <Num>]
           [FIRST <Num> | LAST <Num>]
     
    SET    [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
           [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
           [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    VERSION
     
    HELP
    
    MISC Provides miscellaneous services such as VERSION, WHOAMI, and WHOAREYOU information, allows for listing and querying enabled interfaces, allows you to set operational parameters for STAF and show their settings, and allows you to list and purge the endpoint cache used by automatic interface cycling.

    VERSION
     
    WHOAMI
     
    WHOAREYOU
     
    LIST  INTERFACES | SETTINGS | ENDPOINTCACHE
     
    QUERY INTERFACE <Name>
     
    SET   [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>[s|m|h|d|w]]
          [MAXQUEUESIZE <Number>] [HANDLEGCINTERVAL <Number>[s|m|h|d]]
          [INTERFACECYCLING <Enabled | Disabled>]
          [DEFAULTINTERFACE <Name>]  [DEFAULTAUTHENTICATOR <Name>]
          [RESULTCOMPATIBILITYMODE <Verbose | None>]
          
    PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM>
     
    HELP
    
    MONITOR Allows test cases the ability to log and query status messages.

    LOG    MESSAGE <Message> [NAME <Name>] [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    QUERY  MACHINE <Machine> < HANDLE <Handle> | NAME <Name> >
     
    LIST   <MACHINES | MACHINE <Machine> [NAMES] | SETTINGS>
     
    DELETE [BEFORE <Timestamp>] CONFIRM
     
    SET    [RESOLVEMESSAGE | NORESOLVEMESSAGE]
           [OLDRETURNCODES | NEWRETURNCODES] [MAXRECORDSIZE <Size>]
           [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
     
    VERSION
     
    HELP
    
    PING Allows you to ping other STAF clients.

    PING [MACHINE <Machine>]
     
    HELP
    
    PROCESS Allows you to start, stop, and manage processes.

    START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>]
          [VAR <Variable>=<Value>]... [ENV <Variable>=<Value>]... [USEPROCESSVARS]
          [WORKLOAD <Name>] [TITLE <Title>] [WAIT [<Number>[s|m|h|d|w]] | ASYNC]
          [STOPUSING <Method>] [STATICHANDLENAME <Name>]
          [NEWCONSOLE | SAMECONSOLE] [FOCUS <Background | Foreground | Minimized>]
          [USERNAME <User name> [PASSWORD <Password>]]
          [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH]
          [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
          [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
          [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
          [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>]
          [MACHINE <Machine>] [PRIORITY <Priority>] [KEY <Key>]]
     
    STOP  <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
     
    KILL  PID <Pid> CONFIRM [USING <Method>]
     
    LIST  [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG]
    LIST  SETTINGS
     
    QUERY HANDLE <Handle>>
     
    FREE  <ALL | WORKLOAD <Name> | HANDLE <Handle>>
     
    NOTIFY REGISTER   ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
                      [MACHINE <Machine>] [PRIORITY <Priority>]
     
    NOTIFY UNREGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
                      [MACHINE <Machine>] [PRIORITY <Priority>]
                      
    NOTIFY LIST       ONENDOFHANDLE <Handle>
     
    SET   [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>]
          [DEFAULTFOCUS <Background | Foreground | Minimized>]
          [PROCESSAUTHMODE <Auth Mode>]
          [DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>]
          [DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>]
          [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
     
    HELP
    
    QUEUE Allows you to manipulate and manage queues.

    QUEUE  MESSAGE <Message>
           [HANDLE <Handle>] | [NAME <Name>] [PRIORITY <Priority>] [TYPE <Type>]
     
    GET    [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
           [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
           [CONTAINS <String>]... [ICONTAINS <String>]...
           [FIRST <Number> | ALL]
           [WAIT [<Number>[s|m|h|d|w]]]
     
    PEEK   [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
           [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
           [CONTAINS <String>]... [ICONTAINS <String>]...
           [FIRST <Number> | ALL]
           [WAIT [<Number>[s|m|h|d|w]]]
     
    DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
           [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
           [CONTAINS <String>]... [ICONTAINS <String>]...
     
    LIST   [HANDLE <Handle>]
     
    HELP
    
    RESPOOL Allows you to manage exclusive access to entries within resource pools.

    CREATE  POOL <PoolName> DESCRIPTION <Pooltext>
     
    DELETE  POOL <PoolName> CONFIRM [FORCE]
     
    QUERY   POOL <PoolName>
     
    REQUEST POOL <PoolName>
            [FIRST | RANDOM | ENTRY <Value> [RELEASE]] [PRIORITY <Number>]
            [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
     
    RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
     
    CANCEL  POOL <PoolName>
            [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]]
            [ENTRY <Entry>] [PRIORITY <Number>] [FIRST | LAST]
     
    ADD     POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
     
    REMOVE  POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
     
    LIST    [POOLS | SETTINGS]
     
    VERSION
     
    HELP
    
    SEM Allows you to manipulate and manage mutex and event semaphores.

    REQUEST MUTEX <Name> [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
    RELEASE MUTEX <Name> [FORCE]
    CANCEL  MUTEX <Name>
            [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]]
            [FIRST | LAST]
     
    POST    EVENT <Name>
    RESET   EVENT <Name>
    PULSE   EVENT <Name>
    WAIT    EVENT <Name> [TIMEOUT <Number>[s|m|h|d|w]]
     
    DELETE  MUTEX <Name> | EVENT <Name>
    QUERY   MUTEX <Name> | EVENT <Name>
    LIST    MUTEX | EVENT
    HELP
    
    SERVICE Allows you to manage STAF services and requests.

    LIST    [ SERVICES | SERVICELOADERS | AUTHENTICATORS |
              REQUESTS <[PENDING] [COMPLETE] [LONG]> | [SUMMARY] ]
     
    QUERY   SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> |
            AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number>
     
    ADD     SERVICE <Service Name> LIBRARY <Library Name>
            [EXECUTE <Executable>] [OPTION <Name=[=Value]>]...
            [PARMS <Parameters>]
     
    REMOVE  SERVICE <Service Name>
     
    FREE    REQUEST <Request Number> [FORCE]
     
    HELP
    
    SHUTDOWN Allows you to manage the STAFProc daemon process.

    SHUTDOWN
     
    NOTIFY REGISTER   [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
                      [PRIORITY <Priority>]
     
    NOTIFY UNREGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
                      [PRIORITY <Priority>]
     
    NOTIFY LIST
     
    HELP
    
    TRACE Allows you to turn tracing on and off at the service and tracepoint level.

    ENABLE ALL  [ TRACEPOINTS | SERVICES ]
    ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
    ENABLE SERVICE <Service> [SERVICE <Service>]...
     
    DISABLE ALL  [ TRACEPOINTS | SERVICES ]
    DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
    DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
    DISABLE SERVICE <Service> [SERVICE <Service>]...
     
    SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] >
    SET DEFAULTSERVICESTATE < Enabled | Disabled >
     
    LIST [SETTINGS]
     
    PURGE
     
    HELP
    
    TRUST Allows you to manipulate and manage trust levels (security).

    SET < MACHINE <Machine> | USER <User> | DEFAULT > LEVEL <Level>
     
    GET MACHINE <Machine> [USER <User>]
     
    DELETE MACHINE <Machine> | USER <User>
     
    LIST
     
    HELP
    
    VAR Allows you to manipulate and manage system, shared and process specific variable pools.

    SET [SYSTEM | SHARED | HANDLE <Handle>] [FAILIFEXISTS]
        VAR <Name=Value> [VAR <Name=Value>]...
     
    GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name>
     
    DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]...
     
    LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]]
     
    RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]]
            STRING <String> [STRING <String>]...
     
    HELP
    
    ZIP Allows for unzipping, listing, and adding/deleting entries in Zip archives which are PKZip, WinZip and Jar compatible.

    UNZIP  ZIPFILE <Name> TODIRECTORY <Name>
           [FILE <Name>]... [DIRECTORY <Name>]...
           [RESTOREPERMISSION] [REPLACE]
           
    ADD    ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
           [RELATIVETO <Directory>]
     
    DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
     
    LIST   ZIPFILE <Name>
     
    VERSION
     
    HELP
    


    Appendix C. Samples Descriptions


    Table 110. STAF Sample Code
    Name Description Comments
    D.1.1, "Java Sample 1" Java Ping Sample This sample uses the STAF Ping command to ping a STAF client and measure the throughput.
    D.2.1, "Rexx Sample 1" Rexx Synchronous Process Sample This sample loads the STAF Functions, registers to STAF, queries a system variable from STAF, initiates a synchronous process which is a chkdsk of the boot drive, then unregisters.
    D.2.2, "Rexx Sample 2" Rexx Asynchronous Process Sample This sample loads REXX and STAF Functions, registers to STAF, sets a system variable, initiates an asynchronous PMSEEK process, list variables, queries process status, stops PMSEEK, queries process status again, frees the process, queries the system variable previously set, then unregisters.
    D.2.3, "Rexx Sample 3" Rexx Monitor Sample This sample loads STAF Functions, registers to STAF, writes a monitor message and then queries it, this is done 10 times, then it unregisters. The size of the monitor messages written is based on a random number generated.
    D.2.4, "Rexx Sample 4" Rexx Log Sample This sample loads STAF Functions, registers to STAF, writes and queries 10 log messages to a global log called LOGTEST, then unregisters. The size of the log messages written is based on a random number generated.
    D.2.5, "Rexx Sample 5" Rexx Ping Sample This sample uses the STAF Ping command to ping a STAF client and measure the throughput.
    D.3.1, "C Sample 1" C Log Sample This sample logs a message via the STAF LOG service.
    D.4.1, "C++ Sample 1" C++ Log Sample This sample logs a message via the STAF LOG service.


    Appendix D. Code Samples and Snipets


    D.1 Java

    D.1.1 Java Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
    /*****************************************************************************/
     
    //===========================================================================
    // JPing - A multi-threaded STAF PING test
    //===========================================================================
    // Accepts: Where to PING
    //          Optionally, the number of threads to use (default = 5)
    //          Optionally, the number of loops per thread (default = 10000)
    //          Optionally, the display modulus (default = 250)
    //
    // Returns: 0 , on success
    //          >0, if an error is encountered
    //===========================================================================
    // Date        Who           Comment
    // ----------  ------------  ------------------------------------------
    // 04/25/1998  C. Rankin     File Created
    //===========================================================================
     
    import com.ibm.staf.*;
    import java.util.Date;
    import java.util.Calendar;
    import java.text.DateFormat;
     
    public class JPing implements Runnable
    {
        // Constructor
     
        public JPing(int numLoops, int displayModulus, int myThreadNum)
        {
            loopCount = numLoops;
            modulus = displayModulus;
            threadNum = myThreadNum;
            errors = 0;
        }
     
        // This is the main command line entry point
     
        public static void main(String [] argv)
        {
            // Verify the command line arguments
     
            if ((argv.length < 1) || (argv.length > 4))
            {
                System.out.println();
                System.out.println("Usage: java JPing <Where> [# Threads] " +
                                   "[# Loops per thread] [Display Modulus]");
                System.out.println();
                System.out.println("Defaults:");
                System.out.println();
                System.out.println("  # Threads          = 5");
                System.out.println("  # Loops per thread = 10000");
                System.out.println("  Display Modulus    = 250");
                System.out.println();
                System.out.println("Examples:");
                System.out.println();
                System.out.println("java JPing local");
                System.out.println("java JPing SomeServer 3 1000 100");
                System.exit(1);
            }
     
            // Register with STAF
     
            try
            {
                handle = new STAFHandle("Java_Ping_Test");
            }
            catch (STAFException e)
            {
                System.out.println("Error registering with STAF, RC: " + e.rc);
                System.exit(1);
            }
     
            // Initialize variables
     
            timeFormatter = DateFormat.getTimeInstance(DateFormat.MEDIUM);
     
            where = argv[0];
            int numThreads = 5;
            int numLoops = 10000;
            int displayModulus = 250;
     
            if (argv.length > 1) numThreads = Integer.parseInt(argv[1]);
            if (argv.length > 2) numLoops = Integer.parseInt(argv[2]);
            if (argv.length > 3) displayModulus = Integer.parseInt(argv[3]);
     
            JPing [] pingers = new JPing[numThreads];
            Thread [] threads = new Thread[numThreads];
     
            System.out.println("(0)" + timeFormatter.format(new Date()) +
                               " - Started");
            long startSecs = (new Date()).getTime();
     
            // Start the threads
     
            for(int i = 0; i < numThreads; ++i)
            {
                pingers[i] = new JPing(numLoops, displayModulus, i + 1);
                threads[i] = new Thread(pingers[i]);
                threads[i].start();
            }
     
            // Wait for all the threads to finish
     
            for(int i = 0; i < numThreads; ++i)
            {
                try
                {
                    threads[i].join();
                }
                catch (Exception e)
                {
                    System.out.println("Exception: " + e);
                    System.out.println(e.getMessage());
                }
            }
     
            // Output final pings/sec
     
            long stopSecs = (new Date()).getTime();
            System.out.println("(0)" + timeFormatter.format(new Date()) +
                               " - Ended");
     
            System.out.println("Average: " + ((numLoops * numThreads * 1000) /
                               (stopSecs - startSecs)) + " pings/sec");
     
            // Unregister with STAF
     
            try
            {
                handle.unRegister();
            }
            catch (STAFException e)
            {
                System.out.println("Error unregistering with STAF, RC: " + e.rc);
                System.exit(1);
            }
        }
     
        // This is the method called when each thread starts
     
        public void run()
        {
            for(int i = 1; i <= loopCount; ++i)
            {
                STAFResult result = handle.submit2(where, "PING", "PING");
     
                // If we get a non-zero return code, or a response of something
                // other than "PONG", display an error
     
                if (result.rc != 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Loop #" + i + ", Error #" +
                                       ++errors + ", RC: " + result.rc);
                }
                else if (result.result.compareTo("PONG") != 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Loop #" + i + ", Error #" +
                                       ++errors + ", RESULT = " + result.result);
                }
     
                // If we are at our display modulus display a status message
     
                if ((i % modulus) == 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Ended Loop #" + i + ", Errors = " +
                                       errors);
                }
            }
        }
     
        private static STAFHandle handle;
        private static String where;
        private static DateFormat timeFormatter;
     
        private int loopCount;
        private int modulus;
        private int threadNum;
        private int errors;
    }
    

    D.2 Rexx

    D.2.1 Rexx Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample1.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample loads the STAF Functions, registers to STAF, queries  */
    /* a global variable from STAF, inititates a synchronous process     */
    /* which is a chkdsk of the boot drive, then unregisters.            */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 02/01/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register to STAF */
    call STAFRegister "STAF_REXX_Sample1"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/BootDrive}")
    if STAFRC = 0 then
      bootdrive = STAFResult
    else
    do
      say "Unable to determine boot drive!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    /* Build the process start request with a work load name of STAFSample */
    request = "START WAIT COMMAND chkdsk.com WORKLOAD STAFSample"
     
    /* Pass the boot drive parameter to chkdsk */
    parms = "PARMS" bootdrive
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/Sep/File}")
    if STAFRC = 0 then
      filesep = STAFResult
    else
    do
      say "Unable to determine file seperator!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    /* Set the working directory */
    workdir = "WORKDIR" bootdrive||filesep
     
    /* Submit the request to STAF */
    say "Attempting to CHKDSK bootdrive" bootdrive
    STAFRC = STAFSubmit("local", "process", request parms workdir)
    say "Submit Return Code="STAFRC ", Result="STAFResult
     
    /* Unregister */
    call STAFUnRegister
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister
      EXIT 1
    

    D.2.2 Rexx Sample 2

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample2.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample loads REXX and STAF Functions, registers to STAF,     */
    /* inititates an asynchronous PMSEEK process, queries, stops,        */
    /* queries again then frees the process, then unregisters.           */
    /*                                                                   */
    /* Note that this example explictly uses STAFHandle in all calls     */
    /* and additional error checking is needed.                          */
    /*                                                                   */
    /* Returns: 0,  on success                                           */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 02/02/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load system functions */
    call RxFuncAdd "SysLoadFuncs", "REXXUTIL", "SysLoadFuncs"
    call SysLoadFuncs
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register Sample to STAF */
    call STAFRegister "STAF_REXX_Sample2", "STAFHandle"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Set a global variable for start timestamp */
    request = " GLOBAL SET Start="||DATE('s')||'-'||TIME()
    STAFRC = STAFSubmit(STAFHandle, "local", "VAR", request)
     
    /* Build the process start request with a work load name of STAFSample2 */
    request = "START COMMAND pmseek.exe WORKLOAD STAFSample2"
     
    /* Submit the request to STAF */
    STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
    if STAFRC = 0 then
    do
      PROCHandle = STAFResult
      STAFRC = STAFSubmit(STAFHandle, "local", "VAR", "LIST")
      say STAFResult
      say "Press <Enter> to continue"
      pull response
     
      request = "query handle" PROCHandle
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
      say STAFResult
      say "Press <Enter> to stop PMSEEK"
      pull response
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "STOP HANDLE" PROCHandle)
      call SysSleep 1
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
      say STAFResult
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "FREE HANDLE" PROCHandle)
     
      STAFRC = STAFSubmit(STAFHandle, "local", "var", "resolve {Start}")
      if (STAFRC = 0) & (STAFResult \= '') then Start = STAFResult
     
      say "Start =" Start
      say "End   =" DATE('s')||'-'||TIME()
    end
     
    /* Unregister */
    call STAFUnRegister STAFHandle
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister STAFHandle
      EXIT 1
    

    D.2.3 Rexx Sample 3

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Eclipse Public License (EPL) V1.0.    */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample3.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample writes a monitor message and then queries it, this    */
    /* is done 10 times.  A size of the string written is based on a     */
    /* random number generated.                                          */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------