Software Testing Automation Framework (STAF) User's Guide
Version 2.6.11
18 Apr 2006
9.0 Generic Workload Processor
11.0 STAF V3.0 Migration Preparation
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.
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 conviently 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.16, "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 will be returned. Otherwise, the request will be sent to the newly added service.
A default serviceloader service (STAFDSLS) is shipped with STAF, and it can dynamically load the Log, Monitor, ResPool and Zip services. This service will automatically be configured in your STAF.cfg file.
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 Generic Workload Processer (see 9.0, "Generic Workload Processor"), which is capable of starting, stopping, and querying many kinds of workloads.
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 global variable pool that is common to all the processes on a given STAF Client. 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 global variable pool. However, the process may override this behavior when asking for the value of a variable.
The following global 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.19, "Variable (VAR) Service" for more information on setting and resolving variables.
Security in STAF is defined at the machine level. In other words, you grant access to machines as oppossed to userids. Access in STAF is granted by specifying a certain trust level for a machine, 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.
Note: The local machine is always at trust level 5 with respect to itself.
A basic description of each level follows
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.
Caution: If you use a STAF service that is written in REXX, it can have round trip codepage translation problems. All of STAF services currently provided are written in C++/Java so they do not have this problem.
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 {STAF/Config/CodePage}
By default, the first time STAF starts after installation, it will automatically register with IBM Austin. This is of particular importance, as keeping an accurate count of the number of users and systems using STAF helps to ensure the continued support of STAF, as well as, providing compelling evidence for other groups to adopt STAF. When installing STAF, you may optionally include your name, e-mail address, and organization. This allows us to send you information about updates to STAF, as well as allowing us to better understand which types of groups are benefitting from STAF. If you are installing large numbers of STAF systems, we don't expect you to continually enter this information. We would ask that you enter this information only once.
While STAF registration is enabled by default, all of the installers allow you to bypass this registration. Please see the installation section for your specific platform.
If you want to reinstall STAF or migrate to a newer version of STAF, you must uninstall STAF first and then perform an install. An uninstall of STAF will only remove the files that the STAF install created. Any files created after STAF was installed (e.g. additional services, log files, updated STAF.cfg, etc) will not be removed. The STAF.cfg file will be backed up to file STAF.cfg.ismp.bak by the STAF install (if you perform a InstallShield MultiPlatform install).
STAF provides the following two methods to install STAF on Windows. Both methods use MultiPlatform InstallShield:
java -jar STAF2611-setup-win32.jar
STAF2611-setup-win32
You will be guided through the following steps:
To uninstall STAF on Windows systems, open the Control Panel and double click on the "Add/Remove Programs" icon. Scroll down through the list of installed programs and select "STAF - Software Testing Automation Framework" and click on the "Add/Remove..." button. When uninstalling STAF 2.3 and later (when it was installed using InstallShield MultiPlatform), all STAF features will be uninstalled; you cannot choose which features to uninstall. Also, any files created after STAF was installed will not be removed.
Note that beginning with STAF 2.6.6, if you selected to place icons on the "Start Programs" menu during the installation, there will also be an "Uninstall STAF" icon in the program folder name you specified. You can also use this icon to uninstall STAF on Windows systems.
When uninstalling STAF 2.2 or earlier, when you click on the "Add/Remove..." button, a panel will be displayed asking whether you want to completely uninstall STAF or prepare for a reinstallation of STAF. The latter choice should be used if you are planning to reinstall STAF on this system. Select the option that you want and click Ok.
You must uninstall STAF before reinstalling STAF. Please see 3.2, "Reinstalling/Migrating" for more information.
If you need to install or uninstall the same STAF configuration multiple times or in multiple locations, you can bypass the ISMP Installer GUI and perform a silent installation or uninstallation to save time.
In a silent installation, STAF will be installed with the default options. To perform a silent installation on Windows, issue the following command:
STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept"or
java -Dis:debug=1 -jar STAF2611-setup-win32.jar -silent -W license.selection="Accept"
After performing a silent installation of STAF on Windows 95/98/ME systems, you must restart your system to complete the installation (e.g. sets environment variables for STAF).
You can also use a response file for the responses you normally specify manually when you run the ISMP Installer GUI. To create a response file, you can run a non-silent installation, specifying the response file name, and select the responses during the installation:
STAF2611-setup-win32 -options-record settings.txt
To specify a response file for a silent STAF installation, issue the following command:
STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept" -options settings.txt
You can also override installation settings when doing a silent installation. For example, to install STAF with the default options, except for specifying a different install location, issue the following command:
STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept" -W stafinstalldirectory.defaultInstallLocation="C:\tools\staf"
The following table shows the most commonly-used "-W" silent install options:
Table 1. -W silent install options
| Option | Default Value | Description |
|---|---|---|
| -W license.selection= | N/A | Specify the value "Accept" to indicate that you have read the STAF license agreement and that you accept the terms of the license agreement. You are required to use this option and set the value to "Accept". |
| -W stafinstalldirectory.defaultInstallLocation= | "C:\STAF" | The directory in which STAF should be installed. |
The silent uninstallation uninstalls all STAF components. To perform a silent uninstallation, issue the following command:
ProductDir/_uninst/uninstaller -silent
If you wish to have STAFProc start automatically on Windows when the operating system is rebooted (without requiring a user to log on to Windows), you can install STAF as a Windows service.
These instructions assume you have copied INSTSRV.EXE and SVRANY.EXE (available from the Windows Resource Kit) into C:\WINNT\SYSTEM32.
instsrv STAF c:\winnt\system32\srvany.exe
My Computer\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\STAF
Start > Programs > Administrative Tools > Services
Start > Programs > Administrative Tools > Management Console (Windows 2000 Terminal Server) Services and Applications > Services
Start > Settings > Control Panel > Administrative Tools > Services
net start staf
staf local ping ping
STAF provides the following two methods to install STAF on Unix using MultiPlatform InstallShield. All operating systems supported by STAF, except for Irix and AIX 4.3.2 or earlier, are supported by MultiPlatform InstallShield.
java -jar STAF2611-setup-xxxxx.jar
./STAF2611-setup-xxxxx.bin
You will be guided through the following steps:
If you need to install or uninstall the same STAF configuration multiple times or in multiple locations, you can bypass the ISMP Installer GUI and perform a silent installation or uninstallation to save time.
In a silent installation, STAF will be installed with the default options. To perform a silent installation on Unix, issue the following command (where xxxxx is the operating system, such as "linux", "aix", etc.):
STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept"or
java -Dis:debug=1 -jar STAF2611-setup-xxxxx.jar -silent -W license.selection="Accept"
After performing a silent installation of STAF, be sure to logout and login to complete the installation (e.g. sets environment variables for STAF).
You can also use a response file for the responses you normally specify manually when you run the ISMP Installer GUI. To create a response file, you can run a non-silent installation, specifying the response file name, and select the responses during the installation:
STAF2611-setup-xxxxx.bin -options-record settings.txt
To specify a response file for a silent STAF installation, issue the following command:
STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept" -options settings.txt
You can also override installation settings when doing a silent installation. For example, to install STAF with the default options, except for specifying a different install location, issue the following command:
STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept" -W stafinstalldirectory.defaultInstallLocation="/tools/staf"
The following table shows the most commonly-used "-W" silent install options:
Table 2. -W silent install options
| Option | Default Value | Description |
|---|---|---|
| -W license.selection= | N/A | Specify the value "Accept" to indicate that you have read the STAF license agreement and that you accept the terms of the license agreement. You are required to use this option and set the value to "Accept". |
| -W stafinstalldirectory.defaultInstallLocation= | "C:\STAF" | The directory in which STAF should be installed. |
The silent uninstallation uninstalls all STAF components. To perform a silent uninstallation, issue the following command:
ProductDir/_uninst/uninstaller.bin -silent
A single gzipped or compressed tar file is provided for Unix systems. For some platforms that are not supported by InstallShield MultiPlatform, such as Linux IA-64, Linux AMD-64, z/OS, AS/400, Irix, etc, this is the only install file provided. Before installing STAF, you will need to gunzip the gzipped tar file or uncompress the compressed tar file and then untar it into a temporary directory from which you will later run the STAFInst commmand. Note that when you untar the file, it will expand into a single directory named "staf" that will contain the installation files and directories.
For example, assuming you downloaded the gzipped tar file for Linux IA64 into a temporary directory named /tmp/STAF,
cd /tmp/STAF gunzip STAF2611-linux-ia64.tar.gz tar -xvf STAF2611-linux-ia64.tar cd staf
Or, for example, assuming you downloaded the compressed tar file for z/OS into a temporary directory named /tmp/STAF,
cd /tmp/STAF compress -d STAF2611-zos.tar.Z tar -xvf STAF2611-zos.tar cd staf
Note that you can delete this temporary directory (e.g. /tmp/STAF) after you have run the STAFInst command to install STAF to it's target directory.
Optionally, you may prefer to untar STAF on one system and mount the installable images from other systems.
Once the STAF installation image is ready, you should run the STAFInst command. The syntax is as follows.
Usage: STAFInst [-source <source path>] [-target <target path>]
[-bin <directory>] [-lib <directory>] [-preview]
[-type < m<s<o>> | r<s<o>> | f<s<o>> >] [-verbose] [-warn]
[-ro <mode>] [-rx <mode>] [-rw <mode>] [-dp <mode>]
[-noreg | [-name <name>] [-email <email>] [-org <org>]]
-source specifes the directory in which the STAF files were untar'd. In our example above, this would be /tmp/STAF. The default is the current directory. If you are not running STAFInst from the directory in which STAFInst resides, you must specify -source.
-target specifes where STAF will be installed. The default is /usr/local/staf.
-bin specifies the directory where softlinks to executables will be created. The default is /usr/bin.
-lib specifies the directory where softlinks to libraries will be created. The default is /usr/lib.
-type specifies the type of installation (the default is rs). Possible values are
Any of these options may be suffixed with 's' to indicate that appropriate softlinks should be created in the directories specified by the -bin and -lib options. You may further append 'o' to indicate that only softlinks should be created. That is, no files will be copied. This is useful when you simply wish to create softlinks to a remotely shared copy of STAF. Note, if you perform a softlink-only install, the STAFUninst script (see 3.4.6, "Starting STAF automatically during reboot") will still be created in the directory specified by -target.
-verbose specifies that all operations performed by STAFInst should be displayed to the user.
-warn specifies that STAFInst should stop execution if it encounters a warning condition. An example of a warning condition is trying to copy or link a non-existant file. Normally, these warning conditions are printed and execution continues.
-preview displays the intended actions of STAFInst without touching the file system.
-ro allows you to specify the mode bits for STAF files intended to be read-only. The default is 444.
-rx allows you to specify the mode bits for STAF files intended to be read-execute. The default is 555.
-rw allows you to specify the mode bits for STAF files intended to be read-write. The default is 664.
-dp allows you to specify the mode bits for the directories STAF creates. The default is 775.
-noreg prevents STAF from automatically registering with IBM Austin. This option is highly discouraged. Please see 3.1, "Registering STAF" for more information.
-name allows you to specify the name STAF uses when registering. The default is the empty string.
-email allows you to specify the e-mail address STAF uses when registering. The default is the empty string.
-org allows you to specify the organization STAF uses when registering. The default is the empty string.
IMPORTANT! In order to start STAF or to use STAF, you must make set some environment variables as described in section 3.9, "Environment Variable Settings". STAFInst does not update these environment variables for you.
It is recommended that you start STAFProc (see 5.1, "STAFProc") as root. This is to ensure that the Process and File System services will have full access to the system.
For the following examples, assume the STAF installation image is in /tmp/STAF and your current directory is also /tmp/STAF.
To take all the defaults, which will perform a recommended install of STAF into /usr/local/staf and create softlinks in /usr/bin and /usr/lib, you would simply enter
./STAFInst
To perform a recommended install of STAF into /usr/local/staf, but have the softlinks placed into usr/local/bin and /usr/local/lib, you would enter
./STAFInst -bin /usr/local/bin -lib /usr/local/lib
To perform a minimum installation of STAF into /opt/staf without any softlinks, you would enter
./STAFInst -target /opt/staf -type m
To perform a preview of a full STAF installation into the default /usr/local/staf with default softlinks in /usr/bin and /usr/lib, you would enter
./STAFInst -type fs -preview
To perform a default install of STAF and provide your name and e-mail address for registration, you would enter
./STAFInst -name "Your name" -email "Your e-mail address"
To install STAF in the default locations but change read-only permissions to 440, read-execute permissions to 550, read-write priveleges to 660, and directory permissions to 770, you would enter
./STAFInst -ro 440 -rw 550 -rw 660 -dp 770
When STAF is installed on Unix systems, a script called STAFUninst is created which can be used to uninstall STAF. This file is created in the directory where you installed STAF (default is /usr/local/staf). All STAF features will be uninstalled; you cannot choose which features to uninstall. However, only the files and softlinks that the STAF install created will be removed. Any files created after STAF was installed will not be removed.
If STAF was installed using InstallShield MultiPlatform, you will be prompted to logout to complete the uninstall.
You must uninstall STAF before reinstalling STAF. Please see 3.2, "Reinstalling/Migrating" for more information.
You can have STAF start automatically during reboot on Unix machines by using a script file similar to the following:
#!/bin/sh PATH=/usr/local/staf/bin:$PATH export PATH LD_LIBRARY_PATH=/usr/local/staf/lib export LD_LIBRARY_PATH CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar export CLASSPATH STAFCONVDIR=/usr/local/staf/codepage export STAFCONVDIR STAFCODEPAGE=LATIN_1 export STAFCODEPAGE nohup /usr/local/staf/bin/STAFProc > /usr/local/staf/stafproc.out
If you did not install STAF to the default directory (/usr/local/staf), then you would need to specify the non-default installation directory in the script file.
Note that on AIX, you need to replace LD_LIBRARY_PATH with LIBPATH, and on HP-UX, you need to replace LD_LIBRARY_PATH with SHLIB_PATH.
Note that if your Unix operating system does not support the "nohup" command, then remove it from the last line in the script:
/usr/local/staf/bin/STAFProc > /usr/local/staf/stafproc.out
The console output from STAFProc will be stored in the /usr/local/staf/stafproc.out file.
The usage of this script file varies depending on the specific Unix operating system:
You may get the following error message:
STAFProcess::processMonitorThread: error opening /dev/tty, errno: 6
However, STAFProc does start despite this message, and functions normally.
Note, when you are running STAF on Linux RedHat 9.0 or later, you may encounter a Segmentation Fault every time you execute the STAF executable. To work around this problem, set the following environment variable:
LD_ASSUME_KERNEL=<kernel-version>
The following versions can be specified for <kernel-version>
Note, if you plan to use Java services, or STAF-enabled Java applications with the 64-bit version of STAF for HP-UX IA64, you must use Java 1.4.1 or later. For more information see 4.4.3, "JSTAF service proxy library".
Note: STAF will only run on AS/400 V5R2 or newer.
SHELL "/QOpenSys/usr/bin/qsh -c %C"for PROCESS START requests, or change the default shell by adding the following line to your STAF.cfg file:
SET DEFAULTSHELL "/QOpenSys/usr/bin/qsh -c %C"
Note: STAF will only run on z/OS V1.4 or newer. STAF's Java support on z/OS requires JDK 1.4.1 or newer.
To install STAF on z/OS, you should follow the steps described in 3.4.3, "Installing Using STAFInst".
It is critical that you remember to make set the _CEE_RUNOPTS environment variable. Failure to set this variable will prevent STAF from working properly. The proper setting should be
_CEE_RUNOPTS="posix(on)"
If you did not install STAF in the default /usr/local/staf directory, STAFCONVDIR must be be set to the STAF codepage directory.
STAF requires setting some environment variables to run. If you performed an InstallShield install and selected an option to have the install update the environment variables, these environment variables should already be updated for STAF. Otherwise, you must set these environment variables yourself. In most cases, you'll probably want to set these environments for the system so that they are always set even after logging out or rebooting.
Please verify that the following environment variables have been set as follows before using STAF:
If you have a problem while installing STAF, please check the STAF V2 FAQ at http://staf.sourceforge.net/current2x/STAFFAQ.htm, particularly section 3.2 "STAF Install Questions" under section 3 "Debugging STAF".
If you have a problem starting STAFProc, please be sure that the necessary environment variables have been set for STAF (see section 3.9, "Environment Variable Settings"). Also, check the STAF V2 FAQ at http://staf.sourceforge.net/current2x/STAFFAQ.htm.
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 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 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 the name by which your machine is known by using the MACHINE configuration statement. This option is used in a disconnected mode.
Note: The MACHINE and INTERFACE configuration statements are mutually exclusive.
MACHINE <Name>
<Name> is the name you wish to use for your machine. It is case sensitive.
MACHINE Office
You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement.
Note: The MACHINE and INTERFACE configuration statements are mutually exclusive.
Note: Currently, the only supported network interface is TCP/IP.
INTERFACE TCPIP [Port]
[Port] is the TCP/IP port on which to listen for connections. The default is 6500. All machines in the same STAF Environment must use the same port.
INTERFACE TCPIP INTERFACE TCPIP 6600
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, this might be the name of the REXX script or Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See below for information regarding the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documentation provided by the service proxy library.
OPTION specifes 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 RXSTAF and JSTAF service proxy libraries. Otherwise, see the documation 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.
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 SAMPLER LIBRARY RXSTAF EXECUTE C:\STAF\bin\Sample.cmd PARMS "Sample Data"
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 STAFZip
The library RXSTAF acts as a proxy for STAF services implemented in the REXX language.
The EXECUTE option for a Rexx service should specify the full path to the Rexx script that implements the service.
RXSTAF supports the following OPTIONs:
DEBUG specifies that Rexx service code should be re-read for every service request, thus, allowing debugging without stopping STAFProc. If this option is not specified, the Rexx service code is read in once at initialization time and a tokenized image is created. This tokenized image is used for all service requests, and any changes to the Rexx service code will not be reflected until STAFProc is stopped and started again.
Warning: Using the DEBUG option will degrade the service's performance.
OPTION Debug
The library JSTAF acts as a proxy for STAF services implemented in the Java language. JSTAF works with Java 1.2 and above.
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.
Note: The HP-UX IA64 64-bit version of STAF requires Java 1.4.1 or later.
J2=<Java option> specifies an arbitrary Java option 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. Sun Java 1.4.0 vs IBM Java 1.3.1) 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/Config/STAFRoot}/data/JSTAF/<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.
OPTION J2=-verbose:gc
OPTION "J2=-cp {STAF/Config/BootDrive}/MyJava/Extra.jar{STAF/Config/Sep/Path}{STAF/Env/Classpath}"
OPTION J2=-Xms64m
OPTION J2=-Xmx128m
OPTION J2=-d64
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 128M, and wanted the Event and EventManager Java services to run in a different JVM, called MyJVM2, with a maximum heap size of 64M, 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=-Xmx128m
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/service/STAFEvent.jar \
OPTION JVMName=MyJVM2 OPTION J2=-Xmx64m
SERVICE EventManager LIBRARY JSTAF EXECUTE C:/STAF/services/EventManager.jar \
OPTION JVMName=MyJVM2
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 loader proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the REXX script or Java jar file which actually implements the service loader. This option has no significance for non-proxy service loader libraries. See the Service Registration section for information regarding the RXSTAF and JSTAF service proxy libraries.
OPTION specifes a configuration option that will be passed on to the service loader library / DLL. This is typically used by service loader 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 RXSTAF and JSTAF service proxy libraries. Otherwise, see the documation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the service loader during initialization.
SERVICELOADER LIBRARY STAFDSLS SERVICELOADER LIBRARY JSTAF EXECUTE C:\STAF\services\CustomServiceLoader.jar
STAFProc allows you to set various parameters which affect the general operation of STAF, such as the amount of time to wait for a successful connection to another system. The SET configuration statement lets you set these general operational parameters.
SET [CONNECTTIMEOUT <Number>] [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
[MAXFILES <Number>] [MAXQUEUESIZE <Number>]
[USELONGNAMES] [INITIALTHREADS <Number>] [THREADGROWTHDELTA <Number>]
[ENABLEDIAGS]
[DEFAULTSTOPUSING <Method>] [DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE]
[PROCESSAUTHMODE <Authentication Mode>]
[DEFAULTAUTHUSERNAME] [DEFAULTAUTHPASSWORD]
[DEFAULTAUTHDISABLEDACTION <Disabled Action>]
[DEFAULTSHELL <Shell>]
[DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
CONNECTTIMEOUT specifies the maximum time in milliseconds to wait for a connection attempt to a remote system to succeed. The default is 5000 (i.e., 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.
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.
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).
MAXFILES specifies the maximum number of files STAFProc may have open. The default is 500.
MAXQUEUESIZE specifies the maximum size of the queue associated with each process' handle. The default is 100.
USELONGNAMES specifies that STAF should use full TCP/IP host names instead of the host name minus the domain name. By default, STAF uses short names (the first portion of the TCP/IP hostname) to track machine requests, grant access, etc. This may not be desirable in situations where you are using multiple TCP/IP domains which have duplicate short names across them, for example, server1.austin.ibm.com and server1.test.austin.ibm.com. If USELONGNAMES is set, a machine's effective machine name will be the entire TCP/IP host name (e.g., automate.austin.ibm.com), otherwise, a machine's effective machine name will be the first portion of the TCP/IP host name (e.g., automate).
Note: Using long names can have implications for various external services. For example, the Log Service uses the effective machine name as part of the directory path when creating logs. This might result in a directory structure of C:\STAF\Logging\MACHINE\automate.austin.ibm.com\ which would require a file system which supports long names, such as HPFS.
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.
ENABLEDIAGS specifies to enable diagnostics. The default is to disable diagnostics.
Note: You may also enable (or disable) recording diagnostics dynamically using the DIAG service.
DEFAULTSTOPUSING allows you to specify the default method used to STOP processes. See 8.11.3, "STOP" for more information on available methods.
DEFAULTNEWCONSOLE specifies that processes should be STARTed in a new console window. This is the default for Win32 and OS/2. This option has no effect on Unix systems.
DEFAULTSAMECONSOLE specifies that processes should be STARTed in the same console as STAFProc. This is the default on Unix systems. This option has no effect on OS/2.
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.
DEFAULTAUTHUSERNAME specifies the username under which processes will be started, by default. Note, this option IS valid even if process authentication has been disabled.
DEFAULTAUTHPASSWORD specifies the password with which processes will be authenticated, by default. Note, this option IS valid even if process authentication has been disabled.
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 ben 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 NT/2000/XP/2003 systems is "cmd.exe /c". The default shell used for Windows 95/98/ME systems is "command.com /c".
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.
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.
A shell value can contain substitution characters described in the following table.
Table 3. Substitution Characters for Shells
| Substitution character | Description | Supported systems |
|---|---|---|
| %c | Substitute the values specified by the COMMAND and PARMS options. | Win32 and Unix |
| %C | Same as %c, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 and Unix |
| %p | Substitute the value specified by the PASSWORD option, or an empty string if no PASSWORD is provided. | Win32 and Unix |
| %P | Same as %p, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 and Unix |
| %t | Substitute the value specified by the TITLE option, or <Unknown> if no TITLE is provided. | Win32 and Unix |
| %T | Same as %t, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 and Unix |
| %u | Substitute the value specified by the USERNAME option, or an empty string if no USERNAME is provided. | Win32 and Unix |
| %U | Same as %u, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 and Unix |
| %w | Substitute the value specified by the WORKLOAD option, or <Unknown> if no WORKLOAD is provided. | Win32 and Unix |
| %W | Same as %w, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 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. | Win32 and Unix |
| %X | Same as %x, except the substituted value will be quoted (with all nested quotes properly escaped). | Win32 and Unix |
| %% | Substitute a %. | Win32 and Unix |
Notes:
SET CONNECTTIMEOUT 15000 SET CONNECTTIMEOUT 10000 CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2000 SET MAXFILES 1000 MAXQUEUESIZE 300 SET USELONGNAMES SET INITIALTHREADS 10 THREADGROWTHDELTA 3 SET ENABLEDIAGS SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE 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 global STAF variables at startup by using the VAR configuration statement.
VAR <Name=Value>
Name is the name of the variable.
Value is the value of the variable.
VAR WebServer=testsrv1.test.austin.ibm.com
VAR "Author=Jane Tester"
VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
You may grant access to machines by using the TRUST configuration statement.
Warning: Trust is granted based on the effective machine name. If using short names, be aware that machines with identical hostnames but in different domains (e.g. automate.austin.ibm.com and automate.raleigh.ibm.com) will be treated as one in the same. To ensure that machines from multiple domains with the same short name appear as separate machines, set USELONGNAMES via the SET configuration statement.
TRUST LEVEL <Level> <DEFAULT | MACHINE <Machine> [MACHINE <Machine>] ...>
LEVEL is the level of trust that you wish to grant, see 2.5, "Security" for a list of trust levels.
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.
If using short names:
TRUST LEVEL 3 MACHINE client1 MACHINE client2 MACHINE client3 TRUST LEVEL 5 MACHINE office TRUST LEVEL 0 MACHINE badguy TRUST DEFAULT LEVEL 1If using long names:
TRUST LEVEL 3 MACHINE client1.austin.ibm.com MACHINE client3.austin.ibm.com TRUST LEVEL 2 MACHINE client1.raleigh.ibm.com TRUST LEVEL 5 MACHINE office.austin.ibm.com TRUST LEVEL 0 MACHINE badguy.austin.ibm.com TRUST DEFAULT LEVEL 1
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.12, "Queue Service" for more information.
Note: You may also dynamically register for SHUTDOWN notifications via the SHUTDOWN service, see 8.17, "Shutdown Service".
Warning: In order for the receving 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 content of the message will be the string STAF/START.
ONSHUTDOWN indicates that a notification should be sent when STAF is shutdown. The content of the message will be the string STAF/SHUTDOWN.
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 STAF trace points as well as set the trace output destination and the services to be traced using the TRACE configuration statement.
Note: You may also interact with STAF tracing via the TRACE command of the MISC service, see 8.8.4, "TRACE".
TRACE ON [ServiceRequest] [ServiceResult] [ServiceError]
[ServiceAccessDenied] [ServiceManagement]
[Registration] [RemoteRequests] [Error]
[Warning] [Info] [Deprecated] [All]
TRACE TO <STDOUT | STDERR | FILE <Filename> >
TRACE [ALL] SERVICES [Service list]
See the TRACE command of the MISC service, section 8.8.4, "TRACE", for information on the above options.
TRACE TO STDOUT
TRACE TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc
TRACE ON ServiceResult
TRACE ON Error ServiceAccessDenied
TRACE SERVICES "Process Queue Var"
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
# ---------------------------------------------------------------------
INTERFACE TCPIP
SET USELONGNAMES CONNECTTIMEOUT 10000
# ---------------------------------------------------------------------
# STAF Log Mask Variable
# ---------------------------------------------------------------------
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 4 MACHINE test3.test.austin.ibm.com
TRUST LEVEL 5 MACHINE automate.austin.ibm.com
# ---------------------------------------------------------------------
# Delegated Services
# ---------------------------------------------------------------------
SERVICE pager DELEGATE globpager.test.austin.ibm.com
# ---------------------------------------------------------------------
# Rexx Services
# ---------------------------------------------------------------------
SERVICE doit LIBRARY RXSTAF Execute C:\STAF\services\doit.cmd
# ---------------------------------------------------------------------
# Java Services
# ---------------------------------------------------------------------
# Operating system independent name for my STAF services directory
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 TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc
TRACE ON ServiceAccessDenied Error
TRACE 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
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 Win32). 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.17, "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.
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 <Where> <Service> <Request>
<Where> is either LOCAL, if you wish to make a request of the local machine, or the name of the machine of which you wish to make a request.
<Service> is the name of the service to which you are submitting a request.
<Request> is the actual request string that you wish to submit to the service.
STAF local ping ping STAF testmach1 process query all STAF local sem event SynchSem post STAF local var global set "SomeName=Some text string"
Note: Take a closer look at the last example. Quotes are required around the value to the set option because the value contains spaces. When calling STAF APIs directly from testcases/applications, you should normally use the colon-length-colon delimited format described in 7.2, "Option Value Formats".
Note: Older versions of STAF (prior to V2.1.0) required extra effort when quoting things on the command line. If you should need to resort to the old command line handling algorithm, simply set the environment variable STAF_OLDCLI to any non-empty value.
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. 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.
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.5.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 throught the PROCESS service (see 8.11.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.cmd is a Rexx program that interfaces with STAF and allows you to submit STAF service requests from the command line.
Warning: This command is now deprecated. All command line STAF requests should be submitted through the STAF command. STAF.cmd is currently only available on a full install of STAF and may be removed from future versions of STAF.
CSTAF is an executable similar to STAF.cmd that allows you to submit STAF service requests from the command line.
Warning: This command is now deprecated. All command line STAF requests should be submitted through the STAF command. CSTAF is currently only available on a full install of STAF and may be removed from future versions of STAF.
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.
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 *processName, STAFHandle *handle)
processName points to the name by which you want this process 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 processName 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 is
STAF/RequestComplete <Request #>;<Request return code>;<Request result buffer>
for example, if you submitted the request "RESOLVE {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
STAF/RequestComplete 42;0;Win95
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 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 two primary classes to C++ programs. These class are
Addtionally, these classes use several other classes which are
STAF also provides some other miscellaneous C++ classes, which are
In addtion, 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 behaviour 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, and a result string, result.
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.
typedef STAFRefPtr<STAFResult> STAFResultPtr;
typedef STAFRefPtr<STAFHandle> STAFHandlePtr;
class STAFResult
{
public:
unsigned int rc;
STAFString result;
};
class STAFHandle
{
public:
static unsigned int create(const STAFString &name, STAFHandlePtr &handle);
static unsigned int 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);
static STAFString wrapData(const STAFString &data);
STAFHandle_t getHandle();
STAFHandle_t adoptHandle();
bool getDoUnreg();
void setDoUnreg(bool doUnreg);
~STAFHandle();
};
#include "STAF.h"
#include "STAF_iostream.h"
int main(void)
{
STAFHandle 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", "Event " +
STAFHandle::wrapData(semName) + " Post");
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;
}
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 processName[, handleVarName]
processName is the name by which you want this process 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 "MyProcess", "MyHandle" say "My handle is:" MyHandle
or
call STAFRegister "MyProcess" 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>]
<Mesasage> 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.
<Mesasage> 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
STAF externalizes five primary classes to Java applications. These classes are
These classes all reside in the com.ibm.staf package. In order to use them in a Java application, you must import the STAF package like so
import com.ibm.staf.*;
STAF externalizes two wrapper classes. These classes are
These classes all reside in the com.ibm.staf.wrapper package. In order to use them in a Java application, you must import the STAF wrapper package like so
import com.ibm.staf.wrapper.*;
The STAFHandle class is used to register, unregister, and submit service requests to STAF. Each Java application should create one and only one STAFHandle object. The act of creating this object registers the Java application with STAF using the name passed to the constructor. Once this is done, service requests may be submitted by one of two methods:
Before the Java application exits, it should unregister with STAF by calling the unRegister() method.
STAFHandle also defines the following constants which can be used as the syncOption parameter for the submit() and submit2() methods:
package com.ibm.staf;
public class STAFHandle
{
public static final int ReqSync = 0;
public static final int ReqFireAndForget = 1;
public static final int ReqQueue = 2;
public static final int ReqRetain = 3;
public static final int ReqQueueRetain = 4;
public STAFHandle(String processName) throws STAFException;
public STAFHandle(int staticHandleNumber)
public String submit(String where, String service, String request) throws STAFException;
public String submit(int syncOption, String where, String service, String request) throws STAFException;
public STAFResult submit2(String where, String service, String request);
public STAFResult submit2(int syncOption, String where, String service, String request);
public void unRegister() throws STAFException;
public int getHandle();
}
import com.ibm.staf.*;
public class STAFTest
{
public static void main(String argv[])
{
try
{
STAFHandle handle = new STAFHandle("MyApplication");
try
{
System.out.println("My handle is: " + handle.getHandle());
String result1 = handle.submit("LOCAL", "PING", "PING");
System.out.println("PING Result: " + result1);
String result2 = handle.submit(STAFHandle.ReqQueueRetain, "LOCAL", "PING", "PING");
System.out.println("PING Request number: " + result2);
STAFResult result3 = handle.submit2("LOCAL", "ECHO", "ECHO Hello");
System.out.println("ECHO Result: " + result3.result);
STAFResult result4 = handle.submit2(STAFHandle.ReqRetain, "LOCAL", "ECHO", "ECHO Hello");
System.out.println("Asynchronous ECHO Request number: " + result4.result);
STAFResult result = handle.submit2("local", "handle", "create handle name " + "MyStaticHandleName");
STAFHandle staticHandle;
if (result.rc == 0)
{
staticHandle = new STAFHandle(new Integer(result.result).intValue());
}
}
catch (STAFException e)
{
System.out.println("Error submitting request to STAF, RC: " + e.rc);
System.out.println(e.getMessage());
}
finally
{
handle.unRegister();
}
}
catch (STAFException e)
{
System.out.println("Error (un)registering with staf, RC:" + e.rc);
}
} // End of main()
} // End of STAFTest
The STAFException class is the exception class thrown by the STAFHandle class. It contains an rc variable which contains the actual return code from STAF. You may use the standard Throwable method getMessage() to retrieve any extra information provided by STAF.
package com.ibm.staf;
public class STAFException extends Exception
{
public STAFException();
public STAFException(int theRC);
public STAFException(int theRC, String s);
public int rc;
}
The STAFResult class is returned by the STAFHandle.submit2() method. It contains both the STAF return code as well as the result string. It is typically used in places where you wish to avoid catching exceptions when using STAF. This class also contains the constant definitions for all the STAF return codes. These return codes are common to STAFResult and STAFException.
package com.ibm.staf;
public class STAFResult
{
STAFResult();
STAFResult(int theRC);
STAFResult(int theRC, String theResult);
public int rc;
public String result;
public static final int Ok = 0;
public static final int InvalidAPI = 1;
public static final int UnknownService = 2;
public static final int InvalidHandle = 3;
public static final int HandleAlreadyExists = 4;
public static final int HandleDoesNotExist = 5;
public static final int UnknownError = 6;
public static final int InvalidRequestString = 7;
public static final int InvalidServiceResult = 8;
public static final int REXXError = 9;
public static final int BaseOSError = 10;
public static final int ProcessAlreadyComplete = 11;
public static final int ProcessNotComplete = 12;
public static final int VariableDoesNotExist = 13;
public static final int UnResolvableString = 14;
public static final int InvalidResolveString = 15;
public static final int NoPathToMachine = 16;
public static final int FileOpenError = 17;
public static final int FileReadError = 18;
public static final int FileWriteError = 19;
public static final int FileDeleteError = 20;
public static final int STAFNotRunning = 21;
public static final int CommunicationError = 22;
public static final int TrusteeDoesNotExist = 23;
public static final int InvalidTrustLevel = 24;
public static final int AccessDenied = 25;
public static final int STAFRegistrationError = 26;
public static final int ServiceConfigurationError = 27;
public static final int QueueFull = 28;
public static final int NoQueueElement = 29;
public static final int NotifieeDoesNotExist = 30;
public static final int InvalidAPILevel = 31;
public static final int ServiceNotUnregisterable = 32;
public static final int ServiceNotAvailable = 33;
public static final int SemaphoreDoesNotExist = 34;
public static final int NotSemaphoreOwner = 35;
public static final int SemaphoreHasPendingRequests = 36;
public static final int Timeout = 37;
public static final int JavaError = 38;
public static final int ConverterError = 39;
public static final int ServiceAlreadyExists = 40;
public static final int InvalidObject = 41;
public static final int InvalidParm = 42;
public static final int RequestNumberNotFound = 43;
public static final int InvalidAsynchOption = 44;
public static final int RequestNotComplete = 45;
public static final int ProcessAuthenticationDenied = 46;
public static final int InvalidValue = 47;
public static final int DoesNotExist = 48;
public static final int AlreadyExists = 49;
public static final int DirectoryNotEmpty = 50;
public static final int DirectoryCopyError = 51;
public static final int DiagnosticsNotEnabled = 52;
public static final int UserDefined = 4000;
}
The STAFQueueMessage class provides a wrapper around messages received via the STAF Queue service. It takes the received string as input and breaks it into its constituent parts.
package com.ibm.staf;
public class STAFQueueMessage
{
public STAFQueueMessage(String queueMessage);
public int priority;
public String timestamp;
public String machine;
public String handleName;
public int handle;
public String message;
}
The STAFUtil class contains utility functions provided by STAF. Currently, the only function provided is the static function wrapData() which is used to generate the length-delimited version of a string (see 7.2, "Option Value Formats") to be passed to STAF.
package com.ibm.staf;
public class STAFUtil
{
public static string wrapData(String data);
}
The STAFLog class provides a wrapper around the LOG command of the LOG service. It provides constants for the log type and log levels. It has instance and static methods for logging. The STAFLog class also interfaces with the MONITOR service. You may provide the STAFLog class a monitor mask. For the levels set in the monitor mask, STAFLog will log the message via the LOG service and then log the message via the MONITOR service. STAFLog will also log an error message to the MONITOR service, if it should receive an error while trying to log a message.
package com.ibm.staf.wrapper;
public class STAFLog
{
// Log type constants
public static final String GLOBAL = "GLOBAL";
public static final String MACHINE = "MACHINE";
public static final String HANDLE = "HANDLE";
// Log level constants (int format)
public static final int Fatal = 0x00000001;
public static final int Error = 0x00000002;
public static final int Warning = 0x00000004;
public static final int Info = 0x00000008;
public static final int Trace = 0x00000010;
public static final int Trace2 = 0x00000020;
public static final int Trace3 = 0x00000040;
public static final int Debug = 0x00000080;
public static final int Debug2 = 0x00000100;
public static final int Debug3 = 0x00000200;
public static final int Start = 0x00000400;
public static final int Stop = 0x00000800;
public static final int Pass = 0x00001000;
public static final int Fail = 0x00002000;
public static final int Status = 0x00004000;
public static final int Reserved1 = 0x00008000;
public static final int Reserved2 = 0x00010000;
public static final int Reserved3 = 0x00020000;
public static final int Reserved4 = 0x00040000;
public static final int Reserved5 = 0x00080000;
public static final int Reserved6 = 0x00100000;
public static final int Reserved7 = 0x00200000;
public static final int Reserved8 = 0x00400000;
public static final int Reserved9 = 0x00800000;
public static final int User1 = 0x01000000;
public static final int User2 = 0x02000000;
public static final int User3 = 0x04000000;
public static final int User4 = 0x08000000;
public static final int User5 = 0x10000000;
public static final int User6 = 0x20000000;
public static final int User7 = 0x40000000;
public static final int User8 = 0x80000000;
// Log level constants (String format)
public static final String FatalStr = "FATAL";
public static final String ErrorStr = "ERROR";
public static final String WarningStr = "WARNING";
public static final String InfoStr = "INFO";
public static final String TraceStr = "TRACE";
public static final String Trace2Str = "TRACE2";
public static final String Trace3Str = "TRACE3";
public static final String DebugStr = "DEBUG";
public static final String Debug2Str = "DEBUG2";
public static final String Debug3Str = "DEBUG3";
public static final String StartStr = "START";
public static final String StopStr = "STOP";
public static final String PassStr = "PASS";
public static final String FailStr = "FAIL";
public static final String StatusStr = "STATUS";
public static final String Reserved1Str = "RESERVED1";
public static final String Reserved2Str = "RESERVED2";
public static final String Reserved3Str = "RESERVED3";
public static final String Reserved4Str = "RESERVED4";
public static final String Reserved5Str = "RESERVED5";
public static final String Reserved6Str = "RESERVED6";
public static final String Reserved7Str = "RESERVED7";
public static final String Reserved8Str = "RESERVED8";
public static final String Reserved9Str = "RESERVED9";
public static final String User1Str = "USER1";
public static final String User2Str = "USER2";
public static final String User3Str = "USER3";
public static final String User4Str = "USER4";
public static final String User5Str = "USER5";
public static final String User6Str = "USER6";
public static final String User7Str = "USER7";
public static final String User8Str = "USER8";
// Constructors - Default monitor mask is 0x00007C07. This causes messages
// with log levels Fatal, Error, Warning, Start, Stop, Pass,
// Fail, and Status to also be logged via the MONITOR
// service
public STAFLog(String logType, String logName, STAFHandle handle);
public STAFLog(String logType, String logName, STAFHandle handle, int mask)
// Methods to actually log a message with a given level
public STAFResult log(int level, String msg)
public STAFResult log(String level, String msg)
public static STAFResult log(STAFHandle theHandle, String logType,
String logName, int level, String msg)
public static STAFResult log(STAFHandle theHandle, String logType,
String logName, String level, String msg)
public static STAFResult log(STAFHandle theHandle, String logType,
String logName, int level, String msg,
int mask)
public static STAFResult log(STAFHandle theHandle, String logType,
String logName, String level, String msg,
int mask)
// Accessor methods
public String getName();
public String getLogType();
public int getMonitorMask();
}
import com.ibm.staf.*;
import com.ibm.staf.wrapper.*;
...
...
// Create a log object that only logs Fatal and Error messages.
// myHandle is a STAFHandle object that was created earlier.
STAFLog logger = new STAFLog(STAFLog.GLOBAL, "MyLog", myHandle,
STAFLog.Fatal | STAFLog.Error);
STAFResult result;
// Log an error via the instance and static methods
result = logger.log(STAFLog.Error, "Error during test");
result = STAFLog.log(myHandle, STAFLog.GLOBAL, "MyLog", STAFLog.Error,
"Error during test");
// Set a mask to log Fatal, Error, Warning and Info messages.
// Then log a warning via a static method.
int myMask = STAFLog.Fatal | STAFLog.Error | STAFLog.Warning | STAFLog.Info;
result = STAFLog.log(myHandle, STAFLog.GLOBAL, "MyLog", STAFLog.Warning,
"This is just a warning", myMask);
The STAFMonitor class provides a wrapper around the LOG command of the MONITOR service. It has instance and static methods for logging messages to the MONITOR service.
package com.ibm.staf.wrapper;
public class STAFMonitor
{
// Constructor
STAFMonitor(STAFHandle stafHandle);
// Methods to log data to the MONITOR service
public STAFResult log(String message);
public static STAFResult log(STAFHandle theHandle, String message);
}
import com.ibm.staf.*;
import com.ibm.staf.wrapper.*;
...
...
// Create a monitor object. myHandle is a STAFHandle object that was created
// earlier.
STAFMonitor monitor = new STAFMonitor(myHandle);
STAFResult result;
// Log a message to the MONITOR service via the instance and static methods
result = monitor.log("Beginning phase 1");
result = STAFMonitor.log(myHandle, "Beginning phase 2");
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 appropiate when using the STAF command line. The third is most appropriate and easiest from within programs.
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.
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.
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.
Most services provide a HELP command that list basic service syntax information. The following internal services do not provide HELP due to their simplicity.
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 |
|---|---|
| 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 |
| LOG | Provides robust logging services |
| MISC | Handles miscellaneous commands. Also handles tracing. |
| 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 |
| 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 DELAY service is an internal STAF service. A DELAY request simply sleeps for a specified amount of time (in milliseconds) before returning to the calling program.
DELAY <milliseconds>
This command requires trust level 2.
All return codes from DELAY are documented in Appendix A, "API Return Codes".
Goal: Delay 3 seconds before returning from STAFProf.
DELAY 3000
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 may only be 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".
The result buffer will contain data based on the LIST command.
The result buffer for LIST (without specifying option TRIGGER, SOURCE, TRIGGERS, SOURCES, or SETTINGS) will contain a list of all unique trigger/source combinations and a count of how many times each was recorded in the following format:
From Timestamp : <yyyymmdd-hh:mm:ss> To Timestamp : <yyyymmdd-hh:mm:ss> Elapsed Time : <hh:mm:ss> Number of Triggers: <Number of Triggers> Number of Sources : <Number of Sources> <Count>;<Trigger>;<Source> ... ...
From Timestamp specifies the date/time that diagnostics were first enabled or last reset, or <N/A> if diagnostics have never been enabled.
To Timestamp specifies the date/time that diagnostics were disabled or, if still enabled, the current time.
Elapsed Time specifies the difference between the From Timestamp and the To Timestamp in hours, minutes, and seconds, or <N/A> if diagnostics have never been enabled.
Number of Triggers specifies the number of unique triggers that have been recorded.
Number of Sources specifies the number of unique sources that have been recorded.
Count specifies the number of times each trigger/source combination has been recorded.
The result buffer for LIST TRIGGERS will contain a list of all unique triggers that have been recorded.
From Timestamp : <yyyymmdd-hh:mm:ss> To Timestamp : <yyyymmdd-hh:mm:ss> Elapsed Time : <hhh:mm:ss> Number of Triggers: <Number of Triggers> <Count>;<Trigger> ... ...
Count specifies the number of times the trigger has been recorded.
The result buffer for LIST SOURCES will contain a list of all unique sources that have been recorded.
From Timestamp : <yyyymmdd-hh:mm:ss> To Timestamp : <yyyymmdd-hh:mm:ss> Elapsed Time : <hhh:mm:ss> Number of Sources : <Number of Sources> <Count>;<Source> ... ...
Count specifies the number of times the source has been recorded.
The result buffer for LIST TRIGGER <Trigger> will contain a list of all unique sources that have been recorded for the specified trigger.
From Timestamp : <yyyymmdd-hh:mm:ss> To Timestamp : <yyyymmdd-hh:mm:ss> Elapsed Time : <hhh:mm:ss> Trigger : <Specified Trigger> Number of Sources : <Number of Sources for Trigger> <Count>;<Source> ... ...
Count specifies the number of times the source has been recorded for the specified trigger.
The result buffer for LIST SOURCE <Source> will contain a list of all unique triggers that have been recorded for the specified source.
From Timestamp : <yyyymmdd-hh:mm:ss> To Timestamp : <yyyymmdd-hh:mm:ss> Elapsed Time : <hhh:mm:ss> Source : <Specified Source> Number of Triggers: <Number of Triggers for Source> <Count>;<Trigger> ... ...
Count specifies the number of times the trigger has been recorded for the specified source.
The result buffer for LIST SETTINGS will contain the current operational settings.
Diagnostics : <Enabled | Disabled> Last Reset / First Enabled: <yyyymmdd-hh:mm:ss> Last Disabled : <yyyymmdd-hh:mm:ss>
Diagnostics specifies if recording diagnostics is currently enabled or disabled.
Last Reset / First Enabled specifies the timestamp when diagnostics were last reset or first enabled or <N/A> if diagnostics have never been reset since STAF was started.
Last Disabled specifies the timestamp when diagnostics were last disabled or last cleared via the RESET command. It is initially set to the date/time when STAF was started.
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:29:08 Elapsed Time : 00:03:36 Number of Triggers: 3 Number of Sources : 9 17;STAX QUERY;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78 15;STAX QUERY;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98 14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100 14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80 10;LOG QUERY;STAX/Job/7;lucas.austin.ibm.com;77 10;LOG QUERY;STAX/Job/8;lucas.austin.ibm.com;97 4;PROCESS QUERY;STAX/Job/7;lucas.austin.ibm.com;77 4;PROCESS QUERY;STAX/Job/8;lucas.austin.ibm.com;97 3;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79 2;STAX QUERY;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10 1;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:32:53 Elapsed Time : 00:07:21 Number of Triggers: 3 Number of Sources : 9 10;LOG QUERY;STAX/Job/7;lucas.austin.ibm.com;77 10;LOG QUERY;STAX/Job/8;lucas.austin.ibm.com;97 4;PROCESS QUERY;STAX/Job/7;lucas.austin.ibm.com;77 4;PROCESS QUERY;STAX/Job/8;lucas.austin.ibm.com;97 3;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79 1;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99 14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100 14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80 2;STAX QUERY;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10 17;STAX QUERY;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78 15;STAX QUERY;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:35:03 Elapsed Time : 00:09:31 Number of Triggers: 3 20;LOG QUERY 8;PROCESS QUERY 66;STAX QUERY
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:36:03 Elapsed Time : 00:10:31 Number of Sources : 9 17;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78 15;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98 14;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100 14;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80 14;STAX/Job/7;lucas.austin.ibm.com;77 14;STAX/Job/8;lucas.austin.ibm.com;97 3;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79 2;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10 1;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:37:04 Elapsed Time : 00:11:32 Trigger : LOG QUERY Number of Sources : 2 10;STAX/Job/7;lucas.austin.ibm.com;77 10;STAX/Job/8;lucas.austin.ibm.com;97
From Date/Time : 20040212-18:25:32 To Date/Time : 20040212-18:39:01 Elapsed Time : 00:13:29 Source : STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98 Number of Triggers: 1 15;STAX QUERY
Diagnostics : Enabled Last Disabled : 20040212-18:25:32 Last Reset / First Enabled: 20040212-18:25:32
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 similiar 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 allow match patterns to be specified. These patterns recognize two special characters, '*' and '?'. '*' matches an string of characters (including an empty string). '?' matches any single character (the empty string does not match).
COPY FILE allows you to copy files between machines, as well as locally.
Note: A file copied via the FS services does not retain its system or extended attributes.
COPY FILE <FileName> [TOFILE <FileName>] [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. 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.
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. 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.4.4, "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.
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 issued locally from machine TestSrv1.
Goal: Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file c:\testcase\tc1.cmd on machine Client1
COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1
Goal: Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file d:\WebTests\webtc1.cmd on machine Client1. Don't overwrite the file if it exists.
COPY FILE c:\testcase\tc1.cmd TOFILE d:\WebTests\webtc1.cmd TOMACHINE Client1
FAILIFEXISTS
Goal: Copy text file test1.txt (in the directory specified by STAF variable TestcaseDir) from machine TestSrv1 to file test1.txt (in the directory specified by STAF variable TestcaseDir) on machine Client1. Convert any line-ending characters in the file to those appropriate for machine Client1, if machine Client1 has a different platform (e.g. Unix) than machine TestSrv1 (e.g. Windows). 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
Goal: Copy text file c:\tc\test1.txt from machine TestSrv1 to file c:\tc\test1.txt on machine Client1. Convert any line-ending characters in the file to a space.
COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " "
In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.
Goal: Retrieve file d:\WebTests\Logs\WebTC1.log from Client1 and store it in directory f:\Logs on machine TestSrv1.
COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log
Goal: Copy file d:\WebTests\Logs\WebTC1.log from Client1 to server LogSrv in directory h:\Logs.
COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE h:\Logs\WebTC1.log TOMACHINE LogSrv
Goal: Copy file d:\WebTests\Logs\WebTC1.log from Client1 to file c:\temp\tc1.log on machine Client1.
COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local
Goal: Copy the startup.cmd on the boot drive of Client1 to the boot drive of TestSrv1. Convert any line-ending characters of the text file as needed.
COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT
COPY DIRECTORY allows you to copy entire directories (including subdirectories if needed) between machines, as well as locally.
Note: A file copied via the FS services does not retain its system or extended attributes.
Note: The entries in COPY DIRECTORY are files and directories.
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. 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 '?'. 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 '?'. The default pattern is "*". This option will resolve variables.
Note: The COPY/LIST DIRECTORY commands recognize the "name" (NAME) portion of a filename as the character(s) that preceed 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.
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 '?'. This option will resolve variables.
FORMAT specifies the end-of-line character(s) to use. This option will resolve variables. See 8.4.4, "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 diretoreis 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.
This command requires trust level 4.
All return codes from COPY DIRECTORY are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty. If errors were encountered copying entries and IGNOREERRORS was not specified, the result buffer will be formatted like so
<Failure 1 full path name>;<Failure 1 return code>[:Failure 1 OS return code] <Failure 2 full path name>;<Failure 2 return code>[:Failure 2 OS return code] <Failure N full path name>;<Failure N return code>[:Failure N OS return code]
The OS return code will only be provided if the return code indicated a base operating system error occured (i.e., if RC == 10).
In the following examples, assume the command is being issued locally from machine TestSrv1.
Goal: Copy directory c:/testcase from machine TestSrv1 to directory c:/testcase on machine Client1
COPY DIRECTORY c:/testcase TOMACHINE Client1
Goal: Copy directory c:/testcase and its subdirectories from machine TestSrv1 to directory c:/testcase on machine Client1.
COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE
Goal: Copy directory c:/testcase from machine TestSrv1 to directory d:/WebTests on machine Client1. Don't overwrite the directory if it exists.
COPY DIRECTORY c:/testcase TODIRECTORY d:/WebTests TOMACHINE Client1 FAILIFEXISTS
Goal: Copy all files with an extension of "tmp" in directory c:/testcase to directory c:/testcase on machine Client1. Match the extension in a case insensitive manner. Do not recurse down subdirectories.
COPY DIRECTORY c:/testcase TOMACHINE Client1 EXT tmp CASEINSENSITIVE
Goal: Recursively copy all files under {MyTempDirectory} with a base name beginning with "test" to directory {MyTempDirectory} on machine Client1. Match the file names in a case sensitive manner. Do not report any errors during the copying. Don't create the directory if it does not exist on the target machine.
COPY DIRECTORY {MyTempFiles} TOMACHINE Client1 NAME "test*" CASESENSITIVE RECURSE IGNOREERRORS
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
Goal: Copy directory c:/testcase and its subdirectories, including empty subdirectories, from machine TestSrv1 to directory c:/testcase on machine Client1.
COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE KEEPEMPTYDIRECTORIES
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
Goal: Copy directory c:/testcase and its subdirectories from machine TestSrv1 to directory c:\testcase on machine Client1. However, do not copy any files.
COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE ONLYDIRECTORIES
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
Goal: Copy all files from machine TestSrv1 in directory c:/testcase whose name is 'web' to directory /testcase on machine Client1. Convert the line-ending characters in the files whose extensions are 'txt' or 'xml' (as they are considered to be text files) to the line-ending characters for machine Client1's platform. 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
Goal: Copy all .txt files from machine TestSrv1 in directory c:/testcase, and it's subdirectories, to directory /testcase on machine Client1. Convert the line-ending characters in all the files being copied (as they are considered to be text files) to the line-ending characters for machine Client1's platform. 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.
Goal: Retrieve all files in directory d:\WebTests\Logs from Client1 and store them in directory f:\Logs on machine TestSrv1. Do not copy its subdirectories.
COPY DIRECTORY d:/WebTests/Logs TODIRECTORY f:/Logs
Goal: Copy directory d:\WebTests\Logs and its non-empty subdirectories from Client1 to directory h:\Logs on server LogSrv.
COPY DIRECTORY d:/WebTests/Logs TODIRECTORY h:/Logs TOMACHINE LogSrv RECURSE
Goal: Copy directory d:\WebTests\Logs and its non-empty subdirectories from Client1 to directory h:\Logs on Client1.
COPY DIRECTORY d:/WebTests/Logs TODIRECTORY h:/Logs TOMACHINE local RECURSE
Goal: Copy all .cmd files in the root of the boot drive from Client 1 to the root of the boot drive of machine TestSrv1.
COPY DIRECTORY {STAF/Config/BootDrive}\ EXT cmd
GET FILE retrieves the contents of a file.
GET FILE <FileName> [[TEXT | BINARY] [FORMAT <Format>]]
FILE specifies the name of the 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".
On successful return, the result buffer will contain the contents of the specified file.
Goal: Retrieve the contents of the CONFIG.SYS file as text. Convert any line-ending characters to those of the platform of the machine making the request. Note that all of these GET FILE examples are equivalent.
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
Goal: Retrieve the contents of the STAF configuration file as text. Convert any line-ending characters in the file being retrieved to the line-ending characters for Unix.
GET FILE {STAF/Config/STAFRoot}/bin/STAF.cfg TEXT FORMAT Unix
Goal: In this example, assume the command is being issued to a Unix machine from a Windows machine. Retrieve the contents of file /testcases/test1.txt as text and convert the line-ending characters to the line-ending characters for Windows.
GET FILE /testcases/test1.txt TEXT FORMAT Windows
Goal: Retrieve the contents of file /testcases/test1.txt as text and convert the line-ending characters to a space.
GET FILE /testcases/test1.txt TEXT FORMAT " "
Goal: Retrieve the contents of file c:/testcases/test1.cmp in binary and display its contents in hex. Note that both of these GET FILE examples are equivalent.
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, or last modification time.
GET ENTRY <Name> <TYPE | SIZE | MODTIME>
ENTRY specifies the name of the file system entry for which to retrieve an attribute. This option will resolve variables.
TYPE specifies that the type of the file system entry should be retrieved.
SIZE specifies that the size of the file system entry should be retrieved.
MODTIME specifies that the last modification time of the file system entry should be retrieved.
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. If TYPE is specified, the result buffer
will contain one of the following letters
Table 5. File System Entry Types Reference
| Type identifier | Description |
|---|---|
| F | File |
| D | Directory |
| P | Pipe |
| S | Socket |
| L | Symbolic link |
| B | Block device |
| C | Character device |
| O | Other undefined type |
| ? | Unknown type |
If SIZE is specified, the result buffer will contain the 64-bit size of the file system entry in the format
<Upper 32-bit integer>:<Lower 32-bit integer>
If MODTIME is specified, the result buffer will contain the last modification time of the file system entry in the format YYYYMMDD-HH:MM:SS
Goal: Retrieve the type of the file system entry C:\Stuff\WhatIsIt.d
GET ENTRY C:\Stuff\WhatIsIt.d TYPE
Goal: Retrieve the size of the file system entry /var/log/messages
GET ENTRY /var/log/messages SIZE
Goal: Retrieve the last modification time of the file system entry {STAF/Config/BootDrive}\CONFIG.SYS
GET ENTRY {STAF/Config/BootDrive}\CONFIG.SYS MODTIME
QUERY retrieves all associated attributes of a file system entry.
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 will contain the file system entry attributes in the following format
Name : <Name> Type : <Type> Size : <Size> Modified: <Last Modification Time><Type>, <Size>, and <Last Modification Time> are formatted as specified in section 8.4.5, "GET ENTRY".
Goal: Retrieve the attributes for the file system entry /var/log/messages
QUERY ENTRY /var/log/messages
LIST retrieves the contents of a directory.
LIST DIRECTORY <Name> [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
[CASESENSITIVE | CASEINSENSITIVE] [LONG [FORMAT]]
DIRECTORY specifies the name of the directory to list. This option will resolve variables.
NAME specifies a pattern used to match the name of child entries. Only child entries whose name match this pattern will be returned. 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 returned. The default pattern is "*". This option will resolve variables.
Note: The COPY/LIST DIRECTORY commands recognize the "name" (NAME) portion of a filename as the character(s) that preceed 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.
TYPE specifies the types of child entries to return. These types are the same types described in section 8.4.5, "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.
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.
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.
LONG specifies that the list of child entries should include their name, type, size, and last modification time. By default the list only includes the name of the entry.
FORMAT specifies that the LONG listing should be formatted in a way that makes it easier to read by humans. The default LONG listing is formatted to make it easier to parse by an application.
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 the contents of the specified directory. If LONG was not specified, the format will be
<Name 1> <Name 2> <Name N>
If LONG was specified without FORMAT, the format will be
<Name 1>;<Type 1>;<Size 1>;<Last Modification Time 1> <Name 2>;<Type 2>;<Size 2>;<Last Modification Time 2> <Name N>;<Type N>;<Size N>;<Last Modification Time N>
If LONG and FORMAT were specified, the format will look like the following example
D 0 20010213-16:42:42 WINNT F 209K 19991207-12:00:00 ntldr F 34468 20010214-09:53:24 NTDETECT.COM F 512 20010213-16:44:22 bootsect.dos D 0 20010213-16:45:28 Documents and Settings D 0 20010213-16:45:58 Program Files D 0 20010522-11:23:56 Config.Msi F 0 20010214-09:22:44 CONFIG.SYS F 0 20010214-09:22:44 AUTOEXEC.BAT F 0 20010214-09:22:44 IO.SYS F 0 20010214-09:22:44 MSDOS.SYS D 0 20010214-09:32:38 Recycled D 0 20010214-09:41:18 drivers D 0 20010214-10:27:02 temp F 192 20010214-12:30:58 boot.ini D 0 20010215-08:36:12 Lotus D 0 20010215-08:40:00 NotesSQL F 170 20010215-13:58:44 setup.log F 384M 20010727-17:49:44 pagefile.sys D 0 20010424-14:23:06 sdwork
Note: When using FORMAT, the size listed will only include the lower 32-bits of the size. It will also use the extensions 'K' and 'M' to represent kilobytes and megabytes, respectively.
Goal: List the contents of the /tmp directory.
LIST DIRECTORY /tmp
Goal: List only files in the /tmp directory.
LIST DIRECTORY /tmp TYPE F
Goal: List all the entries in C:\Projects with an extension of "txt". Match this extension in a case sensitive manner.
LIST DIRECTORY C:\Projects EXT txt CASESENSITIVE
Goal: Produce a formatted listing of the C:\Projects directory sorted by size.
LIST DIRECTORY C:\Projects LONG FORMAT SORTBYSIZE
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 alread 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.
Goal: Create the directory /tmp/tests
CREATE DIRECTORY /tmp/tests
Goal: Create the directory {Tests/Root} and ensure that any intermediate parent directories are created as well.
CREATE DIRECTORY {Tests/Root} FULLPATH
Goal: Create the directory D:\TestData. Generate an error if the directory already exists.
CREATE DIRECTORY D:\TestData FAILIFEXISTS
DELETE deletes a file system entry.
DELETE ENTRY <Name> [CHILDREN [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[CASESENSITIVE | CASEINSENSITIVE]] [RECURSE] [IGNOREERRORS] CONFIRM
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. 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 extenision match this pattern will be deleted. The default pattern is "*". This option will resolve variables.
TYPE specifies the types of child entries to delete. These types are the same types described in section 8.4.5, "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".
On successful return, the result buffer will be empty. If errors were encountered and IGNOREERRORS was not specified, the result buffer will be formatted like so
<Failure 1 full path name>;<Failure 1 return code>[:Failure 1 OS return code] <Failure 2 full path name>;<Failure 2 return code>[:Failure 2 OS return code] <Failure N full path name>;<Failure N return code>[:Failure N OS return code]
The OS return code will only be provided if the return code indicated a base operating system error occured (i.e., if RC == 10).
Goal: Delete the entry /tmp/myfile.txt
DELETE ENTRY /tmp/myfile.txt CONFIRM
Goal: Delete the directory /tmp/myfiles and all of its children.
DELETE ENTRY /tmp/myfiles RECURSE CONFIRM
Goal: Recursively delete all the children of C:\TEMP, without deleting the directory itself.
DELETE ENTRY C:\TEMP CHILDREN RECURSE CONFIRM
Goal: Delete all entries with an extension of "tmp" in C:\MyFiles. Match the extension in a case insensitive manner. Do not recurse down subdirectories.
DELETE ENTRY C:\TEMP CHILDREN EXT tmp CASEINSENSITIVE CONFIRM
Goal: Recursively delete all files (and only files) under {MyTempFiles} with a base name beginning with "test". Match the name in a case sensitive manner. Do not report an errors during the deletion.
DELETE ENTRY {MyTempFiles} CHILDREN NAME "test*" RECURSE CASESENSITIVE IGNOREERRORS CONFIRM
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. you
CREATE HANDLE NAME <Handle Name>
NAME specifies the registered name of the handle.
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 CREATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the new handle number.
Goal: Create a static handle which will be registered with the name "Script Test"
CREATE HANDLE NAME "Script Test"
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.
Goal: Delete static handle number 42
DELETE HANDLE 42
QUERY will allow you to display various process' handles. You can query all the handles, only those with a given name, and further restrict the set by only including handles in a certain state.
QUERY [ALL | NAME <Handle Name>] [PENDING] [REGISTERED] [INPROCESS] [STATIC]
ALL will retrieve information about all the handles in use.
NAME specifies that you only want information on handles with the name <Handle Name>.
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.
If none of PENDING, REGISTERED, INPROCESS, or STATIC are specified, the default is REGISTERED, INPROCESS, and STATIC, otherwise, only those specified are shown.
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 will contain a listing of the handles, their registered names, their state, and the date and time of their last use. For example,
2 STAF_REXX_Monitor InProcess 19980216-08:45:45 17 <Unknown> Pending 19980216-10:24:13 42 WebTest1 Registered 19980216-11:23:36 63 WebTest2 Registered 19980216-11:39:57
Goal: Query all the REGISTERED and INPROCESS handles.
QUERY ALL
might result in the following
2 STAF_REXX_Monitor InProcess 19980216-08:45:45 5 STAF_REXX_Logging InProcess 19980216-08:45:55 30 STAF_REXX_Client Registered 19980216-10:03:29
Goal: Query only handles registered with the name WebTest1.
QUERY NAME WebTest1
might result in the following
42 WebTest1 Registered 19980216-11:23:36
Goal: Query all pending handles.
QUERY ALL PENDING
might result in the following
17 <Unknown> Pending 19980216-10:24:13 23 <Unknown> Pending 19980216-10:37:45
Note: Prior to version 2.2.0 of STAF, the Help service was an external Rexx service. That service is now obsolete and should no longer be used.
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.
Syntax: LIST ERRORS
Results:
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 OS 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 Machine
17 File Open Error
18 File Read Error
19 File Write Error
20 File Delete Error
21 STAF Not Running
22 Communication Error
23 Trustee Does Not Exist
24 Invalid Trust Level
25 Insufficient Trust Level
26 STAF 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 Semaphore Owner
36 Semaphore Has Pending Requests
37 Timeout
38 Java Error
39 Converter Error
40 Service already exists
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
..
4000+ Service specific errors
Syntax: LIST SERVICE Log ERRORS
Results:
4001 Invalid number (deprecated) 4002 Invalid date (deprecated) 4003 Invalid time (deprecated) 4004 Invalid level 4005 Invalid log directory (deprecated) 4006 Error creating directory (deprecated) 4007 Invalid file format 4008 Unable to purge all log records 4009 No remote log server defined (deprecated)
Syntax: LIST SERVICES
Results:
LOG MONITOR RESPOOL
[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.
Syntax: ERROR 22
Results:
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.
Syntax: ERROR 4007
Results:
LOG service: Invalid file format An invalid/unknown record format was encountered while reading the log file MONITOR service: Invalid file format (deprecated) An invalid/unknown record format was encountered while reading the monitor file
Syntax: SERVICE Log ERROR 4007
Results:
Invalid file format 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 is only valid when issued by local services.
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.
Syntax: UNREGISTER SERVICE Log ERROR 4008
All return codes from Help are documented in Appendix A, "API Return Codes".
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 OldReturnCodes
service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata"
The Log service accepts a parameter string in the following formats
[DIRECTORY <Log Directory Root>] [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>] [RESOLVEMESSAGE | NORESOLVEMESSAGE] [OLDRETURNCODES | NEWRETURNCODES] [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/Config/STAFRoot}/data/log.
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 0 which means there is no limit on the maximum number of records. 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.
OLDRETURNCODES specifies that the Log service should return the same error codes it always has. See 8.7.12, "Log Error Code Reference" for more information.
OLDRETURNCODES specifies that the Log service should return the old error codes used prior to STAF 2.1. See 8.7.12, "Log Error Code Reference" for more information.
NEWRETURNCODES specifies that the Log service should return the error codes newly defined in STAF 2.1. See 8.7.12, "Log Error Code Reference" for more information. 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.
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.7.10, "SET" for more information.
See 8.7.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.7.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.
RESOLVEMESSAGE causes the LOG service to call the STAF variable service to resolve any variables in the message before being written. This overrrides any other message resolution settings.
NORESOLVEMESSAGE causes the LOG service to not call the STAF variable service. This overrrides any other message resolution settings.
This command requires trust level 3.
All return codes from LOG are documented in 8.7.12, "Log Error Code Reference".
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 10.1, "Format Log Utility" for additional information.
QUERY <GLOBAL | [MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
[LEVELMASK <Mask>] [QMACHINE <Machine> [QHANDLE <Handle>] ]
[NAME <Name>] [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS]
[CONTAINS <String>]... [CSCONTAINS <String>]...
[LEVELBITSTRING] [FIELDSEP <Char>]
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
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. 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. This option will resolve variables.
QHANDLE selects only those records that are associated with a certain handle. This option will resolve variables.
NAME selects only those records with a certain registered name. 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.
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.
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.7.11, "Logging Levels Reference" for a complete list of logging levels.
FIELDSEP is the character that separates each record field, the default is "|". 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.
This command requires trust level 2.
All return codes from QUERY are documented in 8.7.12, "Log Error Code Reference".
The result buffer will contain data based on the QUERY command.
Note: 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.
Assume this example log file called STRESSTST contains the following records:
DATE TIME MACHINE H NAME LEVEL MESSAGE ----------------- -------- -- ------- ------- ---------------------------------- 19980210-18:04:00 automate 37 Test1A Start Stress Test 1A Initiated 19980210-19:37:15 automate 37 Test1A Trace Step 1: processing time: 01:31:26 19980210-19:39:09 automate 37 Test1A Debug Step 1: debug: files=23 threads=37 19980210-22:20:34 automate 37 Test1A Warning Step 2: File not ready, retry=3 19980210-22:21:01 automate 37 Test1A Info Step 2: File ready on retry 3 19980211-01:21:39 automate 37 Test1A Trace Step 2: processing time: 03:02:41 19980211-01:21:58 automate 37 Test1A Debug Step 2: debug: files=31 threads=54 19980210-01:37:25 crazy8s 41 Test2 Trace Step 1: processing time: 03:11:53 19980210-01:43:46 crazy8s 41 Test2 Debug Step 1: debug: files=43 threads=67 19980211-02:53:20 automate 37 Test1A Error Step 3: Sharing buffer exceeded 19980211-02:54:22 automate 37 Test1A User1 Step 3: Error recovery started 19980211-04:32:53 automate 37 Test1A User2 Step 3: Error recovery completed 19980211-04:33:49 automate 37 Test1A Trace Step 3: processing time: 03:10:41 19980211-04:34:07 automate 37 Test1A Debug Step 3: debug: files=78 threads=98 19980211-08:46:22 automate 37 Test1A Stop Stress Test 1A Completed 19980211-08:47:21 automate 37 Test1A Pass Stress Test 1A: Errors=1 Recover=1 19980211-08:48:46 automate 37 Test1A Status Step1=P, Step2=P, Step3=W, TC=P ----------------- -------- -- ------- ------- ----------------------------------
Note: The output for these examples are formated for ease of reading in this document, the actual format will vary depending on the field separator.
DATE TIME MACHINE H NAME LEVEL MESSAGE ----------------- -------- -- ------- ------- ---------------------------------- 19980210-19:37:15 automate 37 Test1A Trace Step 1: processing time: 01:31:26 19980210-19:39:09 automate 37 Test1A Debug Step 1: debug: files=23 threads=37 19980211-01:21:39 automate 37 Test1A Trace Step 2: processing time: 03:02:41 19980211-01:21:58 automate 37 Test1A Debug Step 2: debug: files=31 threads=54 19980210-01:37:25 crazy8s 41 Test2 Trace Step 1: processing time: 03:11:53 19980210-01:43:46 crazy8s 41 Test2 Debug Step 1: debug: files=43 threads=67 19980211-04:33:49 automate 37 Test1A Trace Step 3: processing time: 03:10:41 19980211-04:34:07 automate 37 Test1A Debug Step 3: debug: files=78 threads=98
DATE TIME MACHINE H NAME LEVEL MESSAGE ----------------- -------- -- ------- ------- ---------------------------------- 19980211-02:53:20 automate 37 STest1A Error Step 3: Sharing buffer exceeded
DATE TIME MACHINE H NAME LEVEL MESSAGE ----------------- -------- -- ------- ------- ---------------------------------- 19980210-19:37:15 automate 37 Test1A Trace Step 1: processing time: 01:31:26 19980210-19:39:09 automate 37 Test1A Debug Step 1: debug: files=23 threads=37 19980210-22:20:34 automate 37 Test1A Warning Step 2: File not ready, retry=3 19980210-22:21:01 automate 37 Test1A Info Step 2: File ready on retry 3 19980211-01:21:39 automate 37 Test1A Trace Step 2: processing time: 03:02:41 19980211-01:21:58 automate 37 Test1A Debug Step 2: debug: files=31 threads=54 19980211-02:53:20 automate 37 Test1A Error Step 3: Sharing buffer exceeded 19980211-02:54:22 automate 37 Test1A User1 Step 3: Error recovery started 19980211-04:32:53 automate 37 Test1A User2 Step 3: Error recovery completed 19980211-04:33:49 automate 37 Test1A Trace Step 3: processing time: 03:10:41 19980211-04:34:07 automate 37 Test1A Debug Step 3: debug: files=78 threads=98
DATE TIME MACHINE H NAME LEVEL MESSAGE ----------------- -------- -- ------- ------- ---------------------------------- 19980210-01:43:46 crazy8s 41 Test2 Debug Step 1: debug: files=43 threads=67 19980210-19:39:09 automate 37 Test1A Debug Step 1: debug: files=23 threads=37 19980211-01:21:58 automate 37 Test1A Debug Step 2: debug: files=31 threads=54 19980211-02:53:20 automate 37 Test1A Error Step 3: Sharing buffer exceeded 19980211-04:34:07 automate 37 Test1A Debug Step 3: debug: files=78 threads=98
Error=1 Warning=1 Info=1 Trace=4 Debug=4 Start=1 Stop=1 Pass=1 Status=1 User1=1 User2=1
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. 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.
All return codes from LIST are documented in 8.7.12, "Log Error Code Reference"
The result buffer will contain data based on the LIST command.
StressTST 19980210-14:17:00 Size=120823 Suite100 19980211-15:45:00 Size=2622
aquadyne automate
AutoGlob 19980210-10:54:00 Size=1168
42 43 44 45
HandLog1 19980210-10:54:00 Size=19043 HandLog2 19980211-18:23:00 Size=45264
Remote Logging : Disabled Directory : C:\STAF\data\log Max Record Size : 100000 Default Max Query Records: Resolve Message : Disabled Return codes : New 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. 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.
All return codes from DELETE are documented in 8.7.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
[LEVELMASK <Mask>] [QMACHINE <Machine> [QHANDLE <Handle>] ]
[NAME <Name>] [FIRST <Num> | LAST <Num>]
[CONTAINS <String>]... [CSCONTAINS <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
GLOBAL indicates you want to purge a global log.
MACHINE indicates you want to purge a machine log. 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.
Purge allows almost the same selection options as Query. See 8.13.9, "QUERY" for a list of valid purge selection options with the exception of LAST, TOTAL, STATS, LEVELBITSTRING and FIELDSEP not allowed.
Note: If your purge selection criteria selects every record in the log file, you will receive an error indicating you need to use DELETE.
This command requires trust level 4.
All return codes from PURGE are documented in 8.7.12, "Log Error Code Reference".
The result buffer will contain (number of records purged)/(total records).
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
[OLDRETURNCODES | NEWRETURNCODES]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
[RESOLVEMESSAGE | NORESOLVEMESSAGE]
See section 8.7.3, "Parameters" for a description of these options.
This command requires trust level 5.
All return codes from SET are documented in 8.7.12, "Log Error Code Reference".
The result buffer will contain a description of the new settings.
Max Record Size : 1024
Default Max Query Records: 100
Resolve Message : Enabled Return codes : New
Table 6. 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:
Note: Error codes 4001, 4002, 4003, 4005, 4006, and 4009 are now deprecated and
are no longer returned by the Log service. They are documented here for those
still using an older version of the Log service.
Table 7. Log Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4001 | Invalid number: <input> | An invalid number was specified, maybe for FIRST or LAST |
| 4002 | Invalid date: <input> | An invalid date format was specified, try YYYYMMDD, or MM/DD/YY |
| 4003 | Invalid time: <input> | An invalid time was specified, try HH:MM or HH:MM:SS |
| 4004 | Invalid level specified | An invalid logging level was specified, See 8.7.11, "Logging Levels Reference" for a complete list of logging levels. |
| 4005 | Unable to determine file location in configuration | The STAF/Service/<Name>/Directory variable in the STAF configuration is invalid. |
| 4006 | Error creating directory: <dir> | Unable to create the directories for the log files. |
| 4007 | Invalid file format | Error reading the log data due to an error in the file format. |
| 4008 | Failed attempting to purge all records, use DELETE | Your purge criteria selected every record to be purged from a log file. Use DELETE if you really want to delete every record or modify your purge criteria. |
| 4009 | No Remote Log Server Defined | Remote Log could not find the STAF/Service/<Name>/LogServer variable definition in the STAF configuration file. This variable defines where the ultimate log server resides (e.g. fa1c.test.austin.ibm.com). |
| 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.
Given the long name of a machine (e.g. fa2a.test.austin.ibm.com), returns either the long or short name (STAF configuration dependent). This command is primarily used by other services (such as RLog).
MACHINE <LongName>
This command requires trust level 1.
All return codes from MACHINE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain either the short or long name of the machine
Goal: Return the appropriate machine name.
MACHINE fa2a.test.austin.ibm.com
might result in the following
fa2a
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.
Goal: Display the version of STAF running.
VERSION
might result in the following
2.2.0
TRACE allows you to interact with STAF tracing. You may enable or disable various STAF trace points, change the trace output destination, and list the current trace output destination and enable trace points.
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>
<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 below.
<Message> is the actual trace message.
For example,
19980512-16:20:50;1;00000010;Service HELP: Initializing
Table 8. Trace point hexadecimal representation
| Hex | Trace point |
|---|---|
| 00000001 | Service Request |
| 00000002 | Service Result |
| 00000004 | Service Error |
| 00000008 | Service Access Denied |
| 00000010 | Service Management |
| 00000020 | Remote Requests |
| 00000100 | Error |
| 00000200 | Registration |
| 00000400 | Warning |
| 00000800 | Info |
| 00001000 | Deprecated |
TRACE <ON | OFF> [ServiceRequest] [ServiceResult] [ServiceError]
[ServiceAccessDenied] [ServiceManagement]
[Registration] [RemoteRequests]
[Error] [Warning] [Info] [Deprecated] [All]
TRACE TO <STDOUT | STDERR | FILE <Filename> >
TRACE [ALL] SERVICES [Service list]
TRACE LIST
ON indicates that you wish to enable certain trace points.
OFF indicates that you wish to disable certain trace points.
ServiceRequest indicates the trace point which causes a trace message to be generated for every incoming service request before it is processed by the service.
ServiceResult indicates the trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. This option overrides the ServiceError and ServiceAccessDenied options.
ServiceError indicates the trace point which causes a trace message to be generated for every incoming service request which results in a non-zero error code. This option overrides the ServiceAccessDenied option.
ServiceAccessDenied indicates 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.
ServiceManagement indicates the trace point which causes a trace message to be generated for service management operations such as service initialization and termination.
Registration indicates the trace point which causes a trace message to be generated for every registration or unregistration done by a process.
RemoteRequests indicates the trace point which enables trace message to be generated for requests destined for other machines.
Error indicates the trace point which causes a trace message to be generated for error conditions that STAF detects, such as broken communication connections and fatal REXX Service errors. The Error trace point is turned on by default.
Warning indicates the trace point which causes a trace message to be generated for warning conditions that STAF detects.
Info indicates the trace point which causes a trace message to be generated for information conditions that STAF detects.
Deprecated indicates 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.
All indicates all the aforementioned trace points.
STDOUT indicates that trace messages should be sent to the standard output device (stdout).
STDERR indicates that trace messages should be sent to the standard error device (stderr).
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.
SERVICES indicates which services should be enabled for tracing. The default is all services.
ALL indicates that tracing should be enabled for all services.
LIST indicates that you wish to see the current trace output destination as well as a list of the enabled trace points and services.
TRACE LIST requires trust level 2. All other TRACE command require trust level 5.
All return codes from TRACE are documented in Appendix A, "API Return Codes".
For TRACE LIST the result buffer will contain data formatted as follows.
Tracing to: STDOUT Trace points enabled: ServiceAccessDenied Error Deprecated Services to trace: PROCESS VAR
where Tracing to: indicates the current trace output destination, and there will be one line per enabled trace point following Trace points enabled: or None will be displayed if no trace points are enabled, and there will be one line per enabled service following Services to trace: or All will be displayed if tracing is enabled for all services..
For all other TRACE commands the result buffer will be empty on successful return.
Syntax: TRACE TO STDERR
Syntax: TRACE TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc
Syntax: TRACE ON ServiceRequest ServiceManagement
Syntax: TRACE OFF ServiceResult Error
Syntax: TRACE OFF All
Syntax: TRACE ON RemoteRequests
Syntax: TRACE ON Error Warning Info Deprecated
Syntax: TRACE SERVICES "PROCESS QUEUE"
Syntax: TRACE ALL SERVICES
Syntax: TRACE LIST
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 OLDRETURNCODES"
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> [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.
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 MONITOR are documented in 8.9.9, "Monitor Error Code Reference".
The result buffer will contain no data on return from a LOG command.
QUERY MACHINE <Machine> HANDLE <Handle>
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.
This command requires trust level 2.
All return codes from QUERY are documented in 8.9.9, "Monitor Error Code Reference".
The result buffer will contain data based on the QUERY command.
19980210-19:37:15 Testcase aborted with error "255"
LIST MACHINES | MACHINE <Machine> | SETTINGS
MACHINES indicates you want list all the machine names that have created monitor data.
MACHINE indicates you want to list the monitor data for the specified machine. This option will resolve variables.
SETTINGS returns the Monitor settings.
This command requires trust level 2.
All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".
The result buffer will contain data based on the LIST command.
aquadyne automate
6........................ 19980922-02:17:00 Size=43 21....................... 19980930-15:08:00 Size=148 45....................... 19981001-18:38:00 Size=41
Max Record Size : 512 Resolve Message : Enabled Return codes : New Resolve Message Var: Disabled
DELETE [BEFORE <Timestamp>] CONFIRM
BEFORE specifies that you only want to delete monitor data recorded prior to the specified timestamp. If BEFORE is not specified, all monitor data will be removed. The keyword TODAY can be used for <Timestamp> to delete all data prior to the current system date.
CONFIRM confirms you really want to delete the monitor data.
This command requires trust level 4.
All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".
The result buffer will contain no data on return from a DELETE command.
SET [RESOLVEMESSAGE | NORESOLVEMESSAGE]
[OLDRETURNCODES | NEWRETURNCODES] [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.
OLDRETURNCODES specifies that the MONITOR service should return the old error codes used prior to STAF 2.1. See 8.9.9, "Monitor Error Code Reference" for more information.
NEWRETURNCODES specifies that the MONITOR service should return the error codes newly defined in STAF 2.1. See 8.9.9, "Monitor Error Code Reference" for more information. 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 MONITOR are documented in 8.9.9, "Monitor Error Code Reference".
The result buffer will contain the option requested to be set.
Resolve Message : Enabled
Max Record Size : 512 Return codes : Old
In addition to STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Monitor return codes are defined:
Note: Error codes 4005, 4006, and 4007 are now deprecated and are no longer
returned by the Monitor service. They are documented here for those still
using an older version of the Monitor service.
Table 9. Monitor Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4005 | Unknown/invalid drive specified | The STAF/Service/<Name>/Directory variable in the STAF configuration file is invalid. Insure a valid drive and path is specified. |
| 4006 | Error creating directory | Unable to create the directories for the monitor files. Insure a valid drive and path is specified. |
| 4007 | Invalid file format | Error reading the monitor message due to an error in the file format |
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
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.
Goal: See if STAFProc is running on a given machine.
PING
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 [<Timeout>] | ASYNC]
[STOPUSING <Method>] [NEWCONSOLE | SAMECONSOLE]
[USERNAME <User name> [PASSWORD <Password>]]
[DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STATICHANDLENAME <Name>]
[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.
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.
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 OS/2, they need to be started through a command processor, such as cmd.exe. On Win32 systems, they need to be started through REXX.EXE. This option will resolve variables.
PARMS specifies any parameters that you wish to pass to the command. This option will resolve variables.
SHELL specifies that COMMAND should be started via a separate shell. Using a separate shell allows complex commands involving pipelines to be readily executed. 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. Note that on Windows 95/98/Me, when a process is started with the SHELL option, the process's return code will always be zero, even if the process ended with a non-zero return code. On Windows NT/2000/XP/2003, the actual return code of the process will be returned. You may specify an optional shell, which overrides any defaults specified in the STAF configuration file. See 4.6, "Operational parameters" for more information on how to specify the shell. This option will resolve variables.
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.
WAIT specifies that the START command should not return until the process has finished executing. You may specify an optional timeout, in milliseconds, after which the submit call should return. By default, the submit call will block indefinitely. 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.
ASYNC specifies that the process should be started asynchronously, and that the START command should return to the caller as soon as the processes 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.
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, the global variable pool should then 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.11.3, "STOP" for more information. This option will resolve variables.
NEWCONSOLE specifies that the process should get a new console window. This option only has effect on Win32. This is the default for Win32 and OS/2 systems.
SAMECONSOLE specifies that the process should share the STAFProc console. This option only has effect on Win32. This is the default for Unix systems.
USERNAME specifies the username under which the process should be started.
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.6, "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.
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.
STDIN specifies the name of the file from which standard input will be read.
STDOUT specifies the name of the file to which standard output will be redirected. If the file already exists, it will be replaced.
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.
STDERR specifies the name of the file to which standard error will be redirected. If the file already exists, it will be replaced.
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.
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.
NOTIFY ONEND specifies that you wish to send a notification when this process ends. See 8.11.6, "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.
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.
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.
Note: On Win32 systems, if you are redirecting stdin/out/err and are not using SAMECONSOLE, it is recommended that you redirect all three input/output streams. If you any one or two streams are redirected, but not all three, the non-redirected streams will not be available to the application. For example, if stdout and stderr are redirected, but not stdin, then the application will receive errors if it tries to read from standard input. As another example, if stdin and stdout are redirected, but not stderr, then you will not see any of the standard error output displayed in the console window. This problem only occurs when using NEWCONSOLE, which is the default. You may freely redirect any combination of stdin, stdout, and stderr when using SAMECONSOLE. This problem is due to a known limitation in the Win32 API.
This command requires trust level 5.
All return codes from START are documented in Appendix A, "API Return Codes".
If WAIT was specified and the submit call did not timeout, the result buffer will contain the return code from the process, the KEY (if one was specified with the NOTIFY ONEND option), as well as any files specified by RETURNSTDOUT, RETURNSTDERR, RETURNFILE. The format of the result buffer in this case will look like the following.
<Process return code>[;KEY=key][;<# of files returned>;{<File N return code>:<File N length>:<File N data>}]
Files we be returned in the order of standard output, then standard error, then any files specified with RETURNFILE. The <File N return code> is a standard STAF return code indicating the success or failure of retrieving the file's contents. As an example, assume that the standard output of a process was simply "a", and that the standard error of a process was simply "b", and that you asked for both of these to be returned. The STAF result buffer would look like the following.
0;2;0:1:a0:1:b
If WAIT was specified but the submit call did timeout, the result buffer will contain the handle of the started process. Note, you will also receive a Timeout error code in this case.
If ASYNC was specified, or defaulted to, the result buffer will contain the handle of the started process.
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 -------- 0The result buffer contains the return code from running the "java -version" 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 -------- 0;1;0:157: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 the results from running the "java -version" command, including a return code of 0 and the number of files returned by the process, which in this case is 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 :Length: format. 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 --------------- 2The 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 the actual base operating system error code, 2, is returned 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
C:\>STAF client1 PROCESS START COMMAND "java -cp C:/tests TestA" WAIT RETURNSTDOUT RETURNSTDERR Response -------- 0;2;0:20:SUCCESS. Yippee!!! 0:0:The result buffer contains the results from running the java testcase, including a return code of 0 and the number of files returned which is 2. The first file returned is stdout and it contains "SUCCESS. Yippee!!!\n" and it's contents are shown in :Length: format. The second file returned is stderr and it contains nothing.
The following examples show the goal and the syntax of the request to submit to the PROCESS service but not the results.
START COMMAND tc1.exe TITLE "Testcase 1" WORKDIR d:/testcase ENV RUNMODE=Type1
START COMMAND tc2 WORKDIR d:\webtests VAR WebServer=testsrv1.test.austin.ibm.com WORKLOAD "Web Tests" WAIT
START COMMAND {WWWTestDir}/www1.exe WORKDIR {WWWTestDir} WAIT 120000
START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND
START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND PRIORITY 1
MACHINE EventController NAME ProcessHandler KEY 9bt1az54fq
START COMMAND tc2.exe WORKDIR c:/testcase STOPUSING SIGINT
START COMMAND tc2.exe WORKDIR c:/testcase SAMECONSOLE
START COMMAND tc2 WORKDIR /testcases USERNAME testuser PASSWORD tupass
START COMMAND tc2 WORKDIR /testcase STDOUT /testcases/tc2/stdout.txt
START COMMAND tc3.sh STATICHANDLENAME "Test case 3"
START SHELL COMMAND "ps | grep test | wc >testcount.txt"
START SHELL COMMAND "grep 'Count = ' /tests/out | awk '^{print $5}'" STDOUT=/tests/awk.out STDERRTOSTDOUT
START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT
START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT WAIT RETURNSTDOUT
RETURNFILE /tmp/tc3.results
START COMMAND tc3.sh STDERRTOSTDOUT WAIT RETURNSTDOUT
START SHELL "D:/Cygwin/bin/bash.exe -c %C" COMMAND "D:/tests/test1.sh machA" WORKDIR D:/tests
START SHELL "xterm -title %T -e /bin/sh -c %X" COMMAND "/tests/test1.sh machA"
TITLE "Test 1" STDOUT /tests/test1.out
START SHELL "/bin/csh -c %C" COMMAND "/tests/test1.sh machA" WORKDIR /tests
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 result 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 Misc 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 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 START. 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.
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".
When stopping ALL or a WORKLOAD, the result buffer will contain two numbers separated by a space. First, the number of processes actually stopped. Second, the total number of processes, if ALL was specified, or the number of processes in the workload, if WORKLOAD was specified. These two numbers will be different if some of the processes have already been stopped or have completed execution. For example, if the result buffer contained "2 3" after stopping all processes, it would indicated that one process had already been stopped or had completed execution on its own.
When stopping a specific handle, the result buffer will be empty.
Goal: Stop process with handle 42.
STOP HANDLE 42
Goal: Stop all processes in the Web Tests workload.
STOP WORKLOAD "Web Tests"
Goal: Stop all processes currently running via STAF.
STOP ALL CONFIRM
Goal: Gracefully stop process with handle 113 using the SIGTERM method.
STOP HANDLE 113 USING SIGTERM
Goal: Unconditionally stop process with handle 17.
STOP HANDLE 17 USING SIGKILL
QUERY allows you to obtain information about all of the processes started via STAF, only those processes associated with a certain workload, or only information about a particular process. You may get information about any process started in WAIT mode that is still running and about any process started in ASYNC mode that has not yet been freed.
QUERY <ALL | WORKLOAD <Name> | HANDLE <Handle>>
ALL specifies that you want information for all current processes.
WORKLOAD specifies that you want information for all processes that are part of a given workload.
HANDLE specifies that you only want information for the specified handle.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
When specifying ALL or WORKLOAD, the result buffer will contain information formatted like this
Handle WorkLoad Command Status
------- ------------ ------------ ---------------------------------------------
43 Web Tests cmd.exe Running since 19980215-14:51:23
56 <Unknown> tc1.exe Completed at 19980215-14:59:37 RC: 3
If the process was started with no workload name, the workload column will display <Unknown>.
If a specific handle was queried, the result buffer will contain information formatted like this
Handle : 3 Name : Workload : Shell : <No Shell> Command : TestA.exe Parms : WorkDir : D:/Tests Start Mode: Async Start Date: 19980215 Start Time: 14:51:23 End Date : 19980215 End Time : 14:59:37 RC : 0
The End Date, End Time, and RC fields will only be filled in if the process has been stopped or run to completion.
Goal: Query the process with handle 42.
QUERY HANDLE 42
Goal: Query all the processes in the Web Tests workload.
QUERY WORKLOAD "Web Tests"
Goal: Query all processes in STAF.
QUERY ALL
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.
HANDLE specifies that only the termination information for the specified handle should be freed.
This command requires trust level 4.
All return codes from FREE are documented in Appendix A, "API Return Codes".
When specifying ALL or a WORKLOAD, the result buffer will contain two numbers separated by a space. First, the number of processes for which termination information was actually freed. Second, the total number of processes, if ALL was specified, or the number of processes in the workload, if WORKLOAD was specified. These two numbers will be different if some of the processes have not yet been stopped or have not completed execution. For example, if the result buffer contained "2 3" after freeing all termination information, it would indicated that one process had not yet been stopped or had not completed execution on its own.
When freeing the termination information for a specific handle, the result buffer will be empty.
Goal: Free the termination information for process with handle 42.
FREE HANDLE 42
Goal: Free the termination information for all the processes in the "Web Tests" workload.
FREE WORKLOAD "Web Tests"
Goal: Free the termination information for all stopped processes in STAF.
FREE ALL
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 content of the message will be of the format STAF/PROCESS/END <Handle>;<Timestamp>;<Return Code>[;<Returned file data>]. For example, STAF/PROCESS/END 43;19980427-15:13:26;0. The <Returned file data> is provided if any of RETURNSTDOUT, RETURNSTDERR, or RETURNFILE were specified when the process was started. The format of this data is discussed in the "Results" section of the START command.
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.
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 1 notification when the process with handle 14 ends.
NOTIFY REGISTER ONENDOFHANDLE 14 PRIORITY 1
Goal: Register to have a process end notification sent to all processes with registered name ProcessHandler on machine EventController when process with handle 43 ends.
NOTIFY REGISTER ONENDOFHANDLE 43 MACHINE EventController NAME ProcessHandler
Goal: Unregister the event notification for handle 43 which is to be sent when process with handle 12 ends.
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 list of all the registered notifiees. Each entry will either have the format <Priority>:<Machine>:NAME:<Name> or <Priority>:<Machine>:HANDLE:<Handle>, depending on whether the particular notifiee is to be notified by name or handle. For example,
5:EventController:NAME:ProcessHandler 1:Client2:HANDLE:23
Goal: Retrieve the list of process end notifiees for the process with handle 57.
NOTIFY LIST ONENDOFHANDLE 57
The QUEUE service is one of the internal STAF services. It provides the following commands
QUEUE allows you to queue a message to a given process handle or to any process registered with a given name.
QUEUE [HANDLE <Handle> | NAME <Name>] [PRIORITY <Priority>] MESSAGE <Message>
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.
MESSAGE specifies the message to be queued. This option will not resolve variables.
This command requires trust level 3.
All return codes from QUEUE are documented in Appendix A, "API Return Codes".
If HANDLE was specified, or defaulted to, the result buffer will contain no data upon return from the submit call.
If NAME was specified, the result buffer will contain the number of processes to which the message was queued.
Goal: Queue the priority 3 message "Hello World" to yourself.
QUEUE PRIORITY 3 MESSAGE "Hello World"
Goal: Queue the priority 1 message CONTROL/STAGE2 to all processes with registered name EventController.
QUEUE NAME EventController PRIORITY 1 MESSAGE CONTROL/STAGE2
Goal: Queue the message Ok to handle 17 using default priority 5.
QUEUE HANDLE 17 MESSAGE Ok
GET allows you to retrieve and remove an element from the queue. PEEK will retrieve an element from the queue without removing it from the queue.
GET [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [CONTAINS <String>]... [ICONTAINS <String>]... [WAIT [Timeout] ]
PEEK [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [CONTAINS <String>]... [ICONTAINS <String>]... [WAIT [Timeout] ]
PRIORITY specifies that you want to retrieve/remove a message 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 a message originating from the given machine. The default is any machine. You may specify this option multiple times. This option will resolve variables.
NAME specifies that you want to retrieve/remove a message 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 retrieve/remove a message 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.
CONTAINS specifies that you want to retrieve/remove a message 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 a message 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.
WAIT specifies that the submit call should not return until an appropriate message is available. You may specify an optional timeout, in milliseconds, after which the submit call should return. If no timeout is specified, the call will block indefinitely. This option will resolve variables.
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".
On successful return, the result buffer will contain the desired message in the following format
<Priority>;<Timestamp>;<Machine>;<Name>;<Handle>;<Message>
For example,
3;19980416-13:56:10;Client2;STAF_Process;1;STAF/START
Goal: Wait for, retrieve, and remove the highest priority message in the queue.
GET WAIT
Goal: Wait for and retrieve, but do not remove, the highest priority message from machine Server1.
PEEK WAIT MACHINE Server1
Goal: Wait for, retrieve, and remove the highest priority message containing the string STAF/START. Wait a maximum of 30 seconds.
GET WAIT 30000 CONTAINS STAF/START
Goal: Retrieve a priority 3 message from machine Client3 and registered process name JavaTest1 containing the message referenced by variable TestString.
PEEK PRIORITY 3 MACHINE Client3 NAME JavaTest1 CONTAINS {TestString}
Goal: Wait for, retrieve, and remove the highest priority message containing either STAF/START or STAF/SHUTDOWN from machine Client1, Client2, or Client3
GET WAIT CONTAINS STAF/START CONTAINS STAF/SHUTDOWN MACHINE Client1 MACHINE Client2 MACHINE Client3
DELETE allows you to delete a set of messages from the queue.
DELETE [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [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 originating from the given machine. The default is any machine. You may specify this option multiple times. This option will resolve variables.
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.
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.
Goal: Delete all messages from machine Client2.
DELETE MACHINE Client2
Goal: Delete all priority 3 messages from processes with registered name JavaTest1
DELETE PRIORITY 3 NAME JavaTest1
Goal: Delete all priority 3 and 4 messages from the machines referenced by variables Mach1 and Mach2 containing the string STAF/START or the the string referenced by variable StringTest1.
DELETE PRIORITY 3 PRIORITY 4 MACHINE {Mach1} MACHINE {Mach2}
CONTAINS STAF/START CONTAINS {StringTest1}
Goal: Delete all messages in the queue.
DELETE
LIST allows you to retrieve the contents of the queue of a given process.
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 may 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 list of queue messages in the following format sorted in ascending order by priority.
<Priority>;<Timestamp>;<Machine>;<Name>;<Handle>;<Message>
For example,
1;19980416-13:56:10;Client1;STAF_Process;1;STAF/START 3;19980416-14:01:52;Client3;JavaTest1;36;CONTROL/STAGE2 3;19980416-14:02:17;Client2;STAF_Process;1;STAF/START 5;19980416-13:57:36;Client3;JavaTest1;36;CONTROL/STAGE1
Goal: Retrieve the contents of the submitting process' queue.
LIST
Goal: Retrieve the contents of the process with handle 39.
LIST HANDLE 39
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 OldReturnCodes
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>] [OLDRETURNCODES | NEWRETURNCODES]
DIRECTORY specifies the root directory under which resource pool files are stored. The default is {STAF/Config/STAFRoot}\data\respool.
Note: Previously, in STAF 2.2 and earlier, the default root directory for the old REXX version of the Resource Pool service was {STAF/Config/BootDrive}\STAF\ResPool and that the root directory could be changed by setting a Variable named STAF/Service/<Name>/Directory. So, if you want to continue to use these 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.
OLDRETURNCODES specifies that the Resource Pool service should return the old error codes used prior to STAF 2.3. See 8.13.12, "Resource Pool Error Code Reference" for more information.
NEWRETURNCODES specifies that the Resource Pool service should return the error codes newly defined in STAF 2.3. See 8.13.12, "Resource Pool Error Code Reference" for more information. This is the default.
LIST displays a list of resource pools and their descriptions.
LIST
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.13.12, "Resource Pool Error Code Reference".
The result buffer for LIST will contain a list of resource pools and their descriptions in the following format:
<Pool Name> - <Pool Description> ... ...
For example,
AUSVMR - UserIDs and Passwords for VM System AUSVMR AutoTester_Licenses - License numbers for AutoTester
Goal:List all of the resource pools
LIST
Creates a resource pool.
CREATE POOL <Name> DESCRIPTION <Description>
POOL specifies the name of the resource pool you want to create.
DESCRIPTION specifies the description of the resource pool.
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.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from a CREATE command.
Goal: Create a resource pool called AUSVMR with the description "UserIDs and Passwords for VM System AUSVMR"
CREATE POOL AUSVMR DESCRIPTION "UserIDs and Passwords for VM System AUSVMR"
Deletes a resource pool and all its entries.
DELETE POOL <Name> CONFIRM [FORCE]
POOL specifies the name of the resource pool you want to delete.
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.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from a DELETE command.
Goal:Delete resource pool AUSVMR, but only if there are no pending requests
DELETE POOL AUSVMR CONFIRM
Goal:Delete resource pool AUSVM1, even if there are pending requests
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.
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.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from the ADD command.
Goal:Add the entries "User1 Password1" and "User2 Password2" to resource pool AUSVMR
ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2"
Goal:Add entry 1047923 to resouce pool AutoTester_Licenses
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.
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.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from the REMOVE command.
Goal:Remove entry "User1 Password1" from resource pool AUSVMR, but only if the entry is not currently owned.
REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM
Goal:Remove entries 1137849 and 1075234 from resource pool AutoTester_Licenses regardless of whether the are currently owned
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.
QUERY POOL <Name>
POOL specifies the name of the resource pool you want to query.
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.13.12, "Resource Pool Error Code Reference".
The result buffer for QUERY will contain a list of the entries in the specified pool and indicate whether the resource is available and show the number of pending requests for an entry in the specified pool, if any, and list the pending requests. If the resource is available, the word "Available" will be shown by an entry, otherwise the word "Owned" will be shown by an entry followed by "Owned By" information including the date/time the entry was acquired. The format of the result buffer for QUERY follows:
Description: <Description> Pending requests: <Number of pending requests> Request <Number>: <Machine>;<Process>;<Handle>;<Timestamp> Resources: <Resource>;<Owned|Available>[;<Machine>;<Process>;<Handle>;<Timestamp>;<Acquired Timestamp>]For example,
Description: UserIDs and Passwords for VM System AUSVMR Pending requests: 2 Request 1: cd5d;CM2_1;8;19980825-13:07:05 Request 2: cf2a;JCSHOD;23;19980825-13:07:12 Resources: RDJSV01 RDJSV01;Owned;cf3c;CM2_1;13;19980825-12:58:05;19980825-12:58:30 RDJSV02 RDJSV02;Owned;cd1a;JCSHOD;7;19980825-13:02:29;19980825-13:02:51 RDJSV03 RDJSV03;Owned;cd5a;JCSHOD;25;19980825-13:06:31;19980825-13:06:45or
Description: UserIDs and Passwords for VM System AUSVMR Pending requests: 0 Resources: RDJSV01 RDJSV01;Owned;cf3c;CM2_1;13;19980825-11:58:05;19980825-11:58:30 RDJSV02 RDJSV02;Owned;cd1a;JCSHOD;7;19980825-11:59:29;19980825-11:59:51 RDJSV03 RDJSV03;Available RDJSV04 RDJSV03;Available RDJSV05 RDJSV05;Available
Goal:Query resource pool AUSVMR
QUERY POOL AUSVMR
Obtains exclusive access to an entry from the resource pool.
REQUEST POOL <Name> [TIMEOUT <Timeout>] [FIRST | RANDOM]
POOL specifies the name of the resource pool from which you are requesting a resource.
TIMEOUT specifies the amount of time in milliseconds that you want to wait for a resource. If no timeout is specified, the request will wait indefinitely.
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.
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.13.12, "Resource Pool Error Code Reference".
On successful return, the result buffer will contain the entry given to the process.
Goal:Request, and wait indefinitely for, the first available entry from resource pool AUSVMR.
REQUEST POOL AUSVMR FIRST
Goal:Request a random entry from resource pool AutoTester_Licenses. If no entry is available within five minutes (300 seconds), timeout.
REQUEST POOL AutoTester_Licenses TIMEOUT 300000
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.
ENTRY specifies the actual entry to which you are releaseing exlusive access.
FORCE allows you to force the release of the resource entry. By default, only the process that REQUESTED the entry 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.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from the RELEASE command.
Goal:Release exclusive access of entry "User2 Password2" to resource pool AUSVMR
RELEASE POOL AUSVMR ENTRY "User2 Password2"
Goal:Force the release of entry 1137849 which is a member of resource pool AutoTester_Licenses.
RELEASE POOL AutoTester_Licenses ENTRY 1137849 FORCE
In addition to STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Resource Pool return codes are defined:
Note: Error codes 4001, 4002, 4003, and 4004 are now obsolete and are no
longer returned by the Resource Pool service. They are documented here
for those still using an older version of the Resource Pool service.
Table 10. Resource Pool Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4001 | Pool already exists | The resource pool you are trying to CREATE already exists. |
| 4002 | Pool does not exist | The resource pool you specified does not exist. Use LIST to determine the available resource pools. |
| 4003 | Entry does not exist | A resource pool entry you specified does not exist. Use QUERY to determine the valid resource pool entries. |
| 4004 | Entry already exists | A resource pool entry you tried to ADD already exists. Resource pool entries must be unique within a given resource pool. |
| 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. |
This service is now depricated. Its functionality has been moved into the remote logging capabilities of the Log Service (see section 8.7, "Log Service"). This section is here to remind existing RLog service users of the change. This section will be removed in a later version of STAF.
The SEM service is one of the internal STAF services. It provides the following commands
MUTEX allows you to manipulate a mutex sempahore. A mutex semaphore allows you to synchronize access to a particular resource. You may request exclusive access of the semaphore, release exclusive access of the semaphore, query the semaphore, and delete the semaphore.
MUTEX <Name> <REQUEST [Timeout] | RELEASE [FORCE] | DELETE | QUERY>
MUTEX specifies the name of the mutex semaphore in which you are interested. This option will resolve variables.
REQUEST specifies that you want exclusive access to the 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. This option will resolve variables.
RELEASE specifies that you wish to release exclusive access to the semaphore. Normally, only the owning process may RELEASE the semaphore. Specifying FORCE allows you to force the release of the semaphore.
Note: Any thread in the owning process may RELEASE the semaphore. This is in contrast to other semaphore systems, where only the REQUESTing thread may release the semaphore.
DELETE specifies that you wish to delete the semaphore. The semaphore may only be deleted if there are no pending REQUESTs.
QUERY specifies that you wish to get information on the semaphore, such as, the current owner and pending REQUESTs.
Subcommand QUERY requires trust level 2.
Subcommands REQUEST and RELEASE require trust level 3.
Subcommands RELEASE FORCE and DELETE require trust level 4.
All return codes from MUTEX are documented in Appendix A, "API Return Codes".
If REQUEST, RELEASE [FORCE] , or DELETE were specified, the result buffer will contain no data upon return from the submit call.
If QUERY was specified, the result buffer will contain the word, Unowned, if the semaphore is currently unowned, otherwise it will contain information in the following format,
Owned by: <Machine>;<Process>;<Handle>;<Timestamp> Acquired: <Timestamp> Pending requests: <Number> Request <Number>: <Machine>;<Process>;<Handle>;<Timestamp> ...
For example,
Owned by: crankin3;STAF_REXX_Client;7;19980322-21:37:36 Acquired: 19980322-21:37:36 Pending requests: 0
or
Owned by: crankin3;STAF_REXX_Client;7;19980322-21:37:36 Acquired: 19980322-21:40:06 Pending requests: 2 Request 1: automate;SemTest;13;19980322-21:38:58 Request 2: automate;Server1;27;19980322-21:39:22
Goal: Gain exclusive access to semaphore Printers/Printer1.
MUTEX Printers/Printer1 REQUEST
Goal: Release exclusive access to semaphore Printers/Printer1.
MUTEX Printers/Printer1 RELEASE
Goal: Gain exclusive access to semaphore DataSource1, but only wait for 30 seconds.
MUTEX DataSource1 REQUEST 30000
Goal: Delete the Printers/Printer1 semaphore.
MUTEX Printers/Printer1 DELETE
Goal: Query the information about semaphore DataSource1.
MUTEX DataSource1 QUERY
EVENT allows you to manipulate an event semaphore. An event sempahore is a signalling mechansim used to synchronize two or more tasks. You may post an event semaphore to signal that the event has happened, reset an event semaphore in preparation for the next event, pulse the event semaphore (which performs an atomic post and reset on the semaphore), wait on an event semaphore, delete an event semaphore, and query an event sempahore.
EVENT <Name> <POST | RESET | PULSE | WAIT [Timeout] | DELETE | QUERY>
EVENT specifies the name of the event semaphore in which you are interested. This option will resolve variables.
POST specifies that you wish to post the event semaphore. It is valid to post a semaphore that is already posted.
RESET specifies that you wish to reset the event semaphore. It is valid to reset a semaphore that is already reset.
PULSE specifies that you wish to post and then reset the 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.
WAIT specifies that you wish to wait for the event semaphore. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait for the event semaphore. If no timeout is specified, the request will block indefinitely. This option will resolve variables.
DELETE specifies that you wish to delete the event semaphore. The semaphore may only be deleted if there are no processes WAITing for it.
QUERY specifies that you wish to retrieve information about the event semaphore, such as, whether the semaphore is posted or reset.
Subcommand QUERY requires trust level 2.
Subcommands POST, RESET, PULSE, and WAIT require trust level 3.
Subcommand DELETE require trust level 4.
All return codes from EVENT are documented in Appendix A, "API Return Codes".
If POST, RESET, PULSE, WAIT, or DELETE were specified, the result buffer will contain no data upon return from the submit call.
If QUERY was specified, the result buffer will contain information in the following format
State: <Posted | Reset> Last posted: <Machine>;<Process>;<Handle>;<Timestamp> Last reset : <Machine>;<Process>;<Handle>;<Timestamp>
If the semaphore is currently in a reset state, the result buffer will contain addtional information in the following format
Number of waiters: <Number> Waiter <Number>: <Machine>;<Process>;<Handle>;<Timestamp> ...
For example,
State: Posted Last posted: crankin3;STAF_REXX_CLient;17;19980322-21:37:43 Last reset : crankin3;STAF_REXX_Client;15;19980322-21:36:35
or
State: Reset Last posted: crankin3;SemTest;26;19980322-21:40:22 Last reset : automate;SemTest;59;19980322-21:41:01 Number of waiters: 2 Waiter 1: Server1;STAFClnt;39;19980322-21:43:19 Waiter 2: Client2;STAF_REXX_Client;61;19980322-21:45:46
Goal: Wait for event semaphore Server1/LAN_Started
EVENT Server1/LAN_Started WAIT
Goal: Post event semaphore Server1/LAN_Started
EVENT Server1/LAN_Started POST
Goal: Reset the event semaphore Coffee/Ready
EVENT Coffee/Ready RESET
Goal: Pulse the event semaphore Race/StartLap
EVENT Race/StartLap PULSE
Goal: Wait a maximum of 20 seconds for event semaphore Coffee/Ready
EVENT Coffee/Ready WAIT 20000
Goal: Delete the event semaphore Shutdown_The_Lab
EVENT Shutdown_The_Lab DELETE
Goal: Query information about event semaphore Server1/LAN_Started
EVENT Server1/LAN_Started QUERY
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 sempahores.
EVENT specifies that you want a list of the event sempahores.
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 semaphores. If MUTEX was specified the information will be in the following format
<Name>: <Unowned | Owned - <Number> pending request(s)>
For example,
DataSource1: Unowned Printers/Printer1: Owned - 2 pending request(s)
If EVENT was specified the information will be in the following format
<Name>: <Posted | Reset - <Number> waiter(s)>
For example,
Coffee/Ready: Posted Server1/LAN_Started: Reset - 5 waiter(s) Shutdown_The_Lab: Reset - 0 waiter(s)
Goal: Obtain a list of the of mutex semaphores.
LIST MUTEX
Goal: Obtain a list of the of event semaphores.
LIST EVENT
The SERVICE service is one of the internal STAF services. It provides the following commands.
LIST will display information about the services or service loaders available on the machine or requests that have been submitted on the machine.
LIST [SERVICES | SERVICELOADERS | REQUESTS [PENDING] [COMPLETE]]
SERVICES specifies that you want a list of services.
SERVICELOADERS specifies that you want a list of the service loaders.
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 inlude completed requests which have not yet been FREEd.
If neither PENDING nor COMPLETE is specified the default is PENDING.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return, for Services and Service Loaders, the result buffer will contain a listing of the available services, and service specific information. For Requests, the result buffer will contain information about the request in the following format:
<#>;<State>;<OMachine>;<OProcess>;<OHandle>;<StartTimestamp>;<TMachine>;<Service>;<Request>[;<RC>;<Result>]
# is the request number.
State is the state of the request. This will be either pending or complete.
OMachine, OProcess, and OHandle are the machine name, registered process name, and handle of the process that originated the request.
StartTimestamp is the timestamp when the request started.
TMachine is the machine to which the request was sent, i.e. the target machine.
Service is the service to which the request was sent.
Request is the request which was sent.
RC is the return code from the request. This will only be displayed if the request State is complete.
Result is the result buffer from the request. This will only be displayed if the request State is complete.
Goal: List all the services available on a machine.
LIST SERVICES
might result in the following
DELAY: Internal DIAG: Internal ECHO: Internal EVENT: External library JSTAF, exec C:\STAF\services\STAFEvent.jar FS: Internal HANDLE: Internal HELP: Internal LOG: External library STAFLog MISC: Internal MONITOR: External library STAFMon PING: Internal PROCESS: Internal QUEUE: Internal RESPOOL: External library STAFPool RLOG: Delegated to RLOG on ev3c SEM: Internal SERVICE: Internal SHUTDOWN: Internal STAX: External library JSTAF, exec C:\STAF\services\STAX.jar TRUST: Internal VAR: Internal ZIP: External library STAFZip
Goal: List all the service loaders available on a machine.
LIST SERVICELOADERS
might result in the following
STAF/SERVICELOADER/1: External library STAFDSLS STAF/SERVICELOADER/2: External library JSTAF, exec C:\STAF\services\CustomServiceLoader.jar
Goal: List all the pending and complete requests on a machine.
LIST REQUESTS PENDING COMPLETE
might result in the following
10;pending;testMachineA;STAF/Client;10;20021228-18:59:55;testMachineX;delay;delay 20000 11;complete;testMachineA;STAF/Client;8;20021228-18:59:58;testMachineA;misc;version;0;2.1.0 15;pending;testMachineX;STAF/Client;8;20021228-19:02:24;testMachineA;monitor;help 18;pending;testMachineA;STAF/Client;11;20021228-19:02:43;testMachineA;service;list requests
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 or REXX script which actually implements the service. This option has no significance for non-proxy service libraries. See sections 4.4.2, "RXSTAF service proxy library" and 4.4.3, "JSTAF service proxy library" for information regarding the RXSTAF and JSTAF service proxy libraries. 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 sections 4.4.2, "RXSTAF service proxy library" and 4.4.3, "JSTAF service proxy library" for acceptable options for the RXSTAF and JSTAF service proxy libraries. 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.
Goal: Add the Monitor service, an external C++ service.
ADD SERVICE Monitor LIBRARY STAFMon
Goal: Add the STAX service, an external Java service, specifying a parameter.
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.
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.
Goal: Remove the Event service.
REMOVE SERVICE Event
QUERY will return information about requests that have been submitted on the machine.
QUERY REQUEST <Request Number>
REQUEST indicates the request number to be queried.
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 will contain information about the request in the following format:
Request Number: Request Status: Source Machine: Source Process: Source Handle : Started : Target Machine: Service : Request : Return Code : Result :
Goal: Query the information for request 16.
QUERY REQUEST 16
might result in the following
Request Number: 16 Request Status: pending Source Machine: testSystemC Source Process: STAF/Client Source Handle : 16 Started : 20021228-18:59:58 Target Machine: dave2268 Service : delay Request : delay 30000 Return Code : Result :
FREE returns the results of completed requests that were submitted using the kSTAFReqQueue or kSTAFReqQueueRetain options (see 6.1.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".
On successful return the result buffer will contain information in the following format
<Return Code>:<Result>
Return Code is the return code of the request.
Result is the result buffer of the request.
Goal: Free request 16. Let's assume this which was a "VERSION" request to the MISC service.
FREE REQUEST 16
might result in the following
0;2.1.0
The SHUTDOWN service is an internal STAF service. It provides the following commands.
SHUTDOWN, as the name implies, shuts down the STAFProc program.
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.
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 content of the notification message will be STAF/SHUTDOWN.
UNREGISTER indicates you want to unregister a shutdown notification
MACHINE specifes 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".
The result buffer will contain a list of all the registered notifiees. Each entry will either have the format <Priority>:<Machine>:NAME:<Name> or <Priority>:<Machine>:HANDLE:<Handle>, depending on whether the particular notifiee is to be notified by name or handle. For example,
5:EventSrv1:NAME:ShutdownCatcher 3:Client2:HANDLE:14
Goal: Retrieve the list of shutdown notifiees.
NOTIFY LIST
The TRUST Service is one of the internal STAF services. It allows you to query and set the trust definitions for the machine. It provides the following commands.
SET will set the default trust level or the trust level for a specific machine.
SET <MACHINE <Machine> | DEFAULT> LEVEL <Level>
MACHINE specifies that you want to set the trust level for the specified machine.
DEFAULT specifies that you want to set the default trust level.
LEVEL specifies the level of trust you wish to set.
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.
Goal: Set the trust level for machine client1 to 3.
SET MACHINE client1 LEVEL 3
Goal: Set the default trust level to 1.
SET DEFAULT LEVEL 1
GET will return the effective trust level of a given machine. If the machine has an explicit trust definition then the effective trust level is the level specified in the trust definition. Otherwise, the effective trust level is the default trust level.
GET MACHINE <Machine>
MACHINE specifies the machine for which to return the effective 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 definitions for the machine are as follows
Default: 2 client1: 3 client2: 0 client3: 5
Request: GET MACHINE client1
Result: 3
Request: GET MACHINE client2
Result: 0
Request: GET MACHINE client3
Result: 5
Request: GET MACHINE client4
LIST will return the default trust level and a list of the explicit trust definitions.
LIST
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
Default: 2 client1: 3 client2: 0 client3: 5
Goal: Retrieve the list of trust definitions.
LIST
DELETE will remove the explicit trust definition for the specified machine.
DELETE MACHINE <Machine>
MACHINE specifies the machine for which you wish to delete the specific trust definition.
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.
Goal: Delete the trust definition for machine client1.
DELETE MACHINE client1
The Variable Service, called VAR, is one of the internal STAF services. It allows you to manage the global 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.
[GLOBAL | HANDLE <Handle>] SET <Name=Value> [SET <Name=Value>]...
GLOBAL specifies that you want to set the value of the variable in the global variable pool.
HANDLE indicates that you want to set the value of the variable in the variable pool associated with the specified handle.
If neither GLOBAL nor HANDLE is 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 global variable pool.
This command requires trust level 3.
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.
Goal: Set the global WebServer variable to testsrv1.test.austin.ibm.com.
GLOBAL SET WebServer=testsrv1.test.austin.ibm.com
Goal: In the process local variable pool, set variable "Good String" to "Command completed successfully", and set variable "Bad String" to "SYS3175"
SET :42:Good String=Command completed successfully SET "Bad String=SYS3175"
Goal: Set the variable STAF/Service/Log/Mask to "FATAL ERROR WARNING" in the variable pool associated with handle 37
HANDLE 37 SET "STAF/Service/Log/Mask=FATAL ERROR WARNING"
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.
[GLOBAL | HANDLE <Handle>] GET <Name>
GLOBAL specifies that you want to get the value of the variable from the global variable pool.
HANDLE indicates that you want to get the value of the variable from the variable pool associated with the specified handle.
If neither GLOBAL nor HANDLE is 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 global variable pool.
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.
Goal: Get the value of the variable WebServer from the global variable pool
GLOBAL GET WebServer
Goal: Get the value of the variable "Good String" from the process local variable pool
GET "Good String"
Goal: Get the value of the variable ConfigData from the variable pool associated with handle 59
HANDLE 59 GET ConfigData
LIST will return a list of all variables and their values.
[GLOBAL | HANDLE <Handle> | ONLYHANDLE <Handle>] LIST
GLOBAL specifies that you want the list of variables from the global variable pool only.
HANDLE indicates that you want a combined list of variables from the global variable pool and the variable pool associated with the specified handle. If the same variable is set in both pools, the value from the specified handle's variable pool will be returned.
ONLYHANDLE indicates that you want the list of variables from the variable pool associated with the specified handle only.
If you do not specify GLOBAL or HANDLE or ONLYHANDLE, you will receive a combined list of variables from the global variable pool and the variable pool associated with the handle of the process that submitted the request, with the process-level variable's value being returned in the case where the variable exists in both pools, unless the request came from another machine, in which case only a list of the global variables will be returned.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
Bad String=SYS3175
Good String=Command completed successfully
STAF/Config/BootDrive=C:
STAF/Config/EffectiveMachine=automate
STAF/Config/Machine=automate.austin.ibm.com
STAF/Config/Memory/Physical/Bytes=49938432
STAF/Config/Memory/Physical/KB=48768
STAF/Config/Memory/Physical/MB=47
STAF/Config/OS/MajorVersion=20
STAF/Config/OS/MinorVersion=40
STAF/Config/OS/Name=OS2
STAF/Config/OS/Revision=0
STAF/Config/Sep/File=\
STAF/Config/Sep/Line=
STAF/Config/Sep/Path=;
STAF/Config/STAFRoot=D:\STAF\BIN
STAF/Service/Monitor/Directory={STAF/Config/BootDrive}\STAF\Monitor
STAF/Service/Monitor/MaxRecordSize=256
STAF/Service/Monitor/ResolveMessage=1
STAF/Service/Monitor/Retry=3
WebServer=testsrv1.test.austin.ibm.com
Goal: Retrieve the list of global variables
GLOBAL LIST
Goal: Retrieve the combined list of global and process local variables
LIST
Goal: Retrieve the combined list of global variables and variables associated with handle 62
HANDLE 62 LIST
Goal: Retrieve the list of variables associated with handle 48
ONLYHANDLE 48 LIST
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 "^". However, a caret cannot be used as an escape character within a variable reference (see the examples).
[GLOBAL | HANDLE <Handle>] RESOLVE <String> [RESOLVE <String>]... [DELIMIT <Delimiter>]
GLOBAL specifies that only variables from the global variable pool should be used to resolve a variable reference.
HANDLE indicates that variable references should try to be resolved from the variable pool assicatied with the specified handle first. If the variable is not found in this pool, the global variable pool should then be searched.
If neither GLOBAL nor HANDLE is specified, variable references will try to be resolved from the variable pool associated with the handle of the process that submitted the request first, and then, if not found, from the global variable pool, unless the request came from another machine, in which case only the global variable pool will be used to resolve variable references.
DELIMIT specifies the delimiter to use between results when resolving multiple strings. The default is the NULL character (0x00). This options is ignored if you are only resolving one string.
This command requires trust level 2.
All return codes from RESOLVE are documented in Appendix A, "API Return Codes".
If only one string is being resolved, the result buffer will contain the input string with all variable references resolved.
If you are resolving mutliple strings the result buffer will contain a string in the following format
<Return code 1>:<Result 1><Delimiter>[<Return code 2>:<Result 2><Delimiter>]...
where <Return code N> is the return code from the N'th string to be resolved, and <Result N> is the result from resovling the N'th string.
For the following examples, assume the following variables are in the global variable pool
12=Fun
a=You
b=Me
c=1
d=2
e=a
f={a}
the following variables are in the process local variable pool
a=Dogs b=Catsand the following variables are in the variable pool associated with handle 71
a=Don b=Charles
Request: GLOBAL RESOLVE {a}
Result: You
Request: GLOBAL RESOLVE "{a} and {b}"
Result: You and Me
Request: RESOLVE "{a} and {b} are {12}"
Result: Dogs and Cats are Fun
Request: RESOLVE {c}{d}
Result: 12
Request: RESOLVE {1{d}}
Result: Fun
Request: RESOLVE {{c}{d}}
Result: Fun
Request: RESOLVE {{e}}
Result: Dogs
Request: RESOLVE {f}
Result: Dogs
Request: RESOLVE {a} RESOLVE {b} RESOLVE {q} DELIMIT |
Result: 0:Dogs|0:Cats|13:q|
Request: HANDLE 71 RESOLVE "{f} and {b}"
Result: Don and Charles
The following examples show the use of a caret (^) as an escape character for "{" and "^". Assume the following variables are in the global variable pool for these examples:
h=Hi Hi=HI ^Hi=Hello
Request: GLOBAL RESOLVE "^{{h}, ^{{h}}, {{h}}, ^^{{h}}, and ^{^{h}}
Result: {Hi, {Hi}, HI, ^HI, and {{h}}
Request: GLOBAL RESOLVE "{^{h}}"
Result: Hello
Note that {^{h}} shows that a caret cannot be used as an escape character within a variable reference.
DELETE will remove the given variable from the appropriate variable pool.
Note that you may DELETE multiple variables with a single request.
[GLOBAL | HANDLE <Handle>] DELETE <Name> [DELETE <Name>]...
GLOBAL specifies that you want to delete the variable from the global variable pool.
HANDLE indicates that you want to delete the variable from the variable pool associated with the specified handle.
If neither GLOBAL nor HANDLE is 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 global variable pool.
This command requires trust level 3.
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.
Goal: Delete the variable WebServer from the global variable pool.
GLOBAL DELETE WebServer
Goal: Delete the variable "Bad String" from the process local variable pool.
DELETE "Bad String"
Goal: Delete the variable ConfigData from the variable pool associated with handle 59
HANDLE 59 DELETE ConfigData
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 an Zip archive; list content of an Zip archive, append file / directory to an existing Zip archive, etc.
The syntax and results for requests to the ZIP service are subject to change.
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
ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
[RELATIVETO <Directory>]
ZIPFILE contains the fully qualified ZIP archive name.
ADD indicates you want to add files to the ZIP archive.
FILE contains the fully qualified file name you want to zip into the ZIP archive.
DIRECTORY contains the fully qualified directory name you want to zip info the ZIP archive.
RELATIVETO contains the prefix to be excluded from the fully qualified file name or directory name that is to be zipped into the ZIP archive.
RECURSE indicates that the all the files and subdirectories in the given directory will be zipped 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.20.7, "Zip Error Code Reference".
On a successful return, the result buffer will contain no data on return from a ZIP command.
Extract files from a Zip archive to a specified directory.
UNZIP ZIPFILE <Name> TODIRECTORY <Name>
[FILE <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 to be unzipped.
RESTOREPERMISSION indicates that the owner, group and permission attributes of the file will be restored.
REPLACE indicates that the file will be over written if it already exists in the specified directory.
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.20.7, "Zip Error Code Reference".
On a successful return, the result buffer will contain no data on return from a UNZIP command.
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.20.7, "Zip Error Code Reference"
On successful return, the result buffer will contain a listing of the contents of the Zip archive. The data will be formatted as follows with one line for every entry in the Zip archive.
Length Method Size Ratio Date Time CRC-32 Name ------ ------ ---- ----- ---- ---- ------ ---- 16118 Defl-X 4330 26% 12-12-03 13:20 9a1de6ee myjava/Hello.java 792874 Defl-X 261648 33% 12-12-03 14:46 7e2f5bc8 bin/run The Length column contains the uncompressed size of the file. The Method column contains the compression method "-" compression level used to compress the file. For example "Defl-X", "Defl" stands for "Deflated", "X" stands for "Maximum compression". Compression level can also contain the following values: "N" stands for "Normal compression", "F" stands for "Fast and Super fast compression". Compression method can also contain the following values: "Stored" stands for "No compression", "Unkn." stands for "Unknow compression method". The Size column contains the compressed size of the file. The Ratio column contains the compression ratio of the file. The Date column contains the date stamp of the original file. The Time column contains the time stamp of the original file. The CRC-32 column contains the CRC-32 value of the file. The Name column contains the relative name of the file.
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.
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.20.7, "Zip Error Code Reference".
On a successful return, the result buffer will contain no data on return from a DELETE command.
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 11. Zip Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4001 | General zip error | An general error occured, 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. |
The Generic Workload Processor, GenWL (pronounced Jen-Wall), allows you to define a workload based on a set of machines, processes, and variables, and then provides a means to start, stop, and query the workload.
The syntax for the Generic Workload Processor is
GenWL <Workload Definition File> -<Start[:<Actions>] | Stop | Query | Free>
[-<Include | Exclude>:<MACHINE | PROCESS>:<List>]
[-Quiet | -Verbose]
The <Workload Definition File> defines the workload and is discussed in the next section. The default file extension is .gwl.
-Start is used to start the workload. The processes are started asynchronously in the order that they are defined in the <Workload Definition File> You may optionally specify which actions will take place when you start a workload. These are specified in a comma separated list in place of <Actions> above. No spaces should be used between the commas and the actions. The following are the valid actions:
-Stop is used to stop the workload.
-Query is used to query the workload.
-Free is used to free the termination information for the workload.
-Include and -Exclude allow you to specify that a certain set of machines or processes should be included or excluded from processing. The list of machines or processes is separated by commas and may contain a trailing *, as a wildcard, on any value. No spaces should be used between the commas and the values. These lists are used in place of <List> above. -Includes are processed before -Excludes.
-Quiet supresses all informational messages while processing
-Verbose provides additional informational messages while processing
Note: GenWL is a REXX program. On non-OS/2 systems, you will need to preface the following examples with REXX.
Goal: Start the workload defined in WebTests.gwl
GenWL WebTests -Start
Goal: Query the workload defined in Ogre.cfg
GenWL Ogre.cfg -Query
Goal: Set all global variables defined in MyTest.gwl on machines client1, client2, and client3.
GenWL MyTest -Start:GlobalVar -Include:MACHINE:client1,client2,client3
Goal: Query the workload defined in MyTest.gwl, but exclude machines whose names begin with bad.
GenWL MyTest -Query -Exclude:MACHINE:bad*
Goal: Stop the processes named Test1 and Test2 on machines client1 and client2 that are defined in workload MyTest.gwl
GenWL MyTest -Stop -Include:MACHINE:client1,client2 -Include:PROCESS:Test1,Test2
The workload definition file defines the various machines, processes, and variables that will be used in the workload. The language used in these files consists of the following elements, which will be discussed below.
Blank lines in the file are ignored.
A comment begins with a pound sign, #, and continues through to the end of the line.
WORKLOAD "Web Tests" # Set the workload name
The WORKLOAD statement defines the name of the workload.
WORKLOAD <Name>
WORKLOAD "Web Tests" WORKLOAD Ogre
You must have a WORKLOAD statement in your workload definition file. If you have more than one, the last one takes precedence.
A variable statement allows you to specify a variable and its value. A variable statement inside of a process block is local to that particular process. A variable statement inside of a machine block, but outside of a process block, is global to that machine. A variable statement outside of a machine block is a workload variable, and is set as a global variable on all the machines defined in the workload definition file.
VAR <Name=Value>
VAR WebServer=testsrv1.test.austin.ibm.com VAR "Good String=Command completed successfully"
A machine block defines a machine you wish to use in the workload as well as any global variables on that machine and any processes to run on that machine.
MACHINE <Name>
[One or more variable statements]
[One or more process blocks]
[One or more process references]
END
MACHINE Client1
VAR LogDirectory=d:\logs
VAR MonitorDirectory=d:\monitor
PROCESS
COMMAND d:\testcase\tc1.exe
END
PROCREF tc2
END
A process block defines a process. If the process is defined within a machine block then the process is specific to that machine. If the process is defined outside of a machine block, then the process is global in nature and may be referenced by any machine block using a PROCREF statement (see 9.2.6, "Process reference").
PROCESS
[NAME <Name>]
COMMAND <Command>
[WORKDIR <WorkDir>]
[TITLE <Title>]
[ENV <Name=Value>] [ENV <Name=Value>] ...
[One or more variable statements]
END
NAME specifies the name of the process. This is used to refer back to the process via a PROCREF.
COMMAND, PARMS, WORKDIR, TITLE, and ENV are defined as in 8.11, "Process Service".
PROCESS
NAME WebTest1
COMMAND cmd.exe
PARMS "/c d:\\webtests\\webtest1.cmd"
WORKDIR d:\webtests
TITLE "Web Test 1"
ENV USEHOSTS=1
VAR WebServer=testsrv2.test.austin.ibm.com
END
PROCESS COMMAND d:\webtests\webtest2.exe END
A process reference is a reference to a previously defined process. It is used inside a machine block to indicate that the previously defined process is to be executed by this machine.
PROCREF WebTest1 PROCREF "Big bad stress test"
When you query a workload, you will see a section for each machine as defined in the workload definition file. In this section there will be one line of information per process defined on that machine. Each line contains the handle of the process, with the registered name of the process in parentheses. Following this information is either any available MONITOR data, if the process is still running, or completion information, if the process is no longer running.
Client1 ------- 42(WebTest1) - 19980215-13:12:17 Starting loop 123 43(WebTest2) - 19980215-13:10:39 ERROR: invalid internal html link Client2 ------- 35(WebTest1) - Completed at 19980205-10:19:48, RC: 0 43(WebTest3) - 19980215-13:11:26 Entering JavaScript verification phase
You may also receive warning messages if there are a greater or lesser number of processes running under the context of the workload on a given machine than are defined in the workload definition file. For example, if Client1 is running three processes with the workload name "Web Tests", but only two are defined in the workload definition file, you will get a warning indicating that there is one more process running than defined.
# This is a generic workload definition file for use with test environment 08
# It makes use of the sitloop command file to start test cases.
Workload "ST08 Environment Tests"
#
# Define a workload variable
#
VAR WorkLoadID=ST08T5
VAR Success_msg="Command completed successfully"
VAR LogDirectory={STAF/Config/BootDrive}\ITLUTIL\STAFLog
VAR MonitorDirectory={STAF/Config/BootDrive}\ITLUTIL\STAFMon
#
# Define some processes for later use
#
PROCESS
NAME VACPP02
TITLE VACPP02
COMMAND cmd.exe
PARMS "/c sitloop /lc=1 /lt=600 /tc=vacpp02 /cmd=vacpp02_staf.cmd c: c:"
END
PROCESS
NAME VACPP03
TITLE VACPP03
COMMAND cmd.exe
PARMS "/c sitloop /lc=1 /lt=600 /tc=vacpp03 /cmd=vacpp03_staf.cmd c: c:"
END
#--------
# ST08S04
#--------
Machine cd1b
PROCESS
TITLE L123G_1
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=600 /tc=L123G_1 /cmd=sitl123g_staf.cmd /p=s04held"
END
End # End of the machine block
#--------
# ST08R01
#--------
Machine cd1c
PROCESS
TITLE DB2_1
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=DB2_1 /cmd=sitdb2r_staf.cmd /c=1"
END
PROCESS
TITLE EXER_CCC
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_ccc /cmd=exer_ccc_staf.cmd /S-ST08S04"
END
PROCESS
TITLE INTEROPA
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=INTEROPA /staf /cmd=sitls01.cmd /alias=s05util"
END
PROCESS
TITLE NW_1
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=20 /lt=600 /tc=NW_1 /cmd=itlnw211_staf.cmd"
END
PROCESS
TITLE L123G_1
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=5 /lt=600 /tc=L123G_1 /cmd=sitl123g_staf.cmd /p=s04held"
END
End # End of the machine block
#--------
# ST08R02
#--------
Machine cf2b
PROCESS
TITLE EXER_WEB
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_web /cmd=exer_web_staf.cmd /ID-WEB"
END
PROCESS
TITLE INTEROPB
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=INTEROPB /staf /cmd=sitls01.cmd /alias=s01util"
END
PROCESS
TITLE Notes_TestNSF
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=4 /lt=600 /tc=notes_testnsf /cmd=sittnsf_staf.cmd"
END
PROCESS
TITLE BAPCO_3
COMMAND cmd.exe
PARMS "/c bapstart03_staf /lh=2"
END
PROCREF VACPP02
PROCREF VACPP03
End # End of the machine block
#--------
# ST08R09
#--------
Machine cd3b
PROCESS
TITLE EXER_WEB
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_web /cmd=exer_web_staf.cmd /WS-ST08R09 /h-cd1b /ms-600 /ID-WEB"
END
PROCESS
TITLE ITLPing01
COMMAND cmd.exe
PARMS "/c sitloop /hours=2 /lc=20 /lt=60 /tc=itlping01 /cmd=itlping01_staf.cmd cf2c"
END
End # End of the machine block
cd1b
----
5(nw_1) - 19980428-19:31:09 ST08T5---COMPLETED PASS: 18, SLEEP FOR 448SEC
cd1c
----
84(DB2_1) - Completed at 19980428-17:41:29, RC: 1
85(exer_ccc) - 19980428-19:31:04 ST08T5---STARTING PASS: 27
86(INTEROPA) - 19980428-19:31:00 SITLS01---PASS 19: COPY 8MB.DAT FROM REMOTE COMPLETE
87(NW_1) - 19980428-19:27:37 ST08T5---COMPLETED PASS: 19, SLEEP FOR 446SEC
88(L123G_1) - Completed at 19980428-18:55:39, RC: 1
cf2b
----
Warning: There were 6 more processes running on this machine than were
defined in st08.gwl
2(exer_web) - Completed at 19980417-18:07:08, RC: 0
3(INTEROPB) - 19980417-14:36:32 SITLS01---PASS 1: COPY 8MB.DAT TO REMOTE COMPLETE
4(notes_testnsf) - Completed at 19980417-15:14:25, RC: 1
5(bapco_3) - Completed at 19980417-14:51:16, RC: 0
6(vacpp02) - 19980417-14:28:44 ST08T5---STARTING PASS: 1
7(vacpp03) - 19980417-14:28:44 ST08T5---STARTING PASS: 1
10(exer_web) - 19980428-19:26:20 ST08T5---STARTING PASS: 14
11(INTEROPB) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
12(notes_testnsf) - 19980428-19:24:19 ST08T5---COMPLETED PASS: 3, SLEEP FOR 237SEC
13(bapco_3) - 19980401-14:04:27 COMPLETED PASS: 1
14(vacpp02) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
15(vacpp03) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
cd3b
----
6(exer_web) - 19980428-19:27:04 ST08T5---STARTING PASS: 11
7(itlping01) - 19980428-19:30:44 ST08T5---COMPLETED PASS: 103, SLEEP FOR 53SEC
Utilities are provided to assist in the usage and flexibility of STAF. For each utility the following sections are listed.
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.7.11, "Logging Levels Reference" for a complete list of logging levels.
FIELDSEP is the character that separates each record field, the default is "|".
D:\STAF\LOGGING\ <-Global Top D:\STAF\LOGGING\GLOBAL\ <--Global Dir STRESSTST.LOG <---Global Log SUITE100.LOG <---Global Log D:\STAF\LOGGING\MACHINE\ <-Machine Top D:\STAF\LOGGING\MACHINE\AQUADYNE\ <--AQUADYNE Top D:\STAF\LOGGING\MACHINE\AQUADYNE\GLOBAL\ <---AQUADYNE Global Top TESTLOG1.LOG <----AQUADYNE Global Logs D:\STAF\LOGGING\MACHINE\AQUADYNE\HANDLE\ <--AQUADYNE Handle Top D:\STAF\LOGGING\MACHINE\AQUADYNE\HANDLE\100\ <---Handle 100 Top TESTLOG2.LOG <---Handle 100 Log D:\STAF\LOGGING\MACHINE\AUTOMATE\ <--AUTOMATE Top D:\STAF\LOGGING\MACHINE\AUTOMATE\GLOBAL\ <---AUTOMATE Global Top AUTOGLOB.LOG <----AUTOMATE Global Log D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\ <---AUTOMATE Handle Top D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\42\ <----Handle 42 Top HANDLOG1.log <-----Handle 42 Log D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\43\ <----Handle 43 Top HANDLOG2.log <-----Handle 43 Log HANDLOG3.log <-----Handle 43 Log D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\44\ <----Handle 44 Top HANDLOG4.log <-----Handle 44 Log D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\45\ <----Handle 45 Top HANDLOG5.log <-----Handle 45 Log
In STAF 3.0, commands that return a "multi-valued" result will have a new result format and the syntax of some commands will be changed to follow the STAF standardization rules. To help current STAF 2.x customers prepare for migrating from STAF 2.x to 3.0, a new DIAG (Diagnostics) internal service is provided which allows for the recording of diagnostics data. The DIAG service is being used to track any invocation of a command that will be changing in STAF 3.0. The DIAG service will record the diagnostic trigger (in this case, the service/request that will be changing in STAF 3.0) along with the source of the trigger (the machine/handle/handle name that originated the request). By running with diagnostics enabled, users are able to identify which test cases, applications, and services they have written will need to be updated to work with STAF 3.0.
You must install STAF V2.6.1 or later (but < V3.0.0) to take advantage of this migration aid. Note that STAF V2.6.4 contains the most up-to-date migration aid.
In addition, the following external Java services have been instrumented to record STAF V3.0 migration diagnostics data. If you use any of the following external services, you should also install the new versions of these services:
Note: The above versions of Java services require STAF 2.6.0 (or a later 2.x version).
To record diagnostics for STAF-enabled test cases, applications, or services that you have written, you will need to enable diagnostics on the machines involved. To enable diagnostics, you can use the ENABLE request for the DIAG service. See 8.2.5, "ENABLE" for more information on using enabling diagnostics dynamically. Or, you can enable diagnostics automatically when STAF starts via the ENABLEDIAG operational setting in the STAF configuration file. See 4.6, "Operational parameters" for more information on using this operational setting. After you have completed running the STAF-enabled testcases, applications, and/or services, and diagnostics have been recorded, you can disable diagnostics on the machines involved. See 8.2.6, "DISABLE" for more information on disabling diagnostics.
This section contains a list of the triggers for all STAF commands owned by the STAF Development team that will be changing in STAF 3.0 due to one or both of the following reasons:
Note that many results vary depending on the request options specified, with results for some requests sometimes containing multiple values and at other times only containing one value.
The format of the trigger recorded by STAF services to aid in migrating to STAF 3.0 is:
STAF/V3.0-Mig/<Service> <Request>where:
The format of the source recorded by STAF services to aid in migrating to STAF 3.0 is:
<Handle Name>;<Machine Name>;<Handle#>where:
Table 12. STAF V3.0 Migration Diagnostics Triggers
| Trigger | Meaning |
|---|---|
| STAF/V3.0-Mig/CRON LIST | This indicates a LIST request to the CRON service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/EVENT LIST | This indicates a LIST request to the EVENT service.
The result and syntax for the request will change in STAF V3.0.
The syntax changes include:
|
| STAF/V3.0-Mig/EVENT QUERY | This indicates a QUERY request to the EVENT service.
The result and syntax for the request will change in STAF V3.0.
The syntax changes include:
|
| STAF/V3.0-Mig/EVENTMANAGER LIST | This indicates a LIST request to the EVENTMANAGER service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FS COPY DIRECTORY (no IGNOREERRORS) | This indicates a COPY DIRECTORY request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FS DELETE (no IGNOREERRORS) | This indicates a DELETE request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FS GET ENTRY SIZE | This indicates a GET ENTRY request to the FS service, with the SIZE option specified. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FS LIST | This indicates a LIST request to the FS service. The result for the request will change in STAF V3.0. Also, changed the request syntax: the FORMAT option will change to the DETAILS option in STAF V3.0. Also, note that the default format when using the LONG option is different in STAF V3.0. |
| STAF/V3.0-Mig/FS QUERY | This indicates a QUERY request to the FS service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FSEXT COMPAREDIR (No EXISTS) | This indicates a COMPARDIR request to the FSEXT service that does not specify the EXISTS option. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FSEXT FILECONTAINS NOT | This indicates a FILECONTAINS request to the FSEXT service with the NOT option specified. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/FSEXT LINECONTAINS | This indicates a LINECONTAINS request to the FSEXT service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HANDLE QUERY | This indicates a QUERY request to the HANDLE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HELP ERROR | This indicates a ERROR request to the HELP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HELP LIST | This indicates a LIST request to the HELP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HTTP FOLLOW LINK | This indicates a FOLLOW LINK request to the HTTP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HTTP LIST | This indicates a LIST request to the HTTP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HTTP REQUEST|POST|DOGET | This indicates a REQUEST, POST, or DOGET request to the HTTP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HTTP QUERY | This indicates a QUERY request to the HTTP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/HTTP SUBMIT FORM | This indicates a SUBMIT FORM request to the HTTP service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/LOG LIST | This indicates a LIST request to the LOG service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/LOG PURGE | This indicates a PURGE request to the LOG service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/LOG QUERY | This indicates a QUERY request to the LOG service.
The result for the request will change in STAF V3.0.
In addition, there are some changes to the request syntax in STAF V3.0:
|
| STAF/V3.0-Mig/LOG SET | This indicates a SET request to the LOG service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/MISC MACHINE | This indicates a MACHINE request to the MISC service. This request does not exist in STAF V3.0 as it is no longer needed since there a USELONGNAMES operational setting no longer exists (e.g. the effective machine name and machine name are now the same). |
| STAF/V3.0-Mig/MISC TRACE | This indicates any TRACE request to the MISC service, other than a TRACE LIST request. The syntax for the request will change in STAF V3.0 due to moving the TRACE requests from the MISC service to a new TRACE service. |
| STAF/V3.0-Mig/MISC TRACE LIST | This indicates a LIST request to the MISC service. The result for the request will change in STAF V3.0, as well as the syntax. |
| STAF/V3.0-Mig/MONITOR LIST | This indicates a LIST request to the MONITOR service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/MONITOR QUERY | This indicates a QUERY request to the MONITOR service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/MONITOR SET | This indicates a SET request to the MONITOR service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/NAMEDCOUNTER LIST | This indicates a LIST request to the NAMEDCOUNTER service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/PROCESS FREE ALL|WORKLOAD | This indicates a FREE ALL or FREE WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/PROCESS NOTIFY LIST | This indicates a NOTIFY LIST request to the PROCESS service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/PROCESS QUERY | This indicates a QUERY request to the PROCESS service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/PROCESS START WAIT | This indicates a START request to the PROCESS service with the option WAIT specified. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/PROCESS STOP ALL|WORKLOAD | This indicates a STOP ALL or STOP WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/QUEUE GET|PEEK | This indicates a GET or PEEK request to the QUEUE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/QUEUE LIST | This indicates a LIST request to the QUEUE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/RESPOOL LIST | This indicates a LIST request to the RESPOOL service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/RESPOOL QUERY | This indicates a QUERY request to the RESPOOL service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM EVENT DELETE | This indicates an EVENT DELETE request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM EVENT POST|PULSE | This indicates an EVENT POST or PULSE request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM EVENT QUERY | This indicates an EVENT QUERY request to the SEM service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM EVENT RESET | This indicates an EVENT RESET request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM EVENT WAIT | This indicates an EVENT WAIT request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM LIST | This indicates a LIST request to the SEM service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM MUTEX DELETE | This indicates a MUTEX DELETE request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM MUTEX QUERY | This indicates a MUTEX QUERY request to the SEM service. The syntax and the result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM MUTEX RELEASE | This indicates a MUTEX RELEASE request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SEM MUTEX REQUEST | This indicates a MUTEX REQUEST request to the SEM service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SERVICE FREE | This indicates a FREE request to the SERVICE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SERVICE LIST | This indicates a LIST request to the SERVICE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SERVICE QUERY | This indicates a QUERY request to the SERVICE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SHUTDOWN NOTIFY LIST | This indicates a NOTIFY LIST request to the SHUTDOWN service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/STAX EXECUTE TEST RETURNDETAILS | This indicates a TEST request to the STAX service specifying option RETURNDETAILS. The result for the request will change in STAF V3.0. Note that RETURNDETAILS is an undocumented option and is for use by STAF developers only. |
| STAF/V3.0-Mig/STAX EXECUTE WAIT RETURNRESULT | This indicates an EXECUTE request to the STAX service specifying options WAIT and RETURNRESULT. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/STAX LIST | This indicates a LIST request to the STAX service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/STAX QUERY | This indicates a QUERY request to the STAX service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/STAX SET | This indicates a SET request to the STAX service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/SXE EXECUTE | This indicates an EXECUTE request to the SXE service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/TIMER LIST | This indicates a LIST request to the TIMER service. The syntax and result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/TRUST LIST | This indicates a LIST request to the TRUST service. The result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/VAR DELETE | This indicates a DELETE request to the VAR service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/VAR GET | This indicates a GET request to the VAR service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/VAR LIST | This indicates a LIST request to the TRUST service. The syntax and result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/VAR RESOLVE | This indicates a RESOLVE request to the VAR service, specifying one RESOLVE option. The syntax for the request will change in STAF V3.0. Not only has the syntax been restructured, but the DELIMIT option for resolving multiple variables will be removed in STAF V3.0 as it is no longer needed due to the new format for multi-valued results. |
| STAF/V3.0-Mig/VAR RESOLVE (Multiple) | This indicates a RESOLVE request to the VAR service, specifying more than one RESOLVE option such that the result returns the resolved value for more than one STAF variable. The syntax and result for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/VAR SET | This indicates a SET request to the VAR service. The syntax for the request will change in STAF V3.0. |
| STAF/V3.0-Mig/ZIP LIST | This indicates a LIST request to the ZIP service. The result for the request will change in STAF V3.0. |
Note: The above table is subject to change.
To view the diagnostics data that has been recorded, use the LIST request for the DIAG service. See 8.2.3, "LIST" for more information.
Messages queued by STAF V3.x and it's services have a different format than in STAF V2.x. A new TYPE option was added in STAF V3.0 to identify the type of message being queued. STAF V3.x and it's services specify a type for all the message that they generate because queued messages can contain various marshalled data structures, such as a map, so the type let's you know the structure of the message.
Here's a table showing the new format of the messages queued by STAF V3.0
and it's services, as well as showing the format of these messages queued by
STAF V2.x clients to a STAF V3.0 machine.
Table 13. STAF V3.0 Queued Messages
| Queued Messages from STAF V3.x | Queued Messages from STAF V2.x |
|---|---|
| TYPE: STAF/RequestComplete
MESSAGE: A map containing the request completion information as follows:
{
requestNumber: <Request #>
rc : <Request return code>
result : <Request result buffer>
}
| TYPE: <None>
MESSAGE: A string containing request completion information as follows: STAF/RequestComplete <Request #>;<Request return code>;<Request result buffer> |
| TYPE: STAF/Process/End
MESSAGE: A map containing the process completion information as follows:
{
handle : <Handle #>
endTimestamp: <YYYMMDD-HH:MM:SS>
rc : <Process Return Code>
key : <Key> | <None>
fileList : [
{
rc : <Returned File #1 RC>
data: <Returned File #1 Data>
}
]
}
| TYPE: <None>
MESSAGE: A string containing process completion information as follows: STAF/PROCESS/END <Handle>;<Timestamp>;<Return Code>[;<Returned file data>] |
| TYPE: STAF/Start
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAF/START. |
| TYPE: STAF/Shutdown
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAF/SHUTDOWN. |
| TYPE: STAF/Service/Event
MESSAGE: A map containing the event information as follows:
{
eventID : <Event ID>
eventServiceName: <Event Service Name>
handle : <Handle #>
handleName : <Handle Name>
machine : <Machine>
propertyMap : {
<Name>: <Value>
...
}
subtype : <Subtype>
timestamp : <YYYYDDMM-HH:MM:SS>
type : <Type>
}
| TYPE: <None>
MESSAGE: A string containing the event information as follows: STAF/SERVICE/<Event Service Name>/;<Event ID>;<Generating Machine>;<Generating Process>;<Generating Handle>;<TimeStamp>;<Type>;<Subtype>; [<Name>=<Value>;]... |
| TYPE: STAF/Service/EventManager/End
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing EventManager/End. |
| TYPE: STAF/Service/Cron/End
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing Cron/End. |
| TYPE: STAF/Service/STAX/End
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAX/End. |
| TYPE: STAF/Service/STAX/JobWaitComplete/<JobID>
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAX/Job/Wait/Complete/<JobID>. |
| TYPE: STAF/STAXMonitor/End
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAXMonitorJob/End or STAXJobMonitor/End. |
| TYPE: STAF/Service/Timer
MESSAGE: A map containing the timer information as follows:
{
timerServiceName: <Timer Service Name>
type : <Timer Type>
timestamp : <YYYYDDMM-HH:MM:SS>
}
| TYPE: <None>
MESSAGE: A string containing the timer information as follows: STAF/SERVICE/<Timer Service Name>;<Type>;<Timestamp>; |
| TYPE: STAF/Service/Timer/End
MESSAGE: A string containing QUIT. | TYPE: <None>
MESSAGE: A string containing QUIT |
| TYPE: STAF/STAFDemo/Stop
MESSAGE: Blank | TYPE: <None>
MESSAGE: A string containing STAFDemo/End. |
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-existant 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 14. 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 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 Machine | This indicates that STAFProc was not able to submit the request to the requested machine. This error usually indicates that you have not configured any network interfaces, or that STAF is not running on the target machine. Alternatively, you may need to increase your CONNECTTIMEOUT value and/or increase your CONNECTATTEMPTS value in your STAF.cfg file |
| 17 | File Open Error | This indicates that there was an error opening the requested file.
Some possible explanations are that the file/path does not exist, contains
invalid characters, or is locked.
Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call. |
| 18 | File Read Error | This indicates that there was an error while trying to read data from a file.
Note: Additional information regarding which file could not be read from may be provided in the result passed back from the submit call. |
| 19 | File Write Error | This indicates that there was an error while trying to write data to a file.
Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call. |
| 20 | File Delete Error | This indicates that there was an error while trying to delete a file or
directory.
Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call. |
| 21 | STAF Not Running | This indicates that STAF is not running on the local machine. Verify that STAFProc.exe is running. |
| 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. |
| 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 from a machine which does not have the required trust level to perform the request. |
| 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. If this error occurs, report it the authors. |
| 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 empy. |
| 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 | Service Already Exists | This indicates that the specified Service already exists.
Note: Additional information regarding the service which already exists 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 occured
during the copy.
Note: Additional information specifying the entries which could not be copied may be provided in the result passed back from the submit call. |
| 52 | Diagnostics Not Enabled | This indicates that you tried to record diagnostics data, but diagnostics have not been enabled. You must enable diagnostics before you can record diagnostics data. |
| 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 15. STAF Service Command Reference
| Command | Syntax |
|---|---|
| DELAY | Delay (or sleep) a number of milliseconds.
DELAY <milliseconds> |
| 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> |
| FS | Allows you to manipulate files and directories.
COPY FILE <Name> [TOFILE <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]
GET FILE <Name> [[TEXT | BINARY] [FORMAT <Format>]]
GET ENTRY <Name> <TYPE | SIZE | MODTIME>
QUERY ENTRY <Name>
CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
LIST DIRECTORY <Name> [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
[CASESENSITIVE | CASEINSENSITIVE] [LONG [FORMAT]]
DELETE ENTRY <Name> [CHILDREN [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[CASESENSITIVE | CASEINSENSITIVE]] [RECURSE] [IGNOREERRORS] CONFIRM
HELP
|
| HANDLE | Query information on various process handles and manage static handles.
CREATE HANDLE NAME <Handle Name> DELETE HANDLE <Number> QUERY [ALL | NAME <Handle Name>] [PENDING] [REGISTERED] [INPROCESS] [STATIC] 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 |
| 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>] [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS]
[CONTAINS <String>]... [CSCONTAINS <String>]...
[LEVELBITSTRING] [FIELDSEP <Char>]
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
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>
[LEVELMASK <Mask>] [QMACHINE <Machine>] [QHANDLE <Handle>]
[NAME <Name>] [FIRST <Num> | LAST <Num>]
[CONTAINS <String>]... [CSCONTAINS <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>] CONFIRM
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
[OLDRETURNCODES | NEWRETURNCODES]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
[RESOLVEMESSAGE | NORESOLVEMESSAGE]
VERSION
HELP
|
| MISC | Miscellaneous services such as VERSION, TRACE, and MACHINE information.
VERSION
MACHINE <Machine>
TRACE <ON | OFF> [ServiceRequest] [ServiceResult] [ServiceError]
[ServiceAccessDenied] [ServiceManagement]
[Registration] [RemoteRequests]
[Error] [Warning] [Info] [All]
TRACE [ALL] SERVICES [Service list]
TRACE TO <STDOUT | STDERR | FILE <Filename> >
TRACE LIST
HELP
|
| MONITOR | Allows test cases the ability to log and query status messages.
LOG MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
QUERY MACHINE <Machine> HANDLE <Handle>
LIST <MACHINES | [MACHINE <Machine>&.rbrk. | 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 |
| 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 [Timeout] | ASYNC]
[STOPUSING <Method>] [NEWCONSOLE | SAMECONSOLE]
[USERNAME <User name> [PASSWORD <Password>]]
[DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STATICHANDLENAME <Name>]
[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>]
QUERY <ALL | WORKLOAD <Name> | 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>]
HELP
|
| QUEUE | Allows you to manipulate and manage queues.
QUEUE [HANDLE <Handle>] | [NAME <Name>] [PRIORITY <Priority>]
MESSAGE <Message>
GET [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [CONTAINS <String>]... [ICONTAINS <String>]...
[WAIT [Timeout]]
PEEK [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [CONTAINS <String>]... [ICONTAINS <String>]...
[WAIT [Timeout]]
DELETE [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
[HANDLE <Handle>]... [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> [TIMEOUT <Timeout>] [FIRST | RANDOM] RELEASE POOL <PoolName> ENTRY <Value> [FORCE] ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE] LIST VERSION HELP |
| SEM | Allows you to manipulate and manage mutex and event semephores.
MUTEX <Name> <REQUEST [Timeout] | RELEASE [FORCE] | DELETE | QUERY> EVENT <Name> <POST | RESET | PULSE | WAIT [Timeout] | DELETE | QUERY> LIST <MUTEX | EVENT> HELP |
| SERVICE | Allows you to manage STAF services and requests.
LIST [SERVICES | REQUESTS [PENDING] [COMPLETE]]
QUERY REQUEST <Request Number>
FREE REQUEST <Request Number> [FORCE]
ADD SERVICE <Service Name> LIBRARY <Library Name>
[EXECUTE <Executable>] [OPTION <Name=[=Value]>]...
[PARMS <Parameters>]
REMOVE SERVICE <Service Name>
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
|
| TRUST | Allows you to manipulate and manage trust levels (security).
SET <MACHINE <Machine> | DEFAULT> LEVEL <Level> GET MACHINE <Machine> DELETE MACHINE <Machine> LIST HELP |
| VAR | Allows you to manipulate and manage global and process specific variable pools.
[GLOBAL | HANDLE <Handle>] SET <Name=Value> [SET <Name=Value>] ... [GLOBAL | HANDLE <Handle>] GET <Name> [GLOBAL | HANDLE <Handle>] DELETE <Name> [DELETE <Name>] ... [GLOBAL | HANDLE <Handle> | ONLYHANDLE <Handle>] LIST [GLOBAL | HANDLE <Handle>] RESOLVE <String> [RESOLVE <String>].. HELP |
| ZIP | Allows for zipping, unzipping, deleting entries in Zip archives which are
PKZip, WinZip and Jar compatible.
ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
[RELATIVETO <Directory>]
UNZIP ZIPFILE <Name> TODIRECTORY <Name>
[FILE <Name>]... [RESTOREPERMISSION] [REPLACE]
LIST ZIPFILE <Name>
DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
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 global variable from STAF, inititates 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 global variable, inititates an asynchronous PMSEEK process, list variables, queries process status, stops PMSEEK, queries process status again, frees the process, queries the global 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 Common Public License (CPL) 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 Common Public License (CPL) 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 Common Public License (CPL) 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 Common Public License (CPL) 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/EffectiveMachine}")
if STAFRC = 0 then machine = STAFResult
else
do
say "Unable to determine effective machine name!"
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 Common Public License (CPL) 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 Common Public License (CPL) 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 Common Public License (CPL) 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 Common Public License (CPL) 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);
}