Software Testing Automation Framework (STAF) User's Guide
Version 3.4.26
31 Dec 2016
Appendix B. Service Command Reference
Appendix C. Samples Descriptions
Appendix D. Code Samples and Snipets
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.
STAF is supported on the following operating systems
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.
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:
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).
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.
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:
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.
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.
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.
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.
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:
Caution: You should NOT change the ACP value to the OEMCP value.
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}
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:
The STAF Installation Guide (http://staf.sourceforge.net/current/STAFInstall.pdf) has detailed information on how to install STAF.
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).
You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.
# This is a comment line
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).
MACHINENICKNAME <Nickname>
<Nickname> is the nickname you wish to use for your machine. It is case sensitive.
MACHINENICKNAME testmachine1 MACHINENICKNAME JohnDoe
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).
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.
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
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.
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
External services are registered with the SERVICE configuration statement.
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>.
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
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.
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
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.
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
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).
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"
Service loaders are registered with the SERVICELOADER configuration statement.
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.
# 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
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
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:
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:
# 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.
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.
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
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.
# 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.
Authenticator services are registered with the AUTHENTICATOR configuration statement. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter.
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.
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"
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.
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).
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.
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.
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:
Note that automatic interface cycling only has an effect if there are multiple interfaces configured in the STAF configuration file on the machine that is submitting a STAF request. Also, note that the MISC service provides a LIST ENDPOINTCACHE request to show the cached endpoints and a PURGE ENDPOINTCACHE request to purge one or more cached endpoints.
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:
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:
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:
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"
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.
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.
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
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.
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).
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:
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:
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.
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 *://*
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).
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.
NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager
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.
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.
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"
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
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"
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.
On Unix: export STAF_THREAD_STACK_SIZE=128 On Windows: set STAF_THREAD_STACK_SIZE=128
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. |
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).
Note: <STAF_INSTANCE_NAME> will be replaced with the actual STAF Instance Name which defaults to "STAF" unless it is overridden by setting the STAF_INSTANCE_NAME environment variable.
Note: <DATADIR> will be replaced with the resolved value of the {STAF/DataDir}variable, with the slashes replaced with dashes. For example: DataDir_-usr-local-staf-data-STAF.tmp
This is a socket file used by the Unix Local IPC connection provider. If this socket file is inadvertently deleted, local service requests will fail with RC 21 (STAF Not Running).
This is a socket file used by a STAF JVM that was created when registering a STAF Java service. There will be one socket file for each STAF JVM.
Note: <JVMName> will be replaced by the actual STAF JVM name.
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.
STAFProc is what starts STAF running on a machine.
STAFProc [STAF Configuration File]
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.
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 ports used by STAF TCP connection providers must be unique, otherwise, you'll get a "Error starting tcp interface" error when starting STAFProc. If one instance of STAF is running using a ssl interface with port 6550 and a tcp interface port 6500, then to start another instance of STAF that also uses a ssl and tcp interface, you must specify a different ports in its STAF configuration file. For example:
interface tcp library STAFTCP option SECURE=Yes option PORT=6551 interface tcp library STAFTCP option SECURE=No option PORT=6501
Each STAFProc instance must use a different data directory. However, since the default setting for the data directory is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}, the data directory names will be different if they are not overridden using the DATADIR operational setting (and as long as the STAF_INSTANCE_NAME environment variable is set to a unique value). If the data directory for a STAFProc instance is not unique, you'll get a "Data directory is already in use" error when starting STAFProc
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 STAFProcIn 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.
On Windows Vista and Windows Server 2008 and later (including Windows 7, Windows 8, Windows 8.1, Windows Server 2012, Windows Server 2012 R2, Windows 10, 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").
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.
STAF [-verbose] <Endpoint> <Service> <Request>
[<Interface>://]<System Identifier>[@<Port>]where:
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"
set STAF_INSTANCE_NAME=MySTAF staf local ping ping
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.
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.
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.
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.
The STAFRegister call is used by a C program to register with STAF.
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.
char *myName = "MyProgram"; STAFHandle_t myHandle = 0; STAFRC_t rc = STAFRegister(myName, &myHandle);
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.
The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.
STAFRC_t STAFUnRegister(STAFHandle handle)
handle is the handle that you received on the call to STAFRegister.
/* myHandle was previously set by STAFRegister */ STAFRC_t rc = STAFUnRegister(myHandle);
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
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.
/* 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);
The STAFSubmit2 API is identical to the STAFSubmit API except that it has an additional parameter, syncOption, which allows submission of asynchronous requests.
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.
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.
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.
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.
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.
/* myHandle was previously set by STAF */ /* result was previously set by STAFSubmit */ STAFRC_t rc = 0; if (result != 0) rc = STAFFree(myHandle, result);
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);
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);
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);
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.
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.
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.
// 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;
};
#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;
}
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();
};
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;
}
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.
typedef STAFRefPtr<STAFObjectIterator> STAFObjectIteratorPtr;
class STAFObjectIterator
{
public:
bool hasNext();
STAFObjectPtr next();
~STAFObjectIterator();
};
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;
}
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.
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();
};
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:
The STAFRegister call is used by a Rexx program to register with STAF.
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.
call STAFRegister "MyHandleName", "MyHandle" say "My handle is:" MyHandle
or
call STAFRegister "MyHandleName" say "My handle is:" STAFHandle
The STAFUnRegister call is used by a Rexx program to unregister with STAF, which frees up any internal STAF resources used by the handle.
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.
call STAFUnRegister MyHandle
or
call STAFUnRegister
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
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.
/* 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
The STAFMon wrapper library provides a wrapper around the MONITOR service. The following functions are provided:
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.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFMonErrorText
do i = 1 to numLoops
call STAFMonitor "Beginning of loop #"i
...
...
end
The STAFLog wrapper library provides a wrapper around the LOG service. The following functions are provided:
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.
/* 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"
The STAFPool wrapper library provides a wrapper around the RESPOOL service. The following functions are provided:
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.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFPoolErrorText call STAFPoolRequest "Pool1", "Entry1" say "The entry obtained was:" Entry1 ... call STAFPoolRelease Entry1
The STAFUtil library provides some utilitiy functions for use by Rexx programs. The following functions are provided:
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.
/* 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
For information on STAF's V3 support for the Java language, see the STAF Java User's Guide.
For information on STAF's V3 support for the Perl language, see the STAF Perl User's Guide.
For information on STAF's V3 support for the Python language, see the STAF Python User's Guide.
For information on STAF's V3 support for the Tcl language, see the STAF Tcl User's Guide.
Services are what provide all the capabilities of STAF.
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.
Values for options may be specified in one of three ways.
MESSAGE Hello
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
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:
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).
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.
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.
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>
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.
The following table contains a brief description of the services provided
with STAF. The chapter that follows provides a detailed explanation of each
service.
| 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 |
The foundation services that STAF provides are described in this chapter. For each service the following sections are listed.
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.
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:
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:
This command requires trust level 3.
However, if the DEFAULTAUTHPASSWORD has been set for the PROCESS service, this command requires trust level 5.
All return codes from SAVE are documented in Appendix A, "API Return Codes".
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.
Syntax:
SAVE FILE /tmp/mySTAF.cfg
Results:
Syntax:
SAVE FILE /tmp/mySTAF.cfg VARS Startup
Results:
Syntax:
SAVE
Results:
# ---------------------------------------------------------------------
# STAF Configuration File
# ---------------------------------------------------------------------
# ---------------------------------------------------------------------
# Tracing
# ---------------------------------------------------------------------
TRACE ENABLE ALL SERVICES
TRACE ENABLE TRACEPOINTS "ERROR WARNING DEPRECATED DEBUG"
# ---------------------------------------------------------------------
# Variables
# ---------------------------------------------------------------------
SET SYSTEM VAR STAFDemo/JavaAppClassPath=C:\STAF\lib\JSTAF.zip;C:\STAF\samples\demo\STAFDemo.jar;
SET SYSTEM VAR STAFDemo/JavaAppCommand=javaw.exe
# ---------------------------------------------------------------------
# Operational Parameters
# ---------------------------------------------------------------------
SET MAXQUEUESIZE 1000
SET MAXRETURNFILESIZE 5120
# ---------------------------------------------------------------------
# Interfaces (Connection Providers)
# ---------------------------------------------------------------------
INTERFACE ssl LIBRARY STAFTCP OPTION ConnectTimeout=5000 OPTION Port=6550 \
OPTION Protocol=IPv4 OPTION Secure=Yes
INTERFACE tcp LIBRARY STAFTCP OPTION ConnectTimeout=5000 OPTION Port=6500 \
OPTION Protocol=IPv4 OPTION Secure=No
# ---------------------------------------------------------------------
# Trust Levels
# ---------------------------------------------------------------------
TRUST LEVEL 5 MACHINE *://client1.mycompany.com
TRUST LEVEL 5 MACHINE *://client2.mycompany.com
TRUST LEVEL 5 MACHINE *://server1.mycompany.com
TRUST LEVEL 5 MACHINE local://local
# ---------------------------------------------------------------------
# Service Loader Service Registrations
# ---------------------------------------------------------------------
SERVICELOADER LIBRARY STAFDSLS
# ---------------------------------------------------------------------
# Service Registrations
# ---------------------------------------------------------------------
SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar \
OPTION JVMName=STAX OPTION J2=-Xmx512m \
PARMS "CLEARLOGS Enabled FILECACHEALGORITHM LFU"
SERVICE EVENT LIBRARY JSTAF EXECUTE C:\STAF\services\STAFEvent.jar \
OPTION JVMName=STAX
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.
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:
This command requires trust level 2.
All return codes from DELAY are documented in Appendix A, "API Return Codes".
DELAY 100
DELAY 5s
Note that this is equivalent to:
DELAY 5000
DELAY 1m
Note that this is equivalent to:
DELAY 60000
DELAY 2h
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.
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.
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.
This command requires trust level 3.
Note: This command is only valid if submitted to the local machine, not to remote machines.
All return codes from RECORD are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RECORD command.
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.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the LIST request based on the options specified:
The result buffer for a LIST request (without specifying options
TRIGGER, SOURCE, TRIGGERS, SOURCES, or SETTINGS) will contain a
marshalled <Map:STAF/Service/Diag/AllDiagInfo>
representing the diagnostics information for all of the unique
trigger/source combinations.
The maps are defined as follows:
Table 6. Definition of map class STAF/Service/Diag/AllDiagInfo
| Description: This map class represents the diagnostics information for all of the unique trigger/source combinations. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfTriggers | Number of Triggers | <String> |
|
| numberOfSources | Number of Sources | <String> |
|
| comboList | Trigger/Source Combinations | <List> of <Map:STAF/Service/Diag/ComboCount> |
|
Notes:
| |||
Table 7. Definition of map class STAF/Service/Diag/ComboCount
| Description: This map class represents a unique trigger/source combination and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| trigger | Trigger | <String> |
|
| source | Source | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times each trigger/source combination has been recorded. | |||
The result buffer for a LIST TRIGGERS request will contain a
marshalled <Map:STAF/Service/Diag/TriggersInfo>
representing the diagnostics information for all of the unique triggers
that have been recorded.
The maps are defined as follows:
Table 8. Definition of map class STAF/Service/Diag/TriggersInfo
| Description: This map class represents the diagnostics information for all of the unique triggers that have been recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfTriggers | Number of Triggers | <String> |
|
| triggerList | Triggers | <List> of <Map:STAF/Service/Diag/TriggerCount> |
|
Notes:
| |||
Table 9. Definition of map class STAF/Service/Diag/TriggerCount
| Description: This map class represents a trigger and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| trigger | Trigger | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times a trigger has been recorded. | |||
The result buffer for a LIST SOURCES request will contain a
marshalled <Map:STAF/Service/Diag/SourcesInfo>
representing the diagnostics information for all of the unique sources
that have been recorded.
The maps are defined as follows:
Table 10. Definition of map class STAF/Service/Diag/SourcesInfo
| Description: This map class represents the diagnostics information for all of the unique sources that have been recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfSources | Number of Sources | <String> |
|
| sourceList | Sources | <List> of <Map:STAF/Service/Diag/SourceCount> |
|
Notes:
| |||
Table 11. Definition of map class STAF/Service/Diag/SourceCount
| Description: This map class represents a source and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| source | Source | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times a source has been recorded. | |||
The result buffer for a "LIST TRIGGER <Trigger>" request
will contain a marshalled
<Map:STAF/Service/Diag/TriggerInfo>
representing the diagnostics information for the unique sources
that have been recorded for the specified trigger.
The maps are defined as follows:
Table 12. Definition of map class STAF/Service/Diag/TriggerInfo
| Description: This map class represents the diagnostics information for the specified trigger. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| trigger | Trigger | <String> |
|
| numberOfSources | Number of Sources | <String> |
|
| sourceList | Sources | <List> of <Map:STAF/Service/Diag/SourceCount> |
|
Notes:
| |||
The result buffer for a "LIST SOURCE <Source>" request
will contain a marshalled
<Map:STAF/Service/Diag/SourceInfo>
representing the diagnostics information for all of the unique triggers
that have been recorded for the specified source.
The maps are defined as follows:
Table 13. Definition of map class STAF/Service/Diag/SourceInfo
| Description: This map class represents the diagnostics information for the specified source. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| source | Source | <String> |
|
| numberOfTriggers | Number of Triggers | <String> |
|
| triggerList | Triggers | <List> of <Map:STAF/Service/Diag/TriggerCount> |
|
Notes:
| |||
The result buffer for a "LIST SETTINGS" request
will contain a marshalled
<Map:STAF/Service/Diag/Settings>
representing the current operational settings for the DIAG service.
The maps are defined as follows:
Table 14. Definition of map class STAF/Service/Diag/Settings
| Description: This map class represents the current operational settings for the DIAG service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| diagnostics | Diagnostics | <String> | 'Enabled' | 'Disabled'. |
| lastResetTimestamp | Last Reset / First Enabled | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| lastDisabledTimestamp | Last Disabled | <String> | <YYYYMMDD-HH:MM:SS> |
Notes:
| |||
Syntax: LIST
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:20:05
Elapsed Time : 00:05:01
Number of Triggers : 3
Number of Sources : 2
Trigger/Source Combinations: [
{
Trigger: MYSERVICE QUERY
Source : MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Trigger: MYSERVICE QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 4
}
{
Trigger: MYSERVICE LIST
Source : myApp2;machine1.austin.ibm.com;97
Count : 1
}
]
}
Syntax: LIST SORTBYTRIGGER
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:21:09
Elapsed Time : 00:06:05
Number of Triggers : 3
Number of Sources : 2
Trigger/Source Combinations: [
{
Trigger: MYSERVICE LIST
Source : myApp2;machine1.austin.ibm.com;97
Count : 1
}
{
Trigger: MYSERVICE QUERY
Source : MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Trigger: MYSERVICE QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 4
}
]
}
Syntax: LIST TRIGGERS SORTBYTRIGGER
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Timestamp : 20040926-12:28:20
Elapsed Time : 00:13:16
Number of Triggers: 3
Triggers : [
{
Trigger: MYSERVICE LIST
Count : 1
}
{
Trigger: MYSERVICE QUERY
Count : 17
}
{
Trigger: SAMPLE1 QUERY
Count : 4
}
]
}
Syntax: LIST SOURCES
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:32:53
Elapsed Time : 00:17:49
Number of Sources: 2
Sources : [
{
Source: MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Source: MyApp2;machine1.austin.ibm.com;97
Count : 12
}
]
}
Syntax: LIST TRIGGER "MYSERVICE QUERY" SORTBYSOURCE
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:36:18
Elapsed Time : 00:21:14
Trigger : MYSERVICE QUERY
Number of Sources: 2
Sources : [
{
Source: MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Source: MyApp2;machine1.austin.ibm.com;97
Count : 7
}
]
}
Syntax: LIST SOURCE "MyApp2;machine1.austin.ibm.com;97"
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:40:08
Elapsed Time : 00:25:04
Source : MyApp2;machine1.austin.ibm.com;97
Number of Triggers: 3
Triggers : [
{
Trigger: MYSERVICE QUERY
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Count : 4
}
{
Trigger: MYSERVICE LIST
Count : 1
}
]
}
Syntax: LIST SETTINGS
Results: If the request is issued from the command line, the result, in default format, could look like:
Diagnostics : Enabled Last Reset / First Enabled: 20040926-12:15:04 Last Disabled : 20040926-12:14:53
RESET allows you to clear all data from the diagnostics map.
RESET FORCE
FORCE is a confirmation that you want to clear all data.
This command requires trust level 4.
All return codes from RESET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RESET command.
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.
ENABLE
This command requires trust level 4.
All return codes from ENABLE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a ENABLE command.
DISABLE allows you to disable recording diagnostics.
DISABLE
This command requires trust level 4.
All return codes from DISABLE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a DISABLE command.
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.
ECHO <Message>
Note: ECHO does not follow the request parsing rules described earlier. Any text after the ECHO command will be returned verbatim.
This command requires trust level 2.
All return codes from ECHO are documented in Appendix A, "API Return Codes".
The result buffer will contain <Message> on a successful return from an ECHO command.
Goal: Have STAFProc return the string Hello World to you.
ECHO Hello World
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:
COPY FILE allows you to copy one file between machines, or to another location on the same machine.
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.
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.
All return codes from COPY FILE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a COPY FILE command.
In the following examples, assume the command is being submitted locally from machine TestSrv1.
Syntax: COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1
Syntax: Note that both of these COPY FILE examples are equivalent.
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT FORMAT Native
Syntax: COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " "
In the following examples, assume the command is being submitted to machine Client1 from machine TestSrv1.
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TODIRECTORY h:\Logs TOMACHINE LogSrv
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local
Syntax: COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT
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.
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.
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.
All return codes from COPY DIRECTORY are documented in Appendix A, "API Return Codes".
Table 15. Definition of map class STAF/Service/FS/ErrorInfo
| Description: This map class represents error information for an entry in a directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| rc | RC | <String> |
|
| osRC | OS RC | <String> | <None> |
|
Notes:
| |||
For example, if a copy directory request is submitted from the command line, and two errors occurred during the copy, the result, in table format, could look like:
Name RC OS RC ------------------- -- ------ c:\tmp\project.htm 17 <None> c:\tmp\project5.xml 10 32
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
The expected result is that the following entries exist on machine Client1:
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
The expected result is that the following entries were created on machine Client1:
c:\testcase c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2
Syntax: Note that both of these COPY DIRECTORY examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
NAME web TEXTEXT txt TEXTEXT xml
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
NAME web TEXTEXT txt TEXTEXT xml FORMAT Native
The expected result is that the following entries were created on machine Client1. Note that error.txt was not copied since its name is not 'web'.
/testcase /testcase/web.exe /testcase/web.txt /testcase/web.xml
Syntax: Note that both of these COPY DIRECTORY examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
EXT txt TEXTEXT "*" RECURSE
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
EXT txt TEXTEXT txt FORMAT Native RECURSE
The expected result is that the following entries were created on machine Client1.
/testcase /testcase/error.txt /testcase/subdir /testcase/subdir/subdir_2 /testcase/subdir/subdir_2/readme.txt
In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.
MOVE FILE allows you to rename a file or move files from one directory to another directory on a machine.
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.
This command requires trust level 4
All return codes from MOVE FILE are documented in Appendix A, "API Return Codes".
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.
Syntax: MOVE FILE C:\testcase\test1.exe TOFILE C:\testcase\test2.exe
Syntax: MOVE FILE C:\testcase\test1.exe TODIRECTORY C:\testcase\TestDir
Syntax: MOVE FILE C:\testcase\test*.txt TODIRECTORY D:\Saved_Tests
Syntax: MOVE FILE {STAF/Config/BootDrive}\startup.cmd TODIRECTORY E:\
Syntax: MOVE FILE /tmp/testcase/test1.sh TOFILE /opt/MyTests/test1.sh
MOVE DIRECTORY allows you to rename a directory on a machine.
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.
This command requires trust level 4
All return codes from MOVE DIRECTORY are documented in Appendix A, "API Return Codes".
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.
Syntax: MOVE DIRECTORY C:\testcase TODIRECTORY C:\MyTestcases
Syntax: MOVE DIRECTORY C:\testcase\Test1 TODIRECTORY "D:\My Testcases"
If directory "D:\My Testcases" exists, the directory will be renamed to "D:\My Testcases\Test1" (assuming a directory named Test1 does not already exist in "D:\My Testcases"). If directory "C:\My Testcases" does not exist, the directory will be renamed to "D:\My Testcases".
Syntax: MOVE DIRECTORY {STAF/Config/BootDrive}/mydir TODIRECTORY E:\
GET FILE retrieves the contents of a text file.
Notes:
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.
This command requires trust level 4.
All return codes from GET FILE are documented in Appendix A, "API Return Codes".
Notes:
On successful return, the result buffer will contain the contents of the specified file.
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT FORMAT Native
GET FILE c:/testcases/test1.cmp BINARY GET FILE c:/testcases1/test1.cmp BINARY FORMAT HEX
GET ENTRY retrieves an attribute of a file system entry, such as its type, size, last modification time, link target, or checksum.
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.
This command requires trust level 2.
All return codes from GET ENTRY are documented in Appendix A, "API Return Codes".
On successful return, the contents of the result buffer will depend on the attribute type requested.
Table 16. File System Entry Types Reference
| Type identifier | Description |
|---|---|
| F | File |
| D | Directory |
| P | Pipe |
| S | Socket |
| B | Block device |
| C | Character device |
| O | Other undefined type |
| ? | Unknown type |
Table 17. Definition of map class STAF/Service/FS/SizeInfo
| Description: This map class represents the 64-bit size of the file system entry. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| size | Size | <String> |
|
| upperSize | Upper 32-bit Size | <String> |
|
| lowerSize | Lower 32-bit Size | <String> |
|
| Notes: The "Size" value is the 64-bit size of the file system entry in bytes. The "Upper 32-bit Size" and "Lower 32-bit Size" values are provided for historical reasons as the "Size" value wasn't added until STAF V3.3.5. They represent the upper 32-bits of the size and the lower 32-bits of the size in bytes. Note that if the size < 4,294,967,296 bytes (aka 4G), the upper 32-bit size will be 0 and the lower 32-bit size will be the same as the size field. | |||
F
20040512-18:07:52
Size : 340488704 Upper 32-bit Size: 0 Lower 32-bit Size: 340488704
Size : 4800000000 Upper 32-bit Size: 1 Lower 32-bit Size: 505032704
/usr/local/staf/bin/STAF
3F6C5A05CA3E7422C57851CAFA223FA2
83B4F130E213D61AE6BB393FA9AEE711CC9FF91B
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.
QUERY ENTRY <Name>
ENTRY specifies the name of the file system entry to query. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
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". | |||
Name : /tests/project.tar.gz Link Target : <None> Type : F Size : 340488704 Upper 32-bit Size : 0 Lower 32-bit Size : 340488704 Modified Date-Time: 20080512-18:07:52
Name : C:/tests/myproject.zip Link Target : <None> Type : F Size : 4800000000 Upper 32-bit Size : 1 Lower 32-bit Size : 505032704 Modified Date-Time: 20090712-08:30:01
Name : /usr/local/staf/bin/staf Link Target : /usr/local/staf/bin/STAF Type : F Size : 91098 Upper 32-bit Size : 0 Lower 32-bit Size : 91098 Modified Date-Time: 20090708-21:43:11
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).
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.
This command requires trust level 2.
All return codes from LIST DIRECTORY are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the contents of the specified directory as follows:
Table 19. Definition of map class STAF/Service/FS/ListLongInfo
| Description: This map class represents information about an entry in a specified directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| type | Type | <String> |
|
| size | Size | <String> |
|
| lastModifiedTimestamp | Modified Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| name | Name | <String> |
|
| linkTarget | Link Target
(Link) | <String> | <None> |
|
Notes:
| |||
Table 20. Definition of map class STAF/Service/FS/ListDetailsInfo
| Description: This map class represents detailed information about an entry in a specified directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| linkTarget | Link Target
(Link) | <String> | <None> |
|
| type | Type | <String> |
|
| size | Size | <String> | |
| upperSize | U-Size | <String> |
|
| lowerSize | L-Size | <String> |
|
| lastModifiedTimestamp | Modified Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
Notes:
| |||
Table 21. Definition of map class STAF/Service/FS/ListSummaryInfo
| Description: This map class represents summary information about the matching entries in a specified directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| size | Size | <String> |
|
| numFiles | Files | <String> |
|
| numDirectories | Directories | <String> |
|
Notes:
| |||
win2003.exe 2-ltp-logfile test1 project.tar ACME_NEW2.xml project.htm AutoFVT.bsh
Type Size Modified Date-Time Name Link Target ---- ----- ------------------ ------------- ------------------ F 324M 20080512-18:07:52 win2003.exe <None> F 323 20080706-16:13:10 2-ltp-logfile <None> D 0 20080728-11:21:44 test1 <None> F 1210K 20080517-11:57:10 project.tar <None> F 258K 20080412-11:49:06 ACME_NEW2.xml <None> F 12505 20070506-19:14:40 project.htm <None> F 44 20080928-16:24:40 AutoFVT.bsh /tests/AutoFVT.bsh
Name Link Target Type Size U-Size L-Size Modified Date-Time
-------------- ----------- ---- --------- ------ --------- ------------------
test1 <None> D 0 0 0 20080728-11:21:44
AutoFVT.bsh /tests/Auto F 44 0 44 20080928-16:24:40
FVT.bsh
2-ltp-logfile <None> F 323 0 323 20080706-16:13:10
project.htm <None> F 12505 0 12505 20070506-19:14:40
ACME_NEW2.xml <None> F 264691 0 264691 20080412-11:49:06
project.tar <None> F 1239040 0 1239040 20080517-11:57:10
win2003.exe <None> F 340488704 0 340488704 20080512-18:07:52
Type Size Modified Date-Time Name Link Target ---- ----- ------------------ ------------- ------------------ F 323 20080706-16:13:10 2-ltp-logfile <None> F 258K 20080412-11:49:06 ACME_NEW2.xml <None> F 44 20080928-16:24:40 AutoFVT.bsh /tests/AutoFVT.bsh F 324M 20080512-18:07:52 win2003.exe <None> F 1210K 20080517-11:57:10 project.tar <None> F 12505 20070506-19:14:40 project.htm <None>
javacore.20080420.041412.7713.txt windoc.txt mytest.txt svt-spa02dynos390.txt
backup/docs/hello.txt docs/hello.txt hello.txt
dumpData output
Name Link Type Size U-Size L-Size Modified Date-Time -------------------- ------ ---- ---- ------ ------ ------------------ icu\source\test1.ucm <None> F 871 0 871 20081028-19:18:22 test1 <None> D 0 0 0 20080707-11:47:40 test1.bak <None> F 83 0 83 20080919-11:10:22 test4\test1.txt <None> F 32 0 34 20090331-13:03:04
Name : C:\tests Size : 239152838 Files : 1976 Directories: 182
Name : C:\tests\stax Size : 4250936 Files : 888 Directories: 0
LIST COPYREQUESTS displays the File System copy requests currently in progress.
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.
This command requires trust level 2.
All return codes from LIST COPYREQUESTS are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a list of the copy requests currently in progress as follows:
Table 22. Definition of map class STAF/Service/FS/CopyRequest
| Description: This map class represents a copy request in progress. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | Name | <String> |
|
| type | Type | <String> | 'D' | 'F' |
Notes:
| |||
The maps used in representing detailed information about copy requests
are defined as follows:
Table 23. Definition of map class STAF/Service/FS/CopyFile
| Description: This map class represents detailed information about a file being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | File Name | <String> |
|
| type | Type | <String> | 'F' |
| mode | Mode | <String> | 'Binary' | 'Text' |
| state | Transfer State | <Map:STAF/Service/FS/FileCopyState> |
|
Notes:
| |||
Table 24. Definition of map class STAF/Service/FS/FileCopyState
| Description: This map class represents detailed information about the state of a file being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fileSize | File Size | <String> | <None> |
|
| bytesCopied | Bytes Copied | <String> |
|
Notes:
| |||
Table 25. Definition of map class STAF/Service/FS/CopyDirectory
| Description: This map class represents detailed information about a directory being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | File Name | <String> |
|
| type | Type | <String> | 'D' |
| state | Transfer State | <Map:STAF/Service/FS/DirectoryCopyState> |
|
| Notes: | |||
Table 26. Definition of map class STAF/Service/FS/DirectoryCopyState
| Description: This map class represents detailed information about the state of the directory being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| mode | Mode | <String> | 'Binary' | 'Text' |
| fileSize | File Size | <String> | <None> |
|
| bytesCopied | Bytes Copied | <String> |
|
Notes:
| |||
Start Date-Time I/O Machine Name Type
----------------- --- ---------------------- ------------------------- ----
20050725-18:31:32 Out tcp://client2.company. c:/temp/TestA D
com
20050725-18:31:38 Out tcp://client1.company. c:/tests/Instructions.txt F
com@6500
20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F
20050725-18:31:41 Out tcp://client3.company. c:/tests/TestB/TestB.zip F
com
20050725-18:32:05 In client2.company.com c:/tests/TestC D
[
{
Start Date-Time: 20050725-18:31:32
In/Out : Out
Machine : tcp://client2.company.com
Directory Name : c:/temp/TestA
Type : D
Transfer State : {
Name : c:/temp/TestA/TestA.zip
Mode : Binary
File Size : 9873006
Bytes Copied: 1288000
}
}
{
Start Date-Time: 20050725-18:31:38
In/Out : Out
Machine : tcp://client1.company.com@6500
File Name : c:/tests/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : 26019
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:38
In/Out : In
Machine : client1.company.com
File Name : c:/temp/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : <None>
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
{
Start Date-Time: 20050725-18:32:05
In/Out : In
Machine : client2.company.com
Directory Name : c:/temp/TestC
Type : D
Transfer State : {
Name : c:/temp/TestC/TestC.txt
Mode : Text
File Size : <None>
Bytes Copied: 8000
}
}
]
Start Date-Time In/Out Machine Name Type ----------------- ------ ------------------- ------------------------ ---- 20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F
[
{
Start Date-Time: 20050725-18:31:38
In/Out : Out
Machine : tcp://client1.company.com@6500
File Name : c:/tests/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : 26019
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
]
[
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
]
LIST SETTINGS shows the operational settings for the FS service.
LIST SETTINGS
SETTINGS specifies that you want to list the current operational settings for the FS service.
This command requires trust level 2.
All return codes from LIST SETTINGS are documented in Appendix A, "API Return Codes".
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' |
Strict FS Copy Trust: Disabled
CREATE creates a directory.
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.
This command requires trust level 4.
All return codes from CREATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
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.
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.
This command requires trust level 4. If you specify RECURSE, you must have trust level 5.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
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.
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET STRICTFSCOPYTRUST Enabled
The HANDLE service is one of the internal STAF services. It provides the following commands.
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.
CREATE HANDLE NAME <Handle Name>
NAME specifies the registered name of the handle.
This command is only valid if submitted to the local machine, not to remote machines.
All return codes from CREATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the new handle number.
DELETE deletes a static handle.
DELETE HANDLE <Number>
HANDLE specifies the handle number to delete.
This command requires trust level 5.
Note: This command is only valid if submitted to the local machine, not to remote machines.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
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.
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.
This command requires trust level 1.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a list of the handles as follows:
Table 28. Definition of map class STAF/Service/Handle/HandleInfo
| Description: This map class represents status of a handle. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| name | Handle Name
(Name) | <String> | <None> |
|
| state | State | <String> |
|
| lastUsedTimestamp | Last Used Date-Time
(Last Used) | <String> | <YYYYMMDD-HH:MM:SS> |
Table 29. Definition of map class STAF/Service/Handle/HandleInfoLong
| Description: This map class represents detailed information about the status of a handle. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| name | Handle Name
(Name) | <String> | <None> |
|
| state | State | <String> |
|
| lastUsedTimestamp | Last Used Date-Time
(Last Used) | <String> | <YYYYMMDD-HH:MM:SS> |
| pid | PID | <String> |
|
| Notes: 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. | |||
Table 30. Definition of map class STAF/Service/Handle/HandleSummary
| Description: This map class represents summary information for handles. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| activeHandles | Active Handles | <String> |
|
| totalHandles | Total Handles | <String> |
|
| resetCount | Reset Count | <String> |
|
| handleNumberRange | Handle Number Range | <String> | <Minimum - Maximum> |
| maxActiveHandles | Maximum Active Handles | <String> |
|
Notes:
| |||
Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20051205-12:41:42 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 4 STAF/Service/STAX Registered 20051205-12:41:51 5 STAF/Service/LOG InProcess 20051205-12:41:53 6 STAF/SERVICE/Event Registered 20051205-12:41:51 14 MyTest Registered 20051205-13:08:53 16 STAF/Client Registered 20051205-13:08:40 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time PID ------ ------------------------------- ---------- ------------------- ---- 1 STAF_Process InProcess 20051205-12:41:42 1636 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 2360 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 1636 4 STAF/Service/STAX Registered 20051205-12:41:51 2844 5 STAF/Service/LOG InProcess 20051205-12:41:53 1636 6 STAF/SERVICE/Event Registered 20051205-12:41:51 2844 14 MyTest Registered 20051205-13:08:53 2892 16 STAF/Client Registered 20051205-13:16:40 2900
Handle Handle Name State Last Used Date-Time ------ ----------- ---------- ------------------- 14 MyTest Registered 20051205-13:08:53
Handle Handle Name State Last Used Date-Time ------ ----------- ------ ------------------- 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time ------ ----------- ------- ------------------- 17 <None> Pending 20051205-13:16:55 23 <None> Pending 20051205-13:18:59
Active Handles : 19 Total Handles : 129 Reset Count : 0 Handle Number Range : 1 - 2147483647 Maximum Active Handles: 2147483647
QUERY will allow you to display detailed information about a given handle number.
QUERY HANDLE <Handle>
HANDLE specifies the handle number you want information on. This option will resolve variables.
This command requires trust level 1.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
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:
| |||
Handle : 1 Handle Name : STAF_Process State : InProcess Last Used Date-Time: 20100126-15:45:40 PID : 1636 User : none://anonymous Instance UUID : 7D625F3CB40100000929369C75636194
AUTHENTICATE authenticates the handle submitting the request. An authenticated handle has the specified user identifier and authenticator associated with it.
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.
This command is only valid if submitted to the local machine, not to remote machines.
All return codes from AUTHENTICATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
UNAUTHENTICATE un-authenticates the handle submitting the request. An unauthenticated handle has user 'none://anonymous' associated with it.
UNAUTHENTICATE
This command requires trust level 5.
Note: This command is only valid if submitted to the local machine, not to remote machines.
All return codes from UNAUTHENTICATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
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.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
The result buffer for a "LIST ERRORS" or
"LIST ERRORS SERVICE <Service Name>" request will contain a
marshalled <List> of <Map:STAF/Service/Help/ErrorInfo>
representing the errors that can be generated by STAF internal services or
for a specific external service. The map is defined as follows:
Table 32. Definition of map class STAF/Service/Help/ErrorInfo
| Description: This map class represents information about an error. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| returnCode | Return Code | <String> |
|
| description | Description | <String> |
|
| Notes: The value for "Description" will be a short description of the error. | |||
Syntax: LIST ERRORS
Results:
Return Code Description ----------- ------------------------------ 0 No error 1 Invalid API 2 Unknown service 3 Invalid handle 4 Handle already exists 5 Handle does not exist 6 Unknown error 7 Invalid request string 8 Invalid service result 9 REXX Error 10 Base operating system error 11 Process already complete 12 Process not complete 13 Variable does not exist 14 Unresolvable string 15 Invalid resolve string 16 No path to endpoint 17 File open error 18 File read error 19 File write error 20 File delete error 21 STAF not running 22 Communication error 23 Trusteee does not exist 24 Invalid trust level 25 Insufficient trust leevl 26 Registration error 27 Service configuration error 28 Queue full 29 No queue element 30 Notifiee does not exist 31 Invalid API level 32 Service not unregisterable 33 Service not available 34 Semaphore does not exist 35 Not sempahore owner 36 Semaphore has pending requests 37 Timeout 38 Java error 39 Converter error 40 Not used 41 Invalid object 42 Invalid parm 43 Request number not found 44 Invalid asynchronous option 45 Request not complete 46 Process authentication denied 47 Invalid value 48 Does not exist 49 Already exists 50 Directory Not Empty 51 Directory Copy Error 52 Diagnostics Not Enabled 53 Handle Authentication Denied 54 Handle Already Authenticated 55 Invalid STAF Version 4000+ Service specific errors
Syntax: LIST SERVICE Log ERRORS
Results: If the request is issued from the command line, the result, in table format, could look like:
Return Code Description ----------- ------------------------------- 4004 Invalid level 4007 Invalid file format 4008 Unable to purge all log records
Syntax: LIST SERVICES
Results: If the request is issued from the command line, the result, in default format, could look like:
EVENT LOG RESPOOL STAX
[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
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 33. Definition of map class STAF/Service/Help/ErrorDetails
| Description: This map class represents information about an error. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| description | Description | <String> |
|
| details | Details | <String> |
|
Table 34. Definition of map class STAF/Service/Help/ErrorDetails
| Description: This map class represents information about an error registered by an external service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| service | Service | <String> |
|
| description | Description | <String> |
|
| details | Details | <String> |
|
Syntax: ERROR 22
Results: If the request is issued from the command line, the result, in default format, could look like:
Description: Communication error Details : 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.
Syntax: ERROR 4007
Results: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Service : LOG
Description: Invalid file format
Details : An invalid/unknown record format was encountered while reading the log file
}
{
Service : RESPOOL
Description: Resource pool has no entries available
Details : The resource pool has no entries
}
]
Syntax: SERVICE Log ERROR 4007
Results: If the request is issued from the command line, the result, in default format, could look like:
Description: Invalid file format Details : An invalid/unknown record format was encountered while reading the log file
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.
This command requires trust level 3.
This command is only valid when issued by local services.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
REGISTER SERVICE Log ERROR 4008 INFO "Unable to purge all log records" DESCRIPTION "Your PURGE criteria selected every record in the log file. Use DELETE if you{STAF/Config/Sep/Line}really want to delete every record. Or, modify your PURGE criteria."
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
This command is only valid when issued by local services.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
UNREGISTER SERVICE Log ERROR 4008
All return codes from Help are documented in Appendix A, "API Return Codes".
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.
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.
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.
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain the registration ID.
Syntax:
REGISTER PHASE Startup MACHINE client1.company.com SERVICE Process REQUEST "START SHELL COMMAND C:/tests/TestA.exe" DESCRIPTION "Start TestA"
Syntax:
REGISTER PHASE Startup MACHINE server1 SERVICE STAX REQUEST "EXECUTE FILE /tests/TestA.xml ARGS \"{'testMach': 'client1', 'serverMach': 'server1'}\""
Syntax:
REGISTER PHASE Shutdown MACHINE local SERVICE Process REQUEST "START SHELL COMMAND C:/tests/TestB.exe" DESCRIPTION "Start TestB"
Syntax:
REGISTER PHASE Startup MACHINE server1 SERVICE QUEUE REQUEST "QUEUE NAME MyTestHandle TYPE :12:STAF Startup MESSAGE :0:" ONCE
UNREGISTER ID <Registration ID>
ID specifies the registration ID of the STAF service request to be unregistered.
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
UNREGISTER ID 2
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.
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
UPDATE ID 2 PRIORITY 25 DESCRIPTION "Run TestA"
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.
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 35. Definition of map class STAF/Service/LifeCycle/Reg
| 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 |
| once | Once | <String> | 'True' | 'False' |
The result buffer for a LIST with the LONG
option will contain a marshalled <List> of
<Map:STAF/Service/LifeCycle/RegDetails> representing the
matching registrations for the LifeCycle service.
The map is defined as follows:
Table 36. Definition of map class STAF/Service/LifeCycle/RegDetails
| Description: This map class represents detailed 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' |
Syntax: LIST
Results: If the request is issued from the command line, the result, in table format, could look like:
Phase P ID State Machine Service Request Once
------- -- -- ------- ------- ------- ------------------------------------ ----
Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals
xe e
Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals
e WAIT e
Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals
d e WAIT e
Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals
e
Shutdow 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTer True
n m.exe
Shutdow 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals
n e
Syntax: LIST PHASE Startup
Results: If the request is issued from the command line, the result, in table format, could look like:
Phase P ID State Machine Service Request Once
------- -- -- ------- ------- ------- ------------------------------------ ----
Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals
xe e
Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals
e WAIT e
Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals
d e WAIT e
Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals
e
Syntax: LIST PHASE Shutdown
Results: If the request is issued from the command line, the result, in table format, could look like:
Phase P ID State Machine Service Request Once
-------- -- -- ------- ------- ------- ----------------------------------- ----
Shutdown 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTe True
rm.exe
Shutdown 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals
e
Syntax: LIST PHASE Startup LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Phase P ID State Machine Service Request Description Once
------- -- -- ------- ------- ------- ----------------------- ----------- -----
Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/ Run TestA False
tests/TestA.exe
Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/ Run TestB False
test/TestB.exe WAIT
Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/ Run TestC False
d test/TestC.exe WAIT
Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jo Run STAX Jo False
bA.xml bA
QUERY ID <Registration ID>
ID specifies the registration ID of the STAF service request to be queried. This option will resolve variables.
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
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' |
Syntax: QUERY 5
Results: If the request is issued from the command line, the result, in default format, could look like:
Phase : Startup Priority : 50 ID : 5 State : Enabled Machine : server1 Service : STAX Request : EXECUTE FILE C:/stax/jobA.xml Description: Run STAX JobA Once : False
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.
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).
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 38. Definition of map class STAF/Service/LifeCycle/TriggerId
| Description: This map class represents information about the submitted STAF service request. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> | Private data will be masked |
| rc | RC | <String> |
|
| result | Result | <String> | <Marshalling Context>. |
|
Notes:
| |||
Table 39. Definition of map class STAF/Service/LifeCycle/TriggerIds
| Description: This map class represents information about the submitted STAF service requests. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| id | ID | <String> |
|
| machine | Machine | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> | Private data will be masked |
| rc | RC | <String> |
|
| result | Result | <String> | <Marshalling Context>. |
|
Notes:
| |||
Syntax: TRIGGER ID 5 CONFIRM
Results: If the request is issued from the command line, the result, in default format, could look like the following if the registration submitted a "EXECUTE FILE C:/stax/jobA.xml" request to the STAX service on machine server1:
Machine: server1
Service: STAX
Request: EXECUTE FILE C:/stax/jobA.xml
RC : 0
Result : 4
Syntax: TRIGGER PHASE Startup CONFIRM
Results: If the request is issued from the command line, the result, in verbose format, could look like the following:
[
{
ID : 1
Machine: local
Service: PROCESS
Request: START SHELL COMMAND C:/tests/TestA.exe
RC : 0
Result : 58
}
{
ID : 4
Machine: client1
Service: PROCESS
Request: START SHELL COMMAND C:/test/TestB.exe WAIT
RC : 0
Result : {
Return code: 0
Key : <None>
Files : [
{
Return code: 0
Data : TestB was successful
}
]
}
}
{
ID : 5
Machine: server1
Service: STAX
Request: EXECUTE FILE C:/stax/jobA.xml
RC : 0
Result : 4
}
]
Syntax: TRIGGER PHASE Shutdown CONFIRM
Results: If the request is issued from the command line, the result, in tabular format, could look like the following:
ID Machine Service Request RC Result
-- ------- ------- ---------------- -- ----------------------------------------
2 local PROCESS START SHELL COMM 0 293
AND C:/tests/Tes
tTerm.exe
6 server1 STAX EXECUTE FILE C:/ 16 STAFConnectionProviderConnect: Timed out
stax/jobTerm.xml connecting to endpoint: select() timeou
t: 22, Endpoint: tcp://server1
ENABLE ID <Registration ID>
ID specifies the registration ID which is to be enabled.
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already enabled.
Syntax:
ENABLE ID 2
DISABLE ID <Registration ID>
ID specifies the registration ID which is to be disabled.
This command requires trust level 5.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already disabled.
Syntax:
ENABLE ID 2
All return codes from the LifeCycle service are documented in Appendix A, "API Return Codes".
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:
STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=1]"
Response
--------
Date-Time Level Message
----------------- ----- -------------------------------------------------------
20071127-17:45:19 Info [ID=1] [client10.company.com, STAF/Client, 24] Register
request: register phase Startup machine local service
PROCESS request :38:START SHELL COMMAND C:/tests/TestA.
exe priority 25 description :9:Run TestA
20071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER
Startup] Submitted: STAF local PROCESS START SHELL COM
MAND C:/tests/TestA.exe
20071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER
Startup] Completed. RC=0, Result=49
20071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER
Startup] Submitted: STAF local PROCESS START SHELL COM
MAND C:/tests/TestA.exe
20071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER
Startup] Completed. RC=0, Result=22
STAF local lOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=2]"
Response
--------
Date-Time Level Message
----------------- ----- -------------------------------------------------------
20071127-17:46:18 Info [ID=2] [client10.company.com, STAF/Client, 25] Register
request: register phase Shutdown machine local service
PROCESS request :41:START SHELL COMMAND C:/tests/TestT
erm.exe priority 25
20071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER
Shutdown] Submitted: STAF local PROCESS START SHELL CO
MMAND C:/tests/TestTerm.exe
20071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER
Shutdown] Completed. RC=0, Result=51
20071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER
Shutdown] Submitted: STAF local PROCESS START SHELL CO
MMAND C:/tests/TestTerm.exe
20071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER
Shutdown] Completed. RC=0, Result=78
The LifeCycle service will log an entry when the following actions occur:
[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Register request: <request>
where:
[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Unregistered.
where:
where:
where:
where:
where:
where:
where:
where:
where:
where:
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.
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.
service log library STAFLog
service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata ResolveMessage"
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.
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.
Note: This variable is not checked unless the ENABLERESOLVEMESSAGEVAR option has been set.
Note: There are three places where message resolution can be affected. They are evaluated in the following order
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.
This command requires trust level 3.
The result buffer will contain no data on return from a LOG command.
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.
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.
This command requires trust level 2.
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".
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:
Table 40. Definition of map class STAF/Service/Log/QueryStats
| Description: This map class represents the totals for the log levels of the selected records in the log. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| fatal | Fatal | <String> |
|
| error | Error | <String> |
|
| warning | Warning | <String> |
|
| info | Info | <String> |
|
| trace | Trace | <String> |
|
| trace2 | Trace2 | <String> |
|
| trace3 | Trace3 | <String> |
|
| debug | Debug | <String> |
|
| debug2 | Debug2 | <String> |
|
| debug3 | Debug3 | <String> |
|
| start | Start | <String> |
|
| stop | Stop | <String> |
|
| pass | Pass | <String> |
|
| fail | Fail | <String> |
|
| status | Status | <String> |
|
| user1 | User1 | <String> |
|
| user2 | User2 | <String> |
|
| user3 | User3 | <String> |
|
| user4 | User4 | <String> |
|
| user5 | User5 | <String> |
|
| user6 | User6 | <String> |
|
| user7 | User7 | <String> |
|
| user8 | User8 | <String> |
|
Table 41. Definition of map class STAF/Service/Log/LogRecordLong
| Description: This map class represents detailed information for a log record. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| recordNumber | Record #
(R#) | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| machine | Machine | <String> |
|
| handle | Handle
(H#) | <String> |
|
| handleName | Handle Name
(Name) | <String> |
|
| user | User | <String> |
|
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| level | Level | <String> |
|
| message | Message | <String> |
|
Table 42. Definition of map class STAF/Service/Log/LogRecord
| Description: This map class represents a log record. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| level | Level | <String> |
|
| message | Message | <String> |
|
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.
Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
Results: If the request was issued from the command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ----- ---------------------------------- 20070210-19:37:15 Trace Step 1: processing time: 01:31:26 20070210-19:39:09 Debug Step 1: debug: files=23 threads=37 20070211-01:21:39 Trace Step 2: processing time: 03:02:41 20070211-01:21:58 Debug Step 2: debug: files=31 threads=54 20070211-01:37:25 Trace Step 1: processing time: 03:11:53 20070211-01:43:46 Debug Step 1: debug: files=43 threads=67 20070211-04:33:49 Trace Step 3: processing time: 03:10:41 20070211-04:34:07 Debug Step 3: debug: files=78 threads=98
Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "ERROR"
Results: If the request was issued from the command line, the result in table format, could look like:
Date-Time Level Message ----------------- ----- ------------------------------- 20070211-02:53:20 Error Step 3: Sharing buffer exceeded
Syntax: QUERY GLOBAL LOGNAME stresstst total
Results:
17
Syntax: QUERY GLOBAL LOGNAME stresstst FROM 20070210@19:00:00 QMACHINE automate to today@08:00:00
Results: If the request was issued from the command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ------- ---------------------------------- 20070210-19:37:15 Trace Step 1: processing time: 01:31:26 20070210-19:39:09 Debug Step 1: debug: files=23 threads=37 20070210-22:20:34 Warning Step 2: File not ready, retry=3 20070210-22:21:01 Info Step 2: File ready on retry 3 20070211-01:21:39 Trace Step 2: processing time: 03:02:41 20070211-01:21:58 Debug Step 2: debug: files=31 threads=54 20070211-02:53:20 Error Step 3: Sharing buffer exceeded 20070211-02:54:22 User1 Step 3: Error recovery started 20070211-04:32:53 User2 Step 3: Error recovery completed 20070211-04:33:49 Trace Step 3: processing time: 03:10:41 20070211-04:34:07 Debug Step 3: debug: files=78 threads=98
Syntax: QUERY LONG GLOBAL LOGNAME stresstst FROM 20070210@19:00:00 TO today@08:00:00 CONTAINS threads CONTAINS buffer
Results: If the request was issued from the command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 3 20070210-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 1: debug: files=23 threads=37 7 20070211-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 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 14 20070211-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 3: debug: files=78 threads=98
Syntax: QUERY LONG GLOBAL LOGNAME stresstst CSCONTAINS "Step 1:" CSCONTAINS "Step 2:" LEVELMASK Debug
Results: If the request was issued from the command line, the result, in verbose format, could look like:
[
{
Record # : 3
Date-Time : 20070210-19:39:09
Machine : automate.austin.ibm.com
Handle : 37
Handle Name: Test1A
User : none://anonymous
Endpoint : local://local
Level : Debug
Message : Step 1: debug: files=23 threads=37
}
{
Record # : 7
Date-Time : 20070211-01:21:58
Machine : automate.austin.ibm.com
Handle : 37
Handle Name: Test1A
User : none://anonymous
Endpoint : local://local
Level : Debug
Message : Step 2: debug: files=31 threads=54
}
{
Record # : 9
Date-Time : 20070211-01:43:46
Machine : crazy8s.austin.ibm.com
Handle : 41
Handle Name: Test2
User : none://anonymous
Endpoint : tcp://crazy8s.austin.ibm.com@6500
Level : Debug
Message : Step 1: debug: files=43 threads=67
}
]
Syntax: QUERY GLOBAL LOGNAME stresstst STATS
Results: If the request was issued from the command line, the result, in default format, could look like:
Fatal : 0 Error : 1 Warning: 1 Info : 1 Trace : 4 Trace2 : 0 Trace3 : 0 Debug : 4 Debug2 : 0 Debug3 : 0 Start : 1 Stop : 1 Pass : 1 Fail : 0 Status : 1 User1 : 1 User2 : 1 User3 : 0 User4 : 0 User5 : 0 User6 : 0 User7 : 0 User8 : 0
Syntax: QUERY GLOBAL LOGNAME stresstst FROMRECORD 5 TORECORD 10 LONG
Results: If the request was issued from the command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 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
Syntax: QUERY GLOBAL LOGNAME stresstst FROMRECORD 5 TORECORD 10 LEVELMASK Trace LONG
Results: If the request was issued from the command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 6 20070211-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 2: processing time: 03:02:41 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
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.
This command requires trust level 2.
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".
If successful, the result buffer will contain data based on the LIST command:
If option MACHINE is specified without the HANDLES option, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Log/ListLogs>, which represents the machine logs for the specified machine nickname.
If both options MACHINE and HANDLE are specified, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Log/ListLogs>, which represents the handle logs for the specified machine nickname and handle.
The map is defined as follows:
Table 43. Definition of map class STAF/Service/Log/ListLogs
| Description: This map class represents a log file. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| logName | Log Name | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| upperSize | U-Size | <String> |
|
| size | L-Size | <String> |
|
| Notes: The "U-Size" value is the upper 32-bits of the size and the "L-Size" value is the lower 32-bits of the size. The sizes are shown in bytes. | |||
Table 44. Definition of map class STAF/Service/Log/ListLocalSettings
| Description: This map class represents the settings for a Log service whose logging mode is local. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| loggingMode | Logging Mode | <String> | 'Local' |
| directory | Directory | <String> |
|
| maxRecordSize | Max Record Size | <String> |
|
| defaultMaxQueryRecords | Default Max Query Records | <String> |
|
| resolveMessage | Resolve Message | <String> | 'Enabled' | 'Disabled' |
| resolveMessageVar | Resolve Message Var | <String> | 'Enabled' | 'Disabled' |
Table 45. Definition of map class STAF/Service/Log/ListRemoteSettings
| Description: This map class represents the settings for a Log service whose logging mode is remote. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| loggingMode | Logging Mode | <String> | 'Remote' |
| remoteLogServer | Remote Log Server | <String> |
|
| remoteLogService | Remote Log Service | <String> |
|
Syntax: LIST GLOBAL
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size --------- ----------------- ------ ------ StressTST 20070210-14:17:00 0 120823 Suite100 20070211-15:45:00 0 2622
Syntax: LIST MACHINES
Results: If the request is submitted from the command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
Syntax: LIST MACHINE automate.austin.ibm.com
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ AutoGlob 20070210-10:54:00 0 1168
Syntax: LIST MACHINE automate.austin.ibm.com HANDLES
Results: If the request is submitted from the command line, the result could look like:
42 43 44 45
Syntax: LIST MACHINE automate.austin.ibm.com HANDLE 43
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ HandLog1 20070210-10:54:00 0 19043 HandLog2 20070211-18:23:00 0 45264
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Logging Mode : Local Directory : C:\STAF\data\STAF\service\log Max Record Size : 100000 Default Max Query Records: 100 Resolve Message : Disabled Resolve Message Var : Disabled
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.
This command requires trust level 4.
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".
The result buffer will contain no data on return from a DELETE command.
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.
This command requires trust level 4.
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".
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
Syntax: PURGE GLOBAL LOGNAME stresstst CONFIRM LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
Results: If the PURGE request was issued from the command line, the result could look like:
Purged Records: 8 Total Records : 17
Syntax: PURGE MACHINE {STAF/Config/MachineNickname} LOGNAME test1 CONFIRM BEFORE 20080101
Results: If the PURGE request was issued from the command line, the result could look like:
Purged Records: 2710 Total Records : 3269
Syntax: PURGE MACHINE {STAF/Config/MachineNickname} LOGNAME myTest CONFIRMALL
Results: If the PURGE request was issued from the command line, the result could look like:
Purged Records: 152 Total Records : 152
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
[RESOLVEMESSAGE | NORESOLVEMESSAGE]
See section 8.9.3, "Parameters" for a description of these options.
This command requires trust level 5.
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".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET MaxRecordSize 150000
Syntax: SET DefaultMaxQueryRecords 50
Syntax: SET ResolveMessage
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.
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. |
The MISC service is one of the internal STAF services. It provides a home for miscellaneous commands.
VERSION will display the STAF version number that is currently running.
VERSION
This command requires trust level 1.
All return codes from VERSION are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the version number.
Syntax:
VERSION
Results:
3.4.6
WHOAMI will display information about who a system thinks you are. This can be useful in debugging trust issues and other problems.
WHOAMI
This command requires trust level 1.
All return codes from WHOAMI are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax:
WHOAMI
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Request Number : 1812 Interface : tcp Logical ID : server1.austin.ibm.com Physical ID : 9.41.53.147 Endpoint : tcp://server1.austin.ibm.com@6500 Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : No Handle : 33 Handle Name : myHandle User : authSample://User1 Trust Level : 5
Syntax:
WHOAMI
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Request Number : 92 Interface : local Logical ID : local Physical ID : local Endpoint : local://local Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : Yes Handle : 29 Handle Name : STAF/Client User : none://anonymous Trust Level : 5
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.
WHOAREYOU
This command requires trust level 1.
All return codes from WHOAREYOU are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax:
WHOAREYOU
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Machine : server1.austin.ibm.com Machine Nickname : Server1 Local Request : No Current Date-Time: 20100615-14:46:30
Syntax:
WHOAREYOU
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Machine : client2.austin.ibm.com Machine Nickname : client2.austin.ibm.com Local Request : Yes Current Date-Time: 20100615-15:35:11
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.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
Table 51. 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:
| |||
Table 52. Definition of map class STAF/Service/Misc/Settings
| Description: This map class represents the operational settings for STAF. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| connectAttempts | Connection Attempts | <String> |
|
| connectRetryDelay | Connect Retry Delay | <String> |
|
| interfaceCycling | Interface Cycling | <String> | 'Enabled' | 'Disabled' |
| maxQueueSize | Maximum Queue Size | <String> |
|
| maxReturnFileSize | Maximum Return File Size | <String> |
|
| handleGCInterval | Handle GC Interval | <String> | '5000' - '86400000' |
| initialThreads | Initial Threads | <String> |
|
| threadGrowthDelta | Thread Growth Delta | <String> |
|
| dataDir | Data Directory | <String> |
|
| defaultInterface | Default Interface | <String> |
|
| defaultAuthenticator | Default Authenticator | <String> |
|
| resultCompatibilityMode | Result Compatibility Mode | <String> | 'Verbose' | 'None' |
Table 53. Definition of map class STAF/Service/Misc/EndpointCache
| Description: This map class represents an cached endpoint. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| endpoint | Endpoint | <String> |
|
| interface | Interface | <String> |
|
| createdTimestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
Notes:
| |||
Table 54. Definition of map class STAF/Service/Misc/Properties
| Description: This map class represents the install properties for STAF. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| version | version | <String> |
|
| platform | platform | <String> |
|
| architecture | architecture | <String> | '32-bit' | '64-bit' |
| installer | installer | <String> | 'IA' | 'IA_NoJVM' | 'STAFInst' |
| file | file | <String> |
|
| osname | osname | <String> |
|
| osversion | osversion | <String> | "*" indicates the build is supported on any version of the OS; a version number followed by a "+" indicates the build supports that version or later |
| osarch | osarch | <String> |
|
Syntax:
LIST INTERFACES
Results: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Interface Name: local
Library : STAFLIPC
Options : {
IPCMethod: Shared memory
IPCName : STAF
}
}
{
Interface Name: ssl
Library : STAFTCP
Options : {
ConnectTimeout : 5000
Port : 6550
Protocol : IPv4
SSL/CACertificate : C:\STAF\bin\CAList.crt
SSL/ServerCertificate: C:\STAF\bin\STAFDefault.crt
SSL/ServerKey : C:\STAF\bin\STAFDefault.key
Secure : Yes
}
}
{
Interface Name: tcp
Library : STAFTCP
Options : {
ConnectTimeout: 5000
Port : 6500
Protocol : IPv4
Secure : No
}
}
{
Interface Name: alt-tcp
Library : STAFTCP
Options : {
ConnectTimeout: 30000
Port : 6502
Protocol : IPv6
Secure : No
}
}
]
Syntax:
LIST SETTINGS
Results: If the request is issued from the command line, the result, in default format, could look like:
Connection Attempts : 2 Connect Retry Delay : 1000 Interface Cycling : Enabled Maximum Queue Size : 10000 Maximum Return File Size : 0 Handle GC Interval : 60000 Initial Threads : 10 Thread Growth Delta : 1 Data Directory : c:\STAF\data\STAF Default Interface : tcp Default Authenticator : none Result Compatibility Mode: Verbose
Syntax:
LIST ENDPOINTCACHE
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Endpoint Interface Date-Time -------------------- --------- ----------------- machine1 tcp2 20051101-16:42:41 machine1.company.com tcp2 20051102-11:11:37 machine2.company.com tcp3 20051101-15:23:59 machine3 tcp2 20051102-09:05:34
Syntax:
LIST PROPERTIES
Results: If the request is issued from the command line, the result, in default format, could look like:
version : 3.4.22 platform : win32 architecture: 32-bit installer : IA file : STAF3422-setup-win32.exe osname : Windows osversion : * osarch : x86
QUERY allows you to obtain detailed information about an enabled interface (aka connection provider).
QUERY INTERFACE <Name>
INTERFACE specifies the name of the interface you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax:
QUERY INTERFACE ssl
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Interface Name: ssl
Library : STAFTCP
Options : {
ConnectTimeout : 5000
Port : 6550
Protocol : IPv4
SSL/CACertificate : C:\STAF\bin\CAList.crt
SSL/ServerCertificate: C:\STAF\bin\STAFDefault.crt
SSL/ServerKey : C:\STAF\bin\STAFDefault.key
Secure : Yes
}
}
Syntax:
QUERY INTERFACE tcp
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Interface Name: tcp
Library : STAFTCP
Options : {
ConnectTimeout: 5000
Port : 6500
Protocol : IPv4
Secure : No
}
}
Syntax:
QUERY INTERFACE local
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Interface Name: local
Library : STAFLIPC
Options : {
IPCMethod: Shared memory
IPCName : STAF
}
}
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.
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET MAXQUEUESIZE 50
Syntax: SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2s
Syntax: SET INTERFACECYCLING Disabled
Syntax: SET DEFAULTINTERFACE tcp
Syntax: SET HANDLEGCINTERVAL 50s
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.
This command requires trust level 5.
All return codes from PURGE are documented in Appendix A, "API Return Codes".
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> |
|
Syntax: PURGE ENDPOINTCACHE ENDPOINT client1 ENDPOINT client1.company.com
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Purged Endpoints : 2 Remaining Endpoints: 8
Syntax: PURGE ENDPOINTCACHE CONFIRM
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Purged Endpoints : 8 Remaining Endpoints: 0
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.
service Monitor library STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 512"
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.
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.
This command requires trust level 3.
All return codes from LOG are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a LOG command.
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.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
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.
| |||
Syntax: QUERY MACHINE automate.austin.ibm.com HANDLE 32
Results: If the request is submitted from the command line, the result, in default format, could look like:
Date-Time: 20040911-16:00:32 Message : Testcase aborted with error "255"
Syntax: QUERY MACHINE testmachine1 HANDLE 85
Results: If the request is submitted from the command line, the result, in default format, could look like:
Date-Time: 20041022-17:58:01 Message : TestC: Step 2 of 5
Syntax: QUERY MACHINE automate.austin.ibm.com NAME ActiveXYZRequests
Results: If the request is submitted from the command line, the result, in default format, could look like:
Date-Time: 20061205-08:24:01 Message : TestW: Step 32 of 109
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
The result buffer will contain data based on the LIST command:
Table 58. Definition of map class STAF/Service/Monitor/HandleInfo
| Description: This map class represents the handle that generated the monitor message on the specified machine. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| size | Size | <String> |
|
| Notes: The "Date-Time" is the date/time at which the last monitor message was logged. The "Size" is the size of the last monitor message logged. | |||
Table 59. Definition of map class STAF/Service/Monitor/NameInfo
| Description: This map class represents the named monitors on the specified machine. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| size | Size | <String> |
|
| Notes: The "Date-Time" is the date/time at which the last monitor message was logged. The "Size" is the size of the last monitor message logged. | |||
Table 60. Definition of map class STAF/Service/Monitor/Settings
| Description: This map class represents the settings for the Monitor service. | |||
| Key Name | Display Name | Type | Value |
|---|---|---|---|
| maxRecordSize | Max Record Size | <String> |
|
| resolveMessage | Resolve Message | <String> | Enabled | Disabled |
| resolveMessageVar | Resolve Message Var | <String> | Enabled | Disabled |
Syntax: LIST MACHINES
Results: If the request is submitted from the command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
Syntax: LIST MACHINE automate.austin.ibm.com
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 34 20040910-16:29:03 30 36 20040910-16:29:13 148 37 20040910-16:29:19 97 68 20040911-16:00:32 43
Syntax: LIST MACHINE testmachine1
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 20 20041022-17:43:05 25
Syntax: LIST MACHINE automate.austin.ibm.com NAMES
Results: If the request is submitted from the command line, the result, in table format, could look like:
Name Date-Time Size ----------------- ----------------- ---- ActiveXYZRequests 20061205-13:50:06 39 test1 20061205-13:54:14 25
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Max Record Size : 512 Resolve Message : Enabled Resolve Message Var: Disabled
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.
This command requires trust level 4.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a DELETE command.
Syntax: DELETE BEFORE TODAY CONFIRM
Syntax: DELETE BEFORE 20070101 CONFIRM
Syntax: DELETE CONFIRM
Syntax: DELETE MACHINE automate.austin.ibm.com NAME ActiveXYZRequests CONFIRM
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successul SET command.
Syntax: SET RESOLVEMESSAGE
Syntax: SET MAXRECORDSIZE 512 ENABLERESOLVEMESSAGEVAR
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).
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.
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.
This command requires trust level 1.
All return codes from PING are documented in Appendix A, "API Return Codes".
The result buffer will contain PONG on a successful return from a PING command.
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.).
Syntax and Results:
C:\>STAF local PING PING Response -------- PONG
Syntax and Results:
C:\>STAF host1.company.com PING PING Response -------- PONG
If STAFProc is not running on machine host1.company.com or you cannot communicate via STAF to that machine, you would get an RC 16 (No path to endpoint) and an error message. For example:
C:\>STAF host1.company.com PING PING Error submitting request, RC: 16 Additional info --------------- STAFConnectionProviderConnect: Timed out connecting to endpoint: select() timeou t: 22, Endpoint: tcp://host1.company.com
Note that you can get more information on return code 16 (and other STAF return codes) by using the Help service. For example:
C:\>STAF local HELP ERROR 16 Response -------- Description: No path to endpoint Details : This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. machine). This error usually indicates that STAF i s not running on the target machine, or that the requested endpoint is not valid , or that the network interface or port for the requested endpoint is not suppor ted, or that a firewall is blocking communication via the port for the requested endpoint, or that a secure network interface is being used to communicate to a machine that doesn't have a secure network interface configured with the same ce rtificate. Alternatively, you may need to increase your CONNECTTIMEOUT value fo r the network interface and/or increase your CONNECTATTEMPTS value in your STAF. cfg file.
Syntax and Results:
C:\>STAF host1.company.com PING PING MACHINE host2.company.com Response -------- PONG
Syntax and Results:
C:\>STAF host1.company.com PING PING MACHINE host2.company.com@6501 Response -------- PONG
The PROCESS service is one of the internal STAF services. It provides the following commands
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.
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:
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.
This command requires trust level 5.
All return codes from START are documented in Appendix A, "API Return Codes".
The maps are defined as follows:
Table 61. Definition of map class STAF/Service/Process/CompletionInfo
| Description: This map class represents completion information for a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | Return Code | <String> |
|
| key | Key | <String> | <None> |
|
| fileList | Files | <List> of <Map:STAF/Service/Process/ReturnFileInfo> |
|
| Notes: The "Files" value will contain a list of information about the files requested to be returned, or an empty list if no files were 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. | |||
Table 62. Definition of map class STAF/Service/Process/ReturnFileInfo
| Description: This map class represents a file returned by the process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | Return Code | <String> |
|
| data | 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" WAIT request is submitted from the command line, and assume that the process completed successfully and returned 0. The result, in verbose format, could look like the following:
{
Return Code: 0
Key : <None>
Files : []
}
For example, suppose a PROCESS START COMMAND "java TestA" RETURNSTDOUT RETURNSTDERR WAIT request is submitted from the command line, and assume that the process completed successfully and returned 0, that the standard output of the process was simply "Success !!!", and that the standard error of the process was blank. The result, in verbose format, could look like the following:
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : Success !!!
}
{
Return Code: 0
Data :
}
]
}
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.
Syntax and Results:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" Response -------- 35The result buffer contains the handle number of the process that was started (which in this case is 35). This is not the return code of the process as the process was started asynchronously (no WAIT option was specified) so it doesn't wait for the process to complete.
If you invoke the same process again, you'll get a different handle number each time. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" Response -------- 37If you want the STAF command to wait for the process to complete before returning, specify the WAIT option. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT
Response
--------
{
Return Code: 0
Key : <None>
Files : []
}
The result buffer contains a map of the results from running the "java -version"
command, including the return code from the command which was 0 in this example.
A return code of 0 from a "java -version" command indicates that the
command ran successfully. Note that no files were returned, as indicated
by an empty list, [], since none of the return file options (RETURNSSTDOUT,
RETURNSTDERR, RETURNFILE) were specified.
The "java -version" command writes the Java version information to standard error (stderr). To obtain that information, plus any information written to standard output (stdout), you could use the STDERRTOSTDOUT option to redirect stderr to stdout and use the RETURNSTDOUT option to return the content of stdout. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT STDERRTOSTDOUT RETURNSTDOUT
Response
--------
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64)
Java HotSpot(TM) Client VM (build 1.5.0-b64, mixed mode, sharing)
}
]
}
The result buffer contains a map of the results from running the "java -version"
command, including a return code of 0 and a list of the files returned by the
process, which in this case contains one file (the stdout file).
For each file returned, a standard STAF return code is provided which
indicates the success or failure of retrieving the file's contents, which
in this case was 0, indicating the file's contents were successfully retrieved.
In addition, if the file's return code is 0, then the data contained in the
file is also provided. In this case, it contains the java version information.
Note that instead of specifying local as the machine on which to start this process, you could have specified the name of a remote machine that is also running STAF and which has given trust level 5 to the requesting machine.
Syntax and Results:
C:\>STAF client1 PROCESS START COMMAND myTest.exe Response -------- 60The result buffer contains the handle number of the process that was started (which in this case is 60). This is not the return code of the process as the process was started asynchronously (without the WAIT option) so the STAF request completes as soon as the process is started and doesn't wait for the process to complete.
However, if the myTest.exe file was not found in the system path on machine client1, you would get an error starting the process. For example:
C:\>STAF client1 PROCESS START COMMAND myTest.exe Error submitting request, RC: 10 Additional info --------------- Error starting the process. CreateProcess failed with OS RC 2: The system cannot find the file specified.The return code from the STAF request is 10. STAF RC 10 indicates a base operating system error was encountered (e.g. STAF local HELP ERROR 10 gives more information about STAF RC 10) and an error message that includes the actual base operating system error code, 2, is provided in the result buffer. OS error code 2 indicates that a file was not found. In this case, the myTest.exe file was not found since it's not in the system path.
If myTest.exe is located in directory C:\tests on machine client1, you can fully qualify the path to myTest.exe so that the command can be located and successfully started. For example:
C:\>STAF client1 PROCESS START COMMAND C:/tests/myTest.exe Response -------- 62Or, if you wanted myTest.exe to run in an environment where the system path included the C:/tests directory, you can use the ENV option to update the system path environment variable. Note that if you specify the SHELL option in this situation, you don't need to specify the path to the command because the updated system path will be used to find the command. For example:
C:\>STAF client1 PROCESS START SHELL COMMAND myTest.exe ENV PATH=C:/tests{STAF/Config/Sep/Path}{STAF/Env/Path}
Response
--------
64
Syntax and Results:
C:\>STAF client1 PROCESS START COMMAND "java -cp C:/tests TestA" WAIT RETURNSTDOUT RETURNSTDERR
Response
--------
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : SUCCESS. Yippee!!!
}
{
Return Code: 0
Data :
}
]
}
The result buffer contains a map of the results from running the java testcase,
including a return code of 0 and a list of the files returned. The first file
returned is stdout and it contains "SUCCESS. Yippee!!!". The second file
returned is stderr and it contains nothing.
@echo off EXIT /B 99
Syntax and Results:
C:\>STAF client2 PROCESS START SHELL COMMAND "C:/test.bat & set PROCESSRC=%ERRORLEVEL% & exit %PROCESSRC%" WAIT
Response
--------
{
Return Code: 99
Key : <None>
Files : []
}
The following examples show the goal and the syntax of the request to submit to the PROCESS service but not the results.
Syntax: START COMMAND tc1.exe TITLE "Testcase 1" WORKDIR d:/testcase ENV RUNMODE=Type1 ENV AUTO=1
Syntax: START COMMAND tc2 WORKDIR d:/webtests VAR WebServer=testsrv1.test.austin.ibm.com VAR RunMode=1 WORKLOAD "Web Tests" WAIT
Syntax: START COMMAND {WWWTestDir}/www1.exe WORKDIR {WWWTestDir} WAIT 30m
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND PRIORITY 1 MACHINE EventController NAME ProcessHandler KEY 9bt1az54fq
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase STOPUSING SIGINT
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase SAMECONSOLE
Syntax: START COMMAND tc2 WORKDIR /testcases USERNAME testuser PASSWORD !!@tupass@!!
Syntax: START COMMAND tc2 WORKDIR /testcase STDOUT /testcases/tc2/stdout.txt
Syntax: START COMMAND tc3.sh STATICHANDLENAME "Test case 3"
Syntax: START SHELL COMMAND "ps | grep test | wc >testcount.txt"
Syntax: START SHELL COMMAND "grep 'Count = ' /tests/out | awk '{print $5}'" STDOUT /tests/awk.out STDERRTOSTDOUT
Note: When using STAF V3.4.0 or later, you no longer have to use a caret (^) as an escape character for "{" if it does not denote a variable reference because the IGNOREERRRORS option is used when submitting a VAR RESOLVE request to resolve variables in option values on a PROCESS START request.
Syntax: START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT
Syntax: START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT WAIT RETURNSTDOUT RETURNFILE /tmp/tc3.results
Syntax: START COMMAND tc3.sh STDERRTOSTDOUT WAIT RETURNSTDOUT
Syntax: START SHELL "D:/Cygwin/bin/bash.exe -c %C" COMMAND "D:/tests/test1.sh machA" WORKDIR D:/tests
Syntax: START SHELL "xterm -title %T -e /bin/sh -c %X" COMMAND "/tests/test1.sh machA" TITLE "Test 1" STDOUT /tests/test1.out
Syntax: START SHELL "/bin/csh -c %C" COMMAND "/tests/test1.sh machA" WORKDIR /tests
Syntax: START SHELL 'su - %u -c %C' COMMAND 'echo $HOME' USERNAME test WAIT STDOUT /temp/test.out STDERRTOSTDOUT RETURNSTDOUT
To start a process under a different user name on a Windows system, the following requirements must be met:
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.
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:
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:
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.
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:
This command requires trust level 4.
All return codes from STOP are documented in Appendix A, "API Return Codes".
Table 63. Definition of map class STAF/Service/Process/StopInfo
| Description: This map class represents statistics for stopped processes. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| stoppedProcesses | Stopped Processes | <String> |
|
| totalProcesses | Total Processes | <String> |
|
| Notes: This map contains the number of processes actually stopped and the total number of processes. These two numbers will be different if some of the processes have already been stopped or have already completed execution on their own. | |||
Syntax: STOP HANDLE 42
Syntax: STOP HANDLE 113 USING SIGTERM
Syntax: STOP HANDLE 17 USING SIGKILL
Syntax: STOP WORKLOAD "Web Tests"
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 5 Total Processes: 18
Syntax: STOP ALL CONFIRM
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 16 Total Processes: 16
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.
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.
This command requires trust level 5.
All return codes from KILL are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax: KILL PID 1884 CONFIRM
Syntax: KILL PID 1231 CONFIRM USING SIGKILL
Syntax: KILL PID 3340 CONFIRM USING WM_CLOSE
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.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return:
Table 64. Definition of map class STAF/Service/Process/ProcessListInfo
| Description: This map class represents a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| command | Command | <String> | Private data will be masked. |
| startTimestamp | Start Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| endTimestamp | End Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| rc | Return Code
(RC) | <String> | <None> |
|
| Notes: The value for "End Date-Time" and "Return Code" will be <None> if the process is still running. | |||
Table 65. Definition of map class STAF/Service/Process/ProcessListLong
| Description: This map class represents detailed information for a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| workload | Workload | <String> | <None> |
|
| command | Command | <String> | Private data will be masked. |
| pid | PID | <String> |
|
| startTimestamp | Start Date-Time
(Start D-T) | <String> | <YYYYMMDD-HH:MM:SS> |
| endTimestamp | End Date-Time
(End D-T) | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| rc | Return Code
(RC) | <String> | <None> |
|
Notes:
| |||
Table 66. Definition of map class STAF/Service/Process/Settings
| Description: This map class represents the operational settings for the Process service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| defaultStopUsing | Default Stop Using Method | <String> |
|
| defaultConsoleMode | Default Console Mode | <String> | 'New' | 'Same' |
| defaultFocus | Default Focus | <String> | 'Background' | 'Foreground' | 'Minimized' |
| processAuthMode | Process Auth Mode | <String> |
|
| defaultAuthUsername | Default Auth Username | <String> | <None> |
|
| defaultAuthPassword | Default Auth Password | <String> | <None> | Private data will be masked. |
| defaultAuthDisabledAction | Default Auth Disabled Action | <String> | 'Ignore' | 'Error' |
| defaultShell | Default Shell | <String> | <None> |
|
| defaultNewConsoleShell | Default New Console Shell | <String> | <None> |
|
| defaultSameConsoleShell | Default Same Console Shell | <String> | <None> |
|
Notes:
| |||
Syntax: LIST (or LIST HANDLES)
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- ------ 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None> 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
Syntax: LIST COMPLETED HANDLES
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- -- 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
Syntax: LIST RUNNING HANDLES
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
Syntax: LIST LONG
Results: If the request is submitted from the command line, the result, in table format, could look like:
H# Workload Command PID Start Date-Time End Date-Time RC
-- -------- ---------------- ---- ----------------- ----------------- ---------
17 <None> notepad.exe 1444 20051205-11:33:14 20040912-11:37:55 0
25 <None> java TestProcess 2836 20051205-11:53:18 20040912-11:53:18 1
5 5 0
29 My Test java TestA 3376 20051205-12:01:05 20040912-12:05:23 0
43 My Test java TestB 2776 20051205-12:32:38 <None> <None>
47 My Test C:/tests/MyTest. 2448 20051205-12:32:56 <None> <None>
exe
56 TC1 C:/tests/tc1.exe 2840 20040912-12:33:24 20040912-12:35:32 3
Syntax: LIST WORKLOAD "My Test"
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Default Stop Using Method : SigKillAll Default Console Mode : New Default Focus : Background Process Auth Mode : Disabled Default Auth Username : <None> Default Auth Password : <None> Default Auth Disabled Action: Ignore Default Shell : <None> Default New Console Shell : <None> Default Same Console Shell : <None>
QUERY allows you to obtain detailed information about a process with a specified handle that was started via STAF.
QUERY HANDLE <Handle>
HANDLE specifies the handle number of the process you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax: QUERY HANDLE 17
Results: If the request is issued from the command line, the result, in default format, could look like:
Handle : 17 Handle Name : <None> Title : Notepad Workload : MyWorkload Shell : <None> Command : notepad.exe Parms : <None> Workdir : <None> Focus : Background User Name : <None> Key : <None> PID : 3280 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : <None> Return Code : <None>
Syntax: QUERY HANDLE 42
Results: If the request was issued from the command line, the result in default format, could look like:
Handle : 42 Handle Name : Web Tests Title : TestA Workload : <None> Shell : <None> Command : D:/Tests/TestA.exe Parms : <None> Workdir : D:/Tests Focus : Background User Name : <None> Key : <None> PID : 3285 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : 20051205-11:37:55 Return Code : 0
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.
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.
This command requires trust level 4.
All return codes from FREE are documented in Appendix A, "API Return Codes".
Table 68. Definition of map class STAF/Service/Process/FreeInfo
| Description: This map class represents statistics for freed processes. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| freedProcesses | Freed Processes | <String> |
|
| totalProcesses | Total Processes | <String> |
|
| Notes: This map contains the number of processes for which termination information was actually freed and the total number of processes. These two numbers will be different if some of the processes have not yet been stopped or have not completed execution. | |||
Syntax: FREE HANDLE 42
Results: If the request is issued from the command line, the result, in default format, could look like:
Freed Processes: 1 Total Processes: 10
Syntax: FREE WORKLOAD "Web Tests"
Results: If the request is issued from the command line, the result, in default format, could look like:
Freed Processes: 2 Total Processes: 17
Syntax: FREE ALL
Results: If the request is issued from the command line, the result, in table format, could look like:
Freed Processes: 15 Total Processes: 16
NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when a given process ends.
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:
}
]
}
These commands require trust level 3.
All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.
Syntax: NOTIFY REGISTER ONENDOFHANDLE 14 PRIORITY 1
Syntax: NOTIFY REGISTER ONENDOFHANDLE 43 MACHINE EventController NAME ProcessHandler
Syntax: NOTIFY UNREGISTER ONENDOFHANDLE 12 HANDLE 43
NOTIFY LIST allows you to view the process end notification list for a given process.
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.
This command requires trust level 2.
All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".
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. | |||
Syntax: NOTIFY LIST ONENDOFHANDLE 57
Results: If the request is issued from the command line, the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- -------------------- --------- --------- 5 automate.austin.ibm.com Handle 48 1 dyno.austin.ibm.com Handle 51 3 automate.austin.ibm.com Name Web Tests
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.
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET DEFAULTSTOPUSING WM_Close
Syntax: SET PROCESSAUTHMODE Windows DEFAULTAUTHUSERNAME user1 DEFAULTAUTHPASSWORD !!@secret@!!
The QUEUE service is one of the internal STAF services. It provides the following commands to manipulate the contents of a handle's queue:
QUEUE allows you to queue a message to a given process handle or to any process registered with a given name.
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.
This command requires trust level 3.
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.
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:
Table 72. Definition of map class STAF/Service/Queue/Error
| Description: This map class represents error information when a message is attempted to be sent to all handles with a specified name and at least one handle's queue is full. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| numberQueued | Number Queued | <String> |
|
| fullQueueList | Handles with Full Queues | <List> of <Map:STAF/Service/Queue/FullInfo> |
|
| Notes: The "Handles with Full Queues" value will contain a list of information about the handles whose queues are full. | |||
Table 73. Definition of map class STAF/Service/Queue/FullInfo
| Description: This map class represents error information for a handle whose queue is full. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle | <String> |
|
| queueSize | Queue Size | <String> |
|
| Notes: The "Handle" value will contain the handle number of a handle whose queue is full and the "Queue Size" value will contain the number of messages that the handle's queue contains. | |||
Syntax: QUEUE MESSAGE "Hello World"
Syntax: QUEUE HANDLE 50 PRIORITY 1 MESSAGE "CONTROL/STAGE2"
Syntax: QUEUE HANDLE 17 TYPE "Build/Complete" MESSAGE "Success"
Syntax: STAF test1.company.com QUEUE QUEUE NAME "MyProduct/Test" MESSAGE "Success"
Results
{
Number Queued : 0
Handles with Full Queues: [
{
Handle : 37
Queue Size: 100
}
]
}
{
Number Queued : 1
Handles with Full Queues: [
{
Handle : 37
Queue Size: 100
}
{
Handle : 41
Queue Size: 100
}
]
}
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.
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:
These commands are only valid with respect to the submitting process' queue and if submitted to the local machine.
All return codes from GET/PEEK are documented in Appendix A, "API Return Codes".
For example:
Table 74. Definition of map class STAF/Service/Queue/Entry
| Description: This map class represents an entry from the queue. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| priority | Priority
(P) | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| machine | Machine | <String> |
|
| handleName | Handle Name
(Name) | <String> | <None> |
|
| handle | Handle
(H#) | <String> |
|
| type | Type | <String> | <None> |
|
| message | Message | <Any> |
|
For example, if a GET or PEEK request is submitted from the command line (without the ALL or FIRST option), the result, in default format, could look like the following:
Priority : 3 Date-Time : 20040912-16:49:11 Machine : tcp://client2.austin.ibm.com@6500 Handle Name: STAF_Process Handle : 17 User : none://anonymous Type : STAF/Start Message :
For example, if a GET ALL or PEEK ALL request is submitted from the comand line using a static handle and that handle's queue contains 5 elements, the result would contain a list of all 5 elements, and, in default format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous A This is message #1 15:48:55 5 20090324- local://local MyHandle 150 none://anonymous A This is message #2 15:48:56 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59 5 20090324- local://local MyHandle 150 none://anonymous A This is message #4 15:49:05 5 20090324- local://local MyHandle 150 none://anonymous B This is message #5 15:49:11
For example, if a GET FIRST 3 or PEEK FIRST 3 request is submitted from the comand line using a static handle and that handle's queue contains 5 elements, the result would contain a list of the first 3 elements, and, in default format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous A This is message #1 15:48:55 5 20090324- local://local MyHandle 150 none://anonymous A This is message #2 15:48:56 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59
For example, if a GET TYPE B FIRST 2 or PEEK TYPE B FIRST 2 request is submitted from the comand line using a static handle and that handle's queue contains the 5 elements from the first example, the result would contain a list of the first 2 elements with type B, and, in default format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59 5 20090324- local://local MyHandle 150 none://anonymous B This is message #5 15:49:11
Syntax: GET WAIT
Syntax: PEEK WAIT MACHINE "tcp://server1.company.com@6500"
Syntax: GET WAIT 30s TYPE STAF/Start
Syntax: PEEK PRIORITY 3 MACHINE "*://client3.company.com*" NAME JavaTest1 CONTAINS {TestString}
Syntax: GET WAIT TYPE STAF/Start TYPE STAF/Shutdown MACHINE tcp://client1.company.com@6500 MACHINE tcp://client2.company.com@6500
Syntax: GET WAIT CONTAINS CONTROL CONTAINS "Hi there"
Syntax: GET WAIT 1m TYPE "MyProduct/Build/Complete" CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"
Syntax: PEEK ALL
Syntax: GET ALL
Syntax: GET FIRST 5 WAIT
Syntax: GET ALL WAIT
Syntax: GET ALL TYPE "STAF/Process/Complete" WAIT
DELETE allows you to delete a set of messages from a queue.
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.
This command is only valid with respect to the submitting process' queue and if submitted to the local machine.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain the number of messages deleted.
Syntax: DELETE MACHINE "local://local"
Syntax: DELETE PRIORITY 3 NAME JavaTest1
Syntax: DELETE PRIORITY 3 PRIORITY 4 MACHINE {Mach1} MACHINE {Mach2} CONTAINS Stage2 CONTAINS {StringTest1}
Syntax: DELETE TYPE "MyProduct/Build/Complete" CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"
Syntax: DELETE
LIST allows you to retrieve the contents of the queue of a given handle.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
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. |
Syntax: LIST
Result: If the request is submitted from the command line, the result, in table format, could look like the following:
P Date-Time Machine Name H# User Type Message
- --------- -------------- ------ -- -------- ---------- ------------------------
1 20040912- tcp://client1. STAF_P 1 none://a STAF/Start
13:56:10 austin.ibm.com rocess nonymous
@6500
3 20040912- tcp://client3. JavaTe 36 none://a FVTTest CONTROL/STAGE2
14:01:52 austin.ibm.com st1 nonymous
3 20040912- tcp://client2. STAF_P 1 none://a STAF/Start
14:02:17 austin.ibm.com rocess nonymous
@6500
5 20040912- tcp://client3. JavaTe 36 none://a <None> This is a test message f
13:57:36 austin.ibm.com st1 nonymous rom Test1. Phase 2 has
@6500 completed.
Syntax: LIST HANDLE 37
Result: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Priority : 5
Date-Time : 20050222-16:50:12
Machine : tcp://client1.austin.ibm.com@6500
Handle Name: STAF_Process
Handle : 1
User : none://anonymous
Type : STAF/Process/End
Message : {
endTimestamp: 20050222-16:50:12
fileList : []
handle : 30
key :
rc : 0
}
}
]
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.
service respool library STAFPool
service respool library STAFPool parms "Directory {STAF/Config/BootDrive}/STAF/ResPool"
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.
LIST displays a list of resource pools and their descriptions.
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.
This command requires trust level 2.
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".
Table 76. Definition of map class STAF/Service/ResPool/Pool
| Description: This map class represents a resource pool. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| poolName | Pool Name | <String> |
|
| description | Description | <String> |
|
Table 77. Definition of map class STAF/Service/ResPool/Service
| Description: This map class represents the settings for the service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| directory | Directory | <String> |
|
Syntax: LIST or LIST POOLS
Results: If the request is submitted from the command line, the result, in table format, could look like:
Pool Name Description ------------------- ------------------------------------------ AUSVMR UserIDs and Passwords for VM System AUSVMR AutoTester_Licenses License numbers for AutoTester
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result could look like:
Directory: C:\STAF\data\STAF\service\respool
Creates a resource pool.
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.
This command requires trust level 4.
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".
The result buffer will contain no data upon return from a CREATE command.
Syntax: CREATE POOL AUSVMR DESCRIPTION "UserIDs and Passwords for VM System AUSVMR"
Deletes a resource pool and all its entries.
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.
This command requires trust level 4.
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".
The result buffer will contain no data upon return from a DELETE command.
Syntax: DELETE POOL AUSVMR CONFIRM
Syntax: DELETE POOL AUSVM1 CONFIRM FORCE
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.
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.
This command requires trust level 4.
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".
The result buffer will contain no data upon return from the ADD command.
Syntax: ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2"
Syntax: ADD POOL AutoTester_Licenses ENTRY 1047923
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.
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.
This command requires trust level 4.
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".
The result buffer will contain no data upon return from the REMOVE command.
Syntax: REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM
Syntax: REMOVE POOL AutoTester_Licenses ENTRY 1137849 ENTRY 107523 CONFIRM FORCE
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.
QUERY POOL <PoolName>
POOL specifies the name of the resource pool you want to query. This option will resolve variables.
This command requires trust level 2.
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".
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:
| |||
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' |
Syntax: QUERY POOL AUSVMR
Results: If the request is submitted from the command line, the result, in verbose format, could look like the following if the resource pool contained three entries (where each entry consisted of a user id and a password) and two of the entries were currently owned.
{
Description : UserIDs and Passwords for VM System AUSVMR
Pending Requests: []
Resources : [
{
Entry: USER1 PASSWORD1
Owner: {
Machine : client3.austin.ibm.com
Handle Name : CM2_Test
Handle : 19
User : none://anonymous
Endpoint : tcp://client3.austin.ibm.com@6500
Date-Time Requested : 20070430-15:58:30
Date-Time Acquired : 20070430-15:58:30
Perform Garbage Collection: Yes
}
}
{
Entry: USER2 PASSWORD2
Owner: {
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Date-Time Requested : 20070430-15:58:19
Date-Time Acquired : 20070430-15:58:19
Perform Garbage Collection: No
}
}
{
Entry: USER3 PASSWORD3
Owner: <None>
}
]
}
Syntax: QUERY POOL AUSVMR
Results: If the request is submitted from the command line, the result, in verbose format, could look like the following if the resource pool contained two entries (where each entry consisted of a user id and a password) and all of the entries were currently owned, with three pending requests.
{
Description : UserIDs and Passwords for VM System AUSVMR
Pending Requests: [
{
Priority : 1
Date-Time Requested : 20100230-16:56:55
Requested Entry : USER1 PASSWORD1
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Perform Garbage Collection: No
}
{
Priority : 50
Date-Time Requested : 20100230-16:54:58
Requested Entry : <None>
Machine : client2.austin.ibm.com
Handle Name : User Access Test
Handle : 28
User : none://anonymous
Endpoint : tcp://client2.austin.ibm.com@6500
Perform Garbage Collection: Yes
}
{
Priority : 50
Date-Time Requested : 20100230-16:55:02
Requested Entry : <None>
Machine : client3.austin.ibm.com
Handle Name : CM3_Test
Handle : 21
User : none://anonymous
Endpoint : tcp://client3.austin.ibm.com@6500
Perform Garbage Collection: Yes
}
]
Resources : [
{
Entry: USER1 PASSWORD1
Owner: {
Machine : client3.austin.ibm.com
Handle Name : CM2_Test
Handle : 19
User : none://anonymous
Endpoint : tcp://client3.austin.ibm.com@6500
Date-Time Requested : 20100230-15:58:30
Date-Time Acquired : 20100230-15:58:30
Perform Garbage Collection: Yes
}
}
{
Entry: USER2 PASSWORD2
Owner: {
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Date-Time Requested : 20100230-15:58:19
Date-Time Acquired : 20100230-15:58:19
Perform Garbage Collection: No
}
}
]
}
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.
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.
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:
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.
This command requires trust level 3.
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".
On successful return, the result buffer will contain the entry given to the process.
Syntax: REQUEST POOL AUSVMR FIRST
Syntax: REQUEST POOL AutoTester_Licenses TIMEOUT 5m
Syntax: REQUEST POOL MachinePool GARBAGECOLLECT No
Syntax: REQUEST POOL MachinePool ENTRY machine1
Syntax: REQUEST POOL MachinePool ENTRY machine2 TIMEOUT 1h
Syntax: REQUEST POOL MachinePool PRIORITY 1
Syntax: REQUEST POOL MachinePool ENTRY machine1 PRIORITY 1
Syntax: REQUEST POOL MachinePool ENTRY machine1 RELEASE PRIORITY 30
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>
}
]
}
RELEASE allows you to release exclusive access of a resource entry in a resource pool.
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.
Command RELEASE requires trust level 3.
Command RELEASE FORCE requires trust level 4.
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".
The result buffer will contain no data upon return from the RELEASE command.
Syntax: RELEASE POOL AUSVMR ENTRY "User2 Password2"
Syntax: RELEASE POOL AutoTester_Licenses ENTRY 1137849 FORCE
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.
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.
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).
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".
On successful return, the result buffer will contain no data.
Syntax: CANCEL POOL TestMachines
Syntax: CANCEL POOL TestMachines FORCE NAME STAX/Job/3 FIRST
Syntax: CANCEL POOL MachinePool FORCE MACHINE client1.company.com HANDLE 43 ENTRY system1 PRIORITY 30
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. |
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:
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.
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:
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:
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.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a REQUEST command.
Syntax: REQUEST MUTEX Printers/Printer1
Syntax: REQUEST MUTEX DataSource1 TIMEOUT 30s
Syntax: REQUEST MUTEX Tests/LongLivedSem GARBAGECOLLECT No
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: []
}
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.
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.
This command requires trust level 3.
Note: If the FORCE option is specified, trust level 4 is required.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RELEASE command.
Syntax: RELEASE MUTEX Printers/Printer1
Syntax: RELEASE MUTEX TestABC FORCE
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.
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.
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).
All return codes are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain no data.
Syntax:
CANCEL MUTEX Printers/Printer1
or
CANCEL MUTEX Printers/Printer1 LAST
Syntax: CANCEL MUTEX Mutex1 FORCE NAME STAX/Job/3 FIRST
Syntax: CANCEL MUTEX Mutex1 FORCE MACHINE client1.company.com HANDLE 43
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.
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.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a POST command.
Syntax: POST EVENT Server1/LAN_Started
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.
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.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RESET command.
Syntax: RESET EVENT Coffee/Ready
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.
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.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a PULSE command.
Syntax: PULSE EVENT Race/StartLap
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.
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:
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a WAIT command.
Syntax: WAIT EVENT Server1/LAN_Started
Syntax: WAIT EVENT Coffee/Ready TIMEOUT 20s
DELETE allows you to delete a mutex or event semaphore.
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.
This command requires trust level 4.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a DELETE command.
Syntax: DELETE MUTEX Printers/Printer1
Syntax: DELETE EVENT Shutdown_The_Lab
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.
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.
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain information about the specified mutex or event semaphore:
Table 83. Definition of map class STAF/Service/Sem/QueryMutex
| Description: This map class represents a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| state | State | <String> | 'Unowned' | 'Owned' |
| owner | Owner | <None> | <Map:STAF/Service/Sem/MutexOwner> |
|
| requestList | Pending Requests | <List> of <Map:STAF/Service/Sem/PendingRequest> |
|
Notes:
| |||
Table 84. Definition of map class STAF/Service/Sem/MutexOwner
| Description: This map class represents the owner of a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
| acquireTimestamp | Date-Time Acquired | <String> | <YYYYMMDD-HH:MM:SS> |
| gc | Perform Garbage Collection | <String> | 'Yes' | 'No' |
Table 85. Definition of map class STAF/Service/Sem/PendingRequest
| Description: This map class represents a pending request which is waiting to acquire a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
| gc | Perform Garbage Collection | <String> | 'Yes' | 'No' |
Table 86. Definition of map class STAF/Service/Sem/QueryEvent
| Description: This map class represents an event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| state | State | <String> | 'Posted' | 'Reset' |
| lastPosted | Last Posted | <Map:STAF/Service/Sem/EventRequester> |
|
| lastReset | Last Reset | <Map:STAF/Service/Sem/EventRequester> |
|
| waiterList | Waiters | <List> of <Map:STAF/Service/Sem/EventRequester> |
|
| Notes: If the event semaphore is currently in a reset state, "Waiters" will contain a list of requests waiting for the semaphore, if any. | |||
Table 87. Definition of map class STAF/Service/Sem/EventRequester
| Description: This map class represents a request for a event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in default format, could look like:
State : Unowned Owner : <None> Pending Requests: []
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Owned
Owner : {
Machine : machine1.austin.ibm.com
Handle Name : STAX/Job/1
Handle : 17
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time Requested : 20070430-23:54:41
Date-Time Acquired : 20070430-23:54:41
Perform Garbage Collection: Yes
}
Pending Requests: []
}
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Owned
Owner : {
Machine : machine1.austin.ibm.com
Handle Name : STAX/Job/1
Handle : 17
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time Requested : 20070430-23:54:41
Date-Time Acquired : 20070430-23:54:41
Perform Garbage Collection: Yes
}
Pending Requests: [
{
Machine : machine2.austin.ibm.com
Handle Name : STAF/Client
Handle : 32
User : none://anonymous
Endpoint : tcp://machine2.austin.ibm.com@6500
Date-Time Requested : 20070430-23:56:16
Perform Garbage Collection: No
}
{
Machine : server1.austin.ibm.com
Handle Name : semTest
Handle : 49
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server1.austin.ibm.com@6500
Date-Time Requested : 20070430-23:56:31
Perform Garbage Collection: Yes
}
]
}
Syntax: QUERY EVENT Server1/LAN_Started
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Posted
Last Posted: {
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 20
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041026-23:59:51
}
Last Reset : {
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041026-23:59:15
}
Waiters : []
}
Syntax: QUERY EVENT Server1/LAN_Started
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Reset
Last Posted: {
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 20
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041026-23:59:51
}
Last Reset : {
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Test1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041027-00:02:12
}
Waiters : [
{
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041027-00:02:18
}
{
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 22
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041027-00:02:15
}
]
}
LIST allows you to obtain a list of the mutex or event semaphores.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a list of the desired mutex or event semaphores:
Table 88. Definition of map class STAF/Service/Sem/MutexInfo
| Description: This map class represents a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| state | State | <String> | 'Unowned' | 'Owned' |
| pendingRequests | Pending Requests | <String> |
|
| Notes: "Pending Requests" is the number of requests waiting to acquire the mutex. | |||
Table 89. Definition of map class STAF/Service/Sem/EventInfo
| Description: This map class represents an event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| state | State | <String> | 'Posted' | 'Reset' |
| waiters | Waiters | <String> |
|
| Notes: "Waiters" is the number of waiters waiting on the event semaphore. | |||
Syntax: LIST MUTEX
Results: If the request is issued from the command line, the result, in table format, could look like:
Name State Pending Requests ----------------- ------- ---------------- DataSource1 Unowned 0 Printers/Printer1 Owned 2
Syntax: LIST EVENT
Results: If the request is issued from the command line, the result, in table format, could look like:
Name State Waiters ------------------- ------ ------- Coffee/Ready Posted 0 Server1/LAN_Started Reset 5 Shutdown_The_Lab Reset 0
The SERVICE service is one of the internal STAF services. It provides the following commands.
LIST will display information about the services, service loaders, or authenticators available on the machine, or requests that have been submitted on the machine.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 90. Definition of map class STAF/Service/Service/ServiceInfo
| Description: This map class represents a service, serviceloader, or authenticator. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| library | Library | <String> | '<Internal>', '<Delegated>' or library name if external service |
| executable | Executable | <String> | <None> |
|
Notes:
| |||
Table 91. Definition of map class STAF/Service/Service/RequestInfo
| Description: This map class represents information about a request that has been submitted. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| requestNumber | Request#
(Req#) | <String> |
|
| state3 | Status | <String> | 'Pending' | 'Complete' |
| sourceMachine1 | Source Machine
(Source) | <String> |
|
| sourceHandleName1 | Source Handle Name
(Handle Name) | <String> |
|
| sourceHandle1 | Source Handle
(H#) | <String> |
|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| targetMachine1 | Target Machine
(Target) | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> | Private data will be masked. |
| rc2 | Return Code
(RC) | <String> | <None> |
|
| result2 | Result | <String> | <None> |
|
Notes:
| |||
Table 92. Definition of map class STAF/Service/Service/RequestSummary
| Description: This map class represents summary information about requests. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| activeRequests | Active Requests | <String> |
|
| totalRequests | Total Requests | <String> |
|
| resetCount | Reset Count | <String> |
|
| requestNumberRange | Request Number Range | <String> | <Minimum - Maximum> |
| maxActiveRequests | Maximum Active Requests | <String> |
|
Notes:
| |||
Syntax: LIST SERVICES
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable -------- ---------- ------------------------------------- CRON JSTAF C:\STAF\services\STAFCron.jar DELAY <Internal> <None> DIAG <Internal> <None> ECHO <Internal> <None> EM JSTAF C:\STAF\services\STAFEventManager.jar EMAIL JSTAF C:\STAF\services\STAFEmail.jar EVENT JSTAF C:\STAF\services\STAFEvent.jar FS <Internal> <None> HANDLE <Internal> <None> HELP <Internal> <None> LOG STAFLog <None> MISC <Internal> <None> MONITOR STAFMon <None> NC JSTAF C:\STAF\services\STAFNamedCounter.jar PING <Internal> <None> PROCESS <Internal> <None> QUEUE <Internal> <None> RESPOOL STAFPool <None> SEM <Internal> <None> SERVICE <Internal> <None> SHUTDOWN <Internal> <None> STAX JSTAF C:\STAF\services\STAX.jar TIMER JSTAF C:\STAF\services\STAFTimer.jar TRACE <Internal> <None> TRUST <Internal> <None> VAR <Internal> <None>
Syntax: LIST SERVICELOADERS
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable ------------------ -------- ---------------------------------------- STAFSERVICELOADER1 STAFDSLS <None> STAFSERVICELOADER2 JSTAF C:\STAF\services\CustomServiceLoader.jar
Syntax: LIST AUTHENTICATORS
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable ---------- ------- -------------------------------------------------------- AUTHSAMPLE JSTAF C:\STAF\services\AuthSample.jar IBM JSTAF C:\STAF\services\STAFIBMIntraAuth.jar
Syntax: LIST REQUESTS
Results: If the request is issued from the command line, the result, in table format, could look like:
Request# Start Date-Time Service Request -------- ----------------- ------- ------------------------------------------ 39 20050321-16:33:03 QUEUE GET WAIT 63 20050321-16:33:03 QUEUE GET WAIT 10000 102 20050321-16:34:42 QUEUE GET WAIT 120000 TYPE ProductA/Test2/Status 165 20050321-16:34:52 DELAY DELAY 60000 106 20050321-16:34:58 SERVICE LIST REQUESTS
Syntax: LIST REQUESTS LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request
---- ------- ------------ -- --------- ---------- ------- ---------------------
39 local:/ STAF/SERVICE 11 20050321- client1.co QUEUE GET WAIT
/local /eM 14:25:04 mpany.com
63 local:/ STAF/Service 16 20050321- client1.co QUEUE GET WAIT 10000
/local /TimeR/Watch 14:25:04 mpany.com
102 local:/ ProductA/Tes 21 20050321- client1.co QUEUE GET WAIT 120000 TYPE
/local t2 16:34:42 mpany.com ProductA/Test2/Status
165 local:/ STAF/Client 27 20050321- client2 DELAY DELAY 60000
/local 16:34:52
180 local:/ STAF/Client 34 20050321- client1.co SERVICE LIST REQUESTS LONG
/local 14:39:04 mpany.com
Syntax: LIST REQUESTS PENDING COMPLETE LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# State Source Handle Name H# Date-Time Target Service Request RC Result
---- ------- ------- ----------- -- --------- ------ ------- -------- -- ------
39 Pending local:/ STAF/SERVIC 11 20050321- client QUEUE GET WAIT <N <None>
/local E/eM 14:25:04 1.comp on
any.co e>
m
63 Pending local:/ STAF/Servic 16 20050321- client QUEUE GET WAIT <N <None>
/local e/TimeR/Wat 14:25:04 1.comp 10000 on
ch any.co e>
m
102 Pending local:/ ProductA/Te 21 20050321- client QUEUE GET WAIT <N <None>
/local st2 16:34:42 1.comp 120000 T on
any.co YPE Prod e>
m uctA/Tes
t2/Statu
s
165 Pending local:/ STAF/Client 27 20050321- client DELAY DELAY 60 <N <None>
/local 16:34:52 2 000 on
e>
176 Complet local:/ TestA 36 20050321- client MISC VERSION 0 3.0.0
e /local 13:30:14 1.comp
any.co
m
180 Pending local:/ STAF/Client 38 20050321- client SERVICE LIST REQ <N <None>
/local 13:30:16 1.comp UESTS PE on
any.co NDING CO e>
m MPLETE L
ONG
Syntax: LIST REQUESTS COMPLETE LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request RC Result
---- ------- ----------- -- --------- ---------- ------- -------- -- ------
176 local:/ TestA 36 20050321- client1.co MISC VERSION 0 3.0.0
/local 13:30:14 mpany.com
Syntax: LIST REQUESTS SUMMARY
Results: If the request is issued from the command line, the result, in default form, could look like:
Active Requests : 12 Total Requests : 24127 Reset Count : 0 Request Number Range : 1 - 2147483647 Maximum Active Requests: 2147483647
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.
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.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain the following based on the request:
Table 93. Definition of map class STAF/Service/Service/QueryService
| Description: This map class represents a service, service loader, or authenticator. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| library | Library | <String> | '<Internal>', '<Delegated>' or library name if external service |
| executable | Executable | <String> | <None> |
|
| options | Options | List of <String> |
|
| parameters | Parameters | <String> | <None> |
|
Notes:
| |||
Table 94. Definition of map class STAF/Service/Service/QueryRequest
| Description: This map class represents a request that has been submitted. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| requestNumber | Request# | <String> |
|
| state | Request Status | <String> | 'Pending' | 'Complete' |
| sourceMachine | Source Machine | <String> |
|
| sourceHandleName | Source Handle Name | <String> |
|
| sourceHandle | Source Handle | <String> |
|
| startTimestamp | Start Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| targetMachine | Target Machine | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> |
|
| rc | Return Code | <String> | <None> |
|
| result | Result | <String> | <None> |
|
Notes:
| |||
Syntax: QUERY SERVICE LOG
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : LOG
Library : STAFLog
Executable: <None>
Options : []
Parameters: DEFAULTMAXQUERYRECORDS 50
}
Syntax: QUERY SERVICE STAX
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : STAX
Library : JSTAF
Executable: C:\STAF\services\stax\STAX.jar
Options : [
JVMName=STAX
J2=-Xmx512m
]
Parameters: EXTENSIONXMLFILE C:/STAF/services/stax/extensions.xml
}
Syntax: QUERY AUTHENTICATOR AuthSample
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : AUTHSAMPLE
Library : JSTAF
Executable: C:\STAF\authenticators\AuthSample.jar
Options : [
JVMName=Auth
]
Parameters: USERPROPERTIESFILE C:/STAF/authenticators/authsample.properties
}
Syntax: QUERY SERVICELOADER STAFServiceLoader1
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : STAFSERVICELOADER1
Library : STAFDSLS
Executable: <None>
Options : []
Parameters: <None>
}
Syntax: QUERY REQUEST 34
Results: If the request is issued from the command line, the result, in default format, could look like:
Request Number : 34 Request Status : Pending Source Machine : local://local Source Handle Name: STAF/SERVICE/EM Source Handle : 10 Start Date-Time : 20050321-19:02:28 Target Machine : server1.company.com Service : QUEUE Request : GET WAIT Return Code : <None> Result : <None>
ADD will add (register and initialize) the specified external service and make it available on the machine.
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.
This command requires trust level 5.
All return codes from ADD are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain nothing.
Syntax: ADD SERVICE Monitor LIBRARY STAFMon
Syntax: ADD SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar PARMS "NUMTHREADS 8"
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).
REMOVE SERVICE <Service Name>
SERVICE specifies the name of the service to remove.
This command requires trust level 5.
All return codes from REMOVE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain nothing.
Syntax: REMOVE SERVICE Event
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.
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.
This command requires trust level 5.
All return codes from FREE are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax: FREE REQUEST 16
Results: If the request is issued from the command line, the result, in default format, could look like:
Return Code: 0 Result : 3.0.0
The SHUTDOWN service is an internal STAF service. It provides the following commands.
SHUTDOWN, as the name implies, submits a request to shut down the STAFProc program.
Note: A SHUTDOWN request returns before STAFProc completes shutting down. It may take up to a minute or so after a SHUTDOWN request has returned for STAFProc to finish shutting down all of its registered services.
SHUTDOWN
This command requires trust level 5.
All return codes from SHUTDOWN are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a SHUTDOWN command.
Goal: Shutdown STAFProc on the local system.
STAF local SHUTDOWN SHUTDOWN
NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when the STAF Process is SHUTDOWN.
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.
These commands require trust level 3.
All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.
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
NOTIFY LIST allows you to view the shutdown notification list.
NOTIFY LIST
This command requires trust level 2.
All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".
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. | |||
Request: NOTIFY LIST
Results: If the request is issued from the command line, the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- ---------------------- --------- --------------- 5 server1.austin.ibm.com Name ShutdownCatcher 3 client2.austin.ibm.com Handle 18
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.
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.
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
}
]
}
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. |
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.
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.
This command requires trust level 5.
All return codes from ENABLE are documented in Appendix A, "API Return Codes".
For ENABLE the result buffer will be empty if there are no errors
Syntax: ENABLE TRACEPOINTS "ServiceRequest ServiceResult ServiceManagement"
Syntax: ENABLE TRACEPOINTS "Error Warning"
Syntax: ENABLE ALL TRACEPOINTS
Syntax: ENABLE TRACEPOINT RemoteRequests
Syntax: ENABLE SERVICES "PROCESS QUEUE"
Syntax: ENABLE ALL SERVICES
Syntax: ENABLE ALL
Syntax: ENABLE SERVICE VAR
Syntax: ENABLE SERVICE :7:SERVICE
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.
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.
This command requires trust level 5.
All return codes from DISABLE are documented in Appendix A, "API Return Codes".
For DISABLE the result buffer will be empty if there are no errors
Syntax: DISABLE TRACEPOINTS "ServiceAccessDenied Error"
Syntax: DISABLE TRACEPOINTS "ServiceResult Error"
Syntax: DISABLE ALL TRACEPOINTS
Syntax: DISABLE TRACEPOINT RemoteRequests
Syntax: DISABLE SERVICES "PROCESS QUEUE"
Syntax: DISABLE ALL SERVICES
Syntax: DISABLE ALL
Syntax: DISABLE SERVICE VAR
Syntax: DISABLE SERVICE :7:SERVICE
PURGE removes all unregistered services from the service list
PURGE
This command requires trust level 5.
All return codes from PURGE are documented in Appendix A, "API Return Codes".
For PURGE the result buffer will be empty if there are no errors.
Syntax: PURGE
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
LIST [SETTINGS]
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
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:
| |||
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. | |||
Syntax: LIST or LIST SETTINGS
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
Tracing To : Stdout
File Mode : <None>
Default Service State : Enabled
Maximum Service Result Size: 0
Trace Points : {
Info : Disabled
Warning : Enabled
Error : Enabled
ServiceRequest : Disabled
ServiceResult : Disabled
ServiceError : Disabled
ServiceAccessDenied: Disabled
RemoteRequests : Disabled
Registration : Disabled
Deprecated : Enabled
Debug : Disabled
}
Services : {
DELAY : Enabled
DIAG : Disabled
ECHO : Enabled
EMAIL : Enabled
EVENT : Enabled
FS : Enabled
HANDLE : Enabled
HELP : Disabled
LOG : Enabled
MONITOR : Enabled
MISC : Enabled
PING : Enabled
PROCESS : Enabled
QUEUE : Enabled
SEM : Enabled
SERVICE : Enabled
SHUTDOWN: Enabled
STAX : Enabled
TRACE : Enabled
TRUST : Enabled
VAR : Enabled
}
}
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.
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
For SET the result buffer will be empty
Syntax: SET DESTINATION TO STDERR
Syntax: SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc
Syntax: SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc APPEND
Syntax: SET DESTINATION TO STDOUT FILE {STAF/Config/STAFRoot}/bin/STAF.trc
Syntax: SET DEFAULTSERVICESTATE Enabled
Syntax: SET MAXSERVICERESULTSIZE 5k
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.
SET will set the default trust level or the trust level for a specific machine or user.
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.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a SET command.
Syntax: SET MACHINE local://local LEVEL 5
Syntax: SET DEFAULT LEVEL 1
Syntax: SET MACHINE client1.austin.ibm.com LEVEL 5
Syntax: SET MACHINE 9.3.224.16 LEVEL 5
Syntax: SET MACHINE tcp://mysystem.site.com LEVEL 4
Syntax: SET MACHINE badguy.austin.ibm.com LEVEL 0
Syntax: SET MACHINE tcp2://9.3.224.* LEVEL 3
Syntax: SET MACHINE *.austin.ibm.com LEVEL 2
Syntax: SET MACHINE tcp*://*.site.com LEVEL 2
Syntax: SET USER John@company.com LEVEL 5
Syntax: SET USER badguy@company.com LEVEL 0
Syntax: SET USER *@company.com LEVEL 3
Syntax: SET USER SampleAuth://*@company.com LEVEL 4
Syntax: SET USER *://* LEVEL 1
GET will return the effective trust level of a specific machine and, optionally, for a specific user.
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.
This command requires trust level 2.
All return codes from GET are documented in Appendix A, "API Return Codes".
The result buffer will contain the effective trust level of the given machine.
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
LIST will return the default trust level and a list of the trust entries for machines and users.
LIST
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
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:
| |||
Syntax: LIST
Result: If the request is submitted from the command line, the result, in table format, could look like:
Type Entry Trust Level ------- ----------------------------- ----------- Default <None> 1 Machine *://*.austin.ibm.com 2 Machine *://9.31.73.14* 3 Machine *://9.31.73.147 5 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
DELETE will remove the explicit trust entry for the specified machine or user.
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:
This command requires trust level 5.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a DELETE command.
Syntax: DELETE MACHINE client1.austin.ibm.com
Syntax: DELETE MACHINE tcp://mysystem.site.com
Syntax: DELETE MACHINE 9.3.224.82
Syntax: DELETE MACHINE *.austin.ibm.com
Syntax: DELETE USER John@company.com
Syntax: DELETE USER *@company.com
Syntax: DELETE USER Auth2://Mary
Syntax: DELETE USER *://*
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.
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.
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.
This command requires trust level 3.
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.
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:
Table 102. Definition of map class STAF/Service/Var/ErrorInfo
| Description: This map class represents information on whether a variable was successfully set. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> | |
| rc | RC | <String> |
|
| result | Result | <String> |
|
| Notes:
If a variable is set successfully, its "RC" value will be '0' and its "Result" will be blank. If a variable is not set successfully because the FAILIFEXISTS option was specified and the variable already exists, its "RC" value will be '49' (Already Exists) and its "Result" will contain the variable's value. Otherwise, if another error occurred setting the variable, its "RC" value will contain the error return code and its "Result" may contain additional information about the error, | |||
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.
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.
This command requires trust level 2.
All return codes from GET are documented in Appendix A, "API Return Codes".
The result buffer will contain the value of the variable.
LIST will return a list of all variables and their values.
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.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
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
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).
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:
This command requires trust level 2.
All return codes from RESOLVE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain results based on whether the STRING option was specified once or multiple times:
Table 104. Definition of map class STAF/Service/Var/ResolveString
| Description: This map class represents a string with all variable references resolved. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | RC | <String> |
|
| result | Result | <String> |
|
| Notes:
If all variables in the string are resolved successfully, the "RC" value will be '0' and the "Result" will contain the string with all variable references resolved. Otherwise, if an error occurred resolving a string, the "RC" value will contain the error return code and the result will contain additional information on the error, such as the name of a variable that could not be resolved. | |||
For the following examples, assume the following variables are in System1's system variable pool
a=Partridge b=Doves c=Hens d=Birds e=Ringsthe following variables are in System1's shared variable pool
a=Happy b=Sleepythe following variables are in System1's originating handle variable pool
a=Onethe following variables are in System2's system variable pool
a=Geese b=Swans c=Maids d=Ladies e=Lordsthe following variables are in System2's shared variable pool
d=Grumpy e=Dopeyand the following variables are in the System1's variable pool associated with handle 71
a=Dogs b=CatsLet'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.
RC Result
-- ----------------------------------------------------------------------------
0 3.4.1
13 Variable resolution failed for string: {aaa} You are trying to resolve a va
riable that does not exist: aaa
0 C:
Here's an example of using the IGNOREERRORS option on a VAR RESOLVE request:
PythonMap = {'x': 1, 'osName': 'Linux'}
If you did not use the IGNOREERRORS option, RC 13 (Variable Does Not Exist) would have been returned as follows:
Error submitting request, RC: 13
Additional info
---------------
Variable resolution failed for string: PythonMap = {'x': 1, 'osName': '{STAF/Config/OS/Name}'}
You are trying to resolve a variable that does not exist: 'x': 1, 'osName': 'Linux'
DELETE will remove the given variable from the appropriate variable pool.
Note that you may DELETE multiple variables with a single request.
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.
This command requires trust level 3.
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.
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:
Table 105. Definition of map class STAF/Service/Var/ErrorInfo
| Description: This map class represents information on whether a variable was successfully deleted. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> | |
| rc | RC | <String> |
|
| result | Result | <String> |
|
| Notes:
If a variable is deleted successfully, its "RC" value will be '0' and its "Result" will be blank. If an error occurred deleting a variable, its "RC" value will contain the error return code and its "Result" may contain additional information about the error, | |||
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.
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".
service ZIP library STAFZip
Extract all entries (or specified files and/or directories) from a Zip archive to a specified directory.
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.
This command requires trust level 4.
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".
On a successful return, the result buffer will contain no data on return from a UNZIP command.
Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY D:/mydata/
Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY /usr/lpp/mydata/ FILE myjava/Hello.java RESTOREPERMISSION REPLACE
Syntax: UNZIP ZIPFILE C:/temp/STAXV302.zip TODIRECTORY {STAF/Config/STAFRoot}/services DIRECTORY stax/docs
Syntax: UNZIP ZIPFILE C:/temp/STAXV302.zip TODIRECTORY C:/STAF/services FILE stax/STAX.jar FILE stax/STAFEvent.jar DIRECTORY stax/libraries DIRECTORY stax/samples REPLACE
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 into 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.
This command requires trust level 4.
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".
On a successful return, the result buffer will contain no data on return from a ZIP command.
Syntax: ADD ZIPFILE D:/myzip.zip FILE C:/file.txt
Syntax: ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RELATIVETO /opt
Syntax: ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RECURSE RELATIVETO /opt
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.
This command requires trust level 4.
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".
On a successful return, the result buffer will contain no data on return from a DELETE command.
Syntax: DELETE ZIPFILE D:/myzip.zip FILE myjava/Hello.java CONFIRM
Syntax: DELETE ZIPFILE /opt/myzip.zip FILE myjava/Hello.java FILE bin/run CONFIRM
LIST ZIPFILE <Name>
ZIPFILE contains the fully qualified ZIP archive name.
This command requires trust level 3.
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"
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:
| |||
Syntax: LIST ZIPFILE /usr/local/staf/services/STAXV301.zip
Results: If the request is submitted from the command line, the result, in table format, could look like:
Length Method Size Ratio Date Time CRC-32 Name
------- ------ ------- ----- -------- ----- -------- --------------------------
0 Stored 0 0% 07-28-05 03:44 00000000 stax/
0 Stored 0 0% 07-28-05 03:44 00000000 stax/docs/
42748 Defl:N 13022 30% 07-28-05 03:44 f72affac stax/docs/History
86379 Defl:N 58971 68% 07-28-05 03:44 aeb290ca stax/docs/STAXDoc.pdf
926998 Defl:N 711411 76% 07-28-05 03:44 92496663 stax/docs/staxgs.pdf
921917 Defl:N 653042 70% 07-28-05 03:44 e4e64a11 stax/docs/staxug.pdf
0 Stored 0 0% 07-28-05 03:44 00000000 stax/ext/
2029 Defl:N 572 28% 07-28-05 03:44 b9c0e581 stax/ext/stax-extensions.d
td
0 Stored 0 0% 07-28-05 03:44 00000000 stax/libraries/
57120 Defl:N 10726 18% 07-28-05 03:44 03e1c2d9 stax/libraries/STAXUtil.ht
ml
77766 Defl:N 14909 19% 07-28-05 03:44 2cfa2ce7 stax/libraries/STAXUtil.xm
l
2118 Defl:N 938 44% 07-28-05 03:44 f15cb878 stax/readme.1st
0 Stored 0 0% 07-28-05 03:44 00000000 stax/samples/
5274 Defl:N 826 15% 07-28-05 03:44 277d4fb7 stax/samples/FunctionList.
xsl
10528 Defl:N 2830 26% 07-28-05 03:44 b6dfa3ee stax/samples/sample1.xml
30281 Defl:N 27699 91% 07-28-05 03:44 837e1ab4 stax/STAFEvent.jar
2607441 Defl:N 2541497 97% 07-28-05 03:44 0b9b43aa stax/STAX.jar
25619 Defl:N 22208 86% 07-28-05 03:44 8104f5b9 stax/STAXDoc.jar
189539 Defl:N 177191 93% 07-28-05 03:44 bd0c4288 stax/STAXMon.jar
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. |
Some utilities are provided to assist in viewing and formatting STAF log files and the JVM Log files.
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.
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.
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.
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 "|".
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
Date-Time|Machine|Handle|Handle Name|User|Endpoint|Level|Message
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
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:
|
| 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 and why 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:
|
| 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. More details about why a specific file could not be copied may be provided by submitting a COPY FILE request instead of a COPY DIRECTORY request. |
| 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. |
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
|
| 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. |
/*****************************************************************************/
/* 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;
}
/*****************************************************************************/
/* 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
/*****************************************************************************/
/* 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
/*****************************************************************************/
/* 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 */
/* ---------- ------------ --------------------------------------- */
/* 03/01/1998 D. Randall File Created */
/*********************************************************************/
SIGNAL ON HALT NAME STAFAbort
/* Load STAF functions */
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
call STAFLoadFuncs
/* Register Sample to STAF */
call STAFRegister "STAF_REXX_Sample3"
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/MachineNickname}")
if STAFRC = 0 then machine = STAFResult
else
do
say "Unable to determine machine nickname!"
call STAFUnRegister
RETURN STAFRC
end
service = "monitor"
times = 10
wait = 0
string = "Software Testing Automation Framework (STAF) (C) Copyright IBM Corp.",
"1998 All Rights Reserved"
do times
message = substr(string,1,1 + random(99))
msglen = length(message)
data = "LOG MESSAGE :"msglen":"message
STAFRC = STAFSubmit("local", service, data)
if STAFRC \= 0 then
say "Monitor Log Error: " STAFRC STAFResult
data = "query machine" machine "handle" STAFHandle
STAFRC = STAFSubmit("local", service, data)
if STAFRC = 0 then
say STAFResult
else
say "Monitor Query Error: " STAFRC STAFResult
end
/* Unregister */
call STAFUnRegister
RETURN 0
/*********************************************************************/
/* STAFAbort - If user aborts, make sure STAF unregister occurs. */
/*********************************************************************/
STAFAbort:
call STAFUnRegister
EXIT 1
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the Eclipse Public License (EPL) V1.0. */
/*****************************************************************************/
/*********************************************************************/
/* Sample4.cmd - Rexx sample program using STAF */
/*********************************************************************/
/* This sample writes 10 log messages to a global log file called */
/* LOGTEST and then queries them. The 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 */
/* ---------- ------------ --------------------------------------- */
/* 03/02/1998 D. Randall File Created */
/*********************************************************************/
SIGNAL ON HALT NAME STAFAbort
/* Load STAF functions */
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
call STAFLoadFuncs
/* Register Sample to STAF */
call STAFRegister "STAF_REXX_Sample4"
if RESULT \= 0 then
do
say "Error registering to STAF:" RESULT
RETURN RESULT
end
/* Query STAF for a variable */
STAFRC = STAFSubmit("local", "var", "global resolve {STAF/Config/Machine}")
if STAFRC = 0 then machine = STAFResult
else
do
say "Unable to determine machine name!"
call STAFUnRegister
RETURN STAFRC
end
service = "LOG"
times = 10
count = 0
level = error
logtype = "log global logname "
logname=LogTest
string = "Software Testing Automation Framework (STAF) (C) Copyright IBM Corp.",
"1998. All Rights Reserved"
say "Settings:" logtype logname "level" level "(times=" times ")"
do count = 1 for times
message = substr(string,1,1 + random(99))
msglen = length(message)
data = "LOG GLOBAL LOGNAME" logname "LEVEL" level "MESSAGE :"msglen":"message
STAFRC = STAFSubmit("LOCAL", service, data)
if STAFRC \= 0 then
say "Log Error: " STAFRC STAFResult
say count "of" times "Logged"
end
say "Querying last 10 log records..."
data = "QUERY GLOBAL LOGNAME" logname "LAST 10"
STAFRC = STAFSubmit("local", service, data)
say STAFResult
/* Unregister */
call STAFUnRegister
RETURN 0
/*********************************************************************/
/* STAFAbort - If user aborts, make sure STAF unregister occurs. */
/*********************************************************************/
STAFAbort:
call STAFUnRegister
EXIT 1
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the Eclipse Public License (EPL) V1.0. */
/*****************************************************************************/
/*********************************************************************/
/* Sample5.cmd - Rexx sample program using STAF */
/*********************************************************************/
/* This sample uses the STAF Ping command to ping a STAF client and */
/* and measure the throughput. */
/* */
/* Accepts: [Machine] [LoopCount] [DisplayModulus] */
/* */
/* Returns: 0, on success */
/* >0, if an error is encountered */
/*********************************************************************/
/* Date Who Comment */
/* ---------- ------------ --------------------------------------- */
/* 03/02/1998 C. Rankin File Created */
/*********************************************************************/
SIGNAL ON HALT NAME STAFAbort
parse arg Machine LoopCount DisplayModulus
if (Machine = "?") | (Machine = "/?") | (Machine = "-?") then
do
say
say "Usage: PingTest [Machine] [LoopCount] [DisplayModulus]"
RETURN 1
end
if Machine = "" then Machine = "LOCAL"
if LoopCount = "" then LoopCount = 999999999
if DisplayModulus = "" then DisplayModulus = 1000
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
call STAFLoadFuncs
call STAFRegister "STAF_PING_Test", "STAFHandle"
if RESULT \= 0 then
do
say "Error registering with STAF, RC:" RESULT
RETURN 1
end
say TIME() "- Started"
startDate = DATE('B')
startTime = TIME('S')
errors = 0
do i=1 to LoopCount
call STAFSubmit STAFHandle, Machine, "PING", "PING"
if RESULT \= 0 then
do
errors = errors + 1
say TIME() "- Loop #"i", Error #"errors", RC:" RESULT
end
else if STAFResult \= "PONG" then
do
errors = errors + 1
say TIME() "- Loop #"i", Error #"errors", STAFResult =" STAFResult
end
if i // DisplayModulus = 0 then
say TIME() "- Ended Loop #"i", Errors =" errors
end
call AtEnd
RETURN 0
/*********************************************************************/
/* AtEnd - Unregister from STAF and calculate final PING throughput. */
/*********************************************************************/
AtEnd:
call STAFUnRegister STAFHandle
say TIME() "- Ended"
endTime = TIME('S')
endDate = DATE('B')
endSecs = ((endDate - 720000) * 86400) + endTime
startSecs = ((startDate - 720000) * 86400) + startTime
say "Average:" FORMAT((i / (endSecs - startSecs)), 3, 2) "pings/sec"
RETURN 0
/*********************************************************************/
/* STAFAbort - If user aborts, make sure STAF unregister occurs. */
/*********************************************************************/
STAFAbort:
call AtEnd
EXIT 1
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the Eclipse Public License (EPL) V1.0. */
/*****************************************************************************/
#include <string.h>
#include <stdio.h>
#include "STAF.h"
unsigned int logIt(char *type, char *name, char *level, char *message);
// This could be a handy macro.
// Just set gLogType and gLogName to the appropriate values.
// Then you can use the macro as follows
// LOGIT("INFO", "This is some data I want to log");
#define LOGIT(level, message) logIt(gLogType, gLogName, level, message)
char *gLogType = "GLOBAL";
char *gLogName = "MyLog";
char *gRegName = "Logit";
STAFHandle_t gHandle = 0;
int main(int argc, char **argv)
{
unsigned int rc = 0;
if (argc != 5)
{
printf("Usage: %s <Type> <Name> <Level> <Message>\n", argv[0]);
return 1;
}
if ((rc = STAFRegister(gRegName, &gHandle)) != 0)
{
printf("Error registering with STAF, RC: %d\n", rc);
return rc;
}
if ((rc = logIt(argv[1], argv[2], argv[3], argv[4])) != 0)
{
printf("Error logging data to STAF, RC: %d\n", rc);
return rc;
}
if ((rc = STAFUnRegister(gHandle)) != 0)
{
printf("Error unregistering with STAF, RC: %d\n", rc);
return rc;
}
return rc;
}
unsigned int logIt(char *type, char *name, char *level, char *message)
{
static char *where = "LOCAL";
static char *service = "LOG";
static char buffer[4000] = { 0 };
char *resultPtr = 0;
unsigned int resultLength = 0;
unsigned int rc = 0;
sprintf(buffer, "LOG %s LOGNAME %s LEVEL %s MESSAGE :%d:%s", type, name,
level, strlen(message), message);
rc = STAFSubmit(gHandle, where, service, buffer, strlen(buffer),
&resultPtr, &resultLength);
STAFFree(gHandle, resultPtr);
return rc;
}
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the Eclipse Public License (EPL) V1.0. */
/*****************************************************************************/
#include "STAF.h"
#include "STAF_iostream.h"
#include "STAFString.h"
STAFResultPtr logIt(const STAFString &type, const STAFString &name,
const STAFString &level, const STAFString &message);
// This could be a handy macro.
// Just set gLogType and gLogName to the appropriate values.
// Then you can use the macro as follows
// LOGIT("INFO", "This is some data I want to log");
#define LOGIT(level, message) logIt(gLogType, gLogName, level, message)
STAFString gLogType("GLOBAL");
STAFString gLogName("MyLog");
STAFString gRegName("Logit");
STAFHandlePtr gHandle;
int main(int argc, char **argv)
{
if (argc != 5)
{
cout << "Usage: LogIt <Type> <Name> <Level> <Message>" << endl;
return 1;
}
unsigned int rc = STAFHandle::create(gRegName, gHandle);
if (rc != 0)
{
cout << "Error registering with STAF, RC: " << rc << endl;
return rc;
}
STAFResultPtr result = logIt(argv[1], argv[2], argv[3], argv[4]);
if (result->rc != 0)
{
cout << "Error logging to STAF, RC: " << result->rc
<< " RESULT: " << result->result << endl;
}
return result->rc;
}
STAFResultPtr logIt(const STAFString &type, const STAFString &name,
const STAFString &level, const STAFString &message)
{
static STAFString where("LOCAL");
static STAFString service("LOG");
STAFString request("LOG " + type + " LOGNAME " + name + " LEVEL " +
level + " MESSAGE " + STAFHandle::wrapData(message));
return gHandle->submit(where, service, request);
}