Software Testing Automation Framework (STAF) User's Guide
Version 3.2.0
31 Oct 2006
Appendix B. Service Command Reference
Appendix C. Samples Descriptions
Appendix D. Code Samples and Snipets
As its name indicates, STAF is a framework. It was designed to promote reuse and extensibility. It is intended to make software testing easier, and specifically to make it easier to automate software testing. This includes creating automated testcases, managing and automating the test environment, creating execution harnesses (i.e., applications which schedule and/or execute work on test systems), etc.
STAF externalizes its capabilities through services. A service provides a focused set of functionality, such as, Logging, Process Invocation, etc. STAFProc is the process that runs on a machine, called a STAF Client, which accepts requests and routes them to the appropriate service. These requests may come from the local machine or from another STAF Client. Thus, STAF works in a peer environment, where machines may make requests of services on other machines.
STAF was designed with the following points in mind.
STAF is supported on the following operating systems
A handle is a unique identifier, representing a given process. This handle is used when submitting requests to STAF. This handle, combined with the machine name, uniquely identifies a particular process in the STAF Environment. It is this combination of machine/handle that allows services to track requests from multiple processes on different machines.
In order to submit service requests to STAF, a process must have a handle. Thus, the first thing a process should do is register with STAF to obtain a handle. Other data tied to this handle is the following:
Before a process exits it should unregister with STAF to free up any resources used by that handle.
Note: Handle 1 is always allocated to the STAF Process itself. The name associated with this handle is STAF_Process.
If STAFProc is shutdown on a machine (or the machine is rebooted), STAF handles for that machine are deleted.
The SEM and RESPOOL services perform garbage collection for handles that have been deleted. If a handle is deleted and it owns a mutex semaphore or a resource pool entry (or has a pending request for a resource pool entry), the handle will be garbage collected. This means any mutex semaphores or resource pool entries owned by the handle will be released and any pending requests submitted by the handle will be removed.
Services are what provide all the capability in STAF. Services may be internal services, in which case, the executable code for the service resides within STAFProc. Services may also be external services, in which case, the executable code for the service resides outside of STAFProc, for example, in a Java routine.
Services are known by their name, such as PROCESS or LOG. Internal services are always available and have a fixed name. External services must be registered, and the name by which they are known is specified when they are registered. If an external service is not registered with STAF, then the service is not available on that STAF Client.
Services may also be delegated to another STAF Client. In this case, when a request is made for the service on the local STAF Client, it is automatically forwarded to the machine to which this service has been delegated. For example, a testcase may request the local machine to log some information via the LOG service. If the LOG service has been delegated to another machine, the LOG request will actually be handled by the machine to which logging has been delegated. In this way, all logs could be 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.15, "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, Zip, Monitor, and ResPool services. This service will automatically be configured in your STAF.cfg file.
Authenticators are special external services whose purpose is to authenticate users in order to provide user level trust, which can be used in addition (or instead of) machine level trust. An Authenticator is a special service that accepts an authenticate request. As a user, you cannot directly submit a request to an authenticator service. Authenticators are accessed indirectly via the Handle service.
Authenticators can only be registered in the STAF configuration file -- they cannot be dynamically registered. One or more Authenticators can be registered. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter. If you want to authenticate across systems, you must register the Authenticator on each system using the same name (case-insensitive).
A workload is a set of processes running on a set of machines. A workload may be as simple as a single process running on a single machine, or it may be as complex as multiple processes on multiple machines coordinating together to perform a larger complex task. STAF was designed to help the creation and automation of workloads of all sizes.
STAF provides a means to store and retrieve variables. These variables may be used for any purpose the tester desires, such as storing testcase configuration parameters. These variables provide two main capabilities to testcase writers. One, they provide a standard means by which to store configuration data, i.e., each tester doesn't have to figure out how to store and retrieve said configuration data. Two, these variables may be changed dynamically. For example, if a testcase queries the WebServer variable before sending a request off to the web server, and that web server goes down, the WebServer variable can be dynamically changed by the tester to refer to a different web server, and the testcase can continue execution. Note how STAF allows the variable's value to be changed outside of the scope of the running testcase, thus allowing the testcase to continue execution without needing to be stopped and restarted.
STAF maintains a "system" variable pool that is common to all the processes on a given STAF Client. STAF also maintains a "shared" variable pool which is also system-wide, but which will be sent across the network and used in variable resolution on remote systems. In addition, each process/handle has its own variable pool. By default, the values of variables in a process' variable pool override the values of variables in the system and shared variable pools. However, the process may override this behavior when asking for the value of a variable. Basically, as part of every remote request, the originating handle and system shared variable pools are sent across the wire. These pools are stored only for the duration of the request for use in variable resolution.
The following system variables are predefined:
To substitute a variable's value, write the name of the variable in curly braces: "{STAF/Config/OS/Name}" is a valid reference to the variable STAF/Config/OS/Name. Assuming STAF/Config/OS/Name=Win2000, string "Operating system is {STAF/Config/OS/Name}" resolves to "Operating system is Win2000".
Variable references can be used in many places when submitting a STAF request. For example:
See section 8.19, "Variable (VAR) Service" for more information on setting and resolving variables.
Security in STAF can be defined at the machine level and/or the user level. In other words, you grant access to machines and/or to userids. Access in STAF is granted by specifying a certain trust level for a machine or user, where trust level 0 indicates no access and trust level 5 indicates all access. Each service in STAF defines what trust level is required in order to use the various functions the service provides.
A basic description of each level follows
In order to use user trust security in STAF, you must have at least one authenticator registered.
Note: The local machine can be granted a trust level by specifying interface "local" and a system identifier of "local".
User authentication overrides machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.
Each handle in STAF has a priority queue associated with it. This queue is used to accept/retrieve messages from other processes/machines. Each message in the queue has the following data associated with it.
STAF allows you to register to receive notifications for certain events, such as STAF starting and shutting down. These events will appear in the queue of the requesting process. They will reveal the originating handle as handle 1 of the originating machine, which is the reserved STAF Process handle.
The requests submitted to STAF and the results received from STAF are all strings. These strings may contain any arbitrary set of characters, including the NULL (i.e., 0) character. When working in an environment with a heterogeneous set of codepages, STAF will translate the request and result strings from and to the necessary codepages. This ensures that the request and result strings are not misinterpreted by the receiver.
In general, when using STAF services, there shouldn't be any round trip problems. "Round trip" in this context means when all requests are originating from the same system, even if the requests are sent to, and the data is stored on, a system with a different codepage. However, if you send, for example, a request to log data containing Japanese codepage specific characters to any system and then query the log from a system using a US English codepage, you won't get the "correct" data, as that is not a valid "round trip".
Note: All STAF generated strings are composed of only ASCII-7 characters and will safely survive the translation from/to different codepages.
If you need to specify non-ASCII characters in a request, then you need to be aware of some anomalies if your target system is a Windows system that isn't using an English codepage and whose ANSI codepage (ACP) identifier is different from the OEM codepage (OEMCP) identifier. The system locale determines which codepages are defaults for the Windows system. However, some European locales such as French and German set different values for the ACP and OEMCP. By default, STAF uses the OEM codepage when doing codepage translation. But, depending on where the data is input, it may be necessary to tell STAF to use the ANSI codepage. The ANSI codepage is used in the window manager and graphics device interface and by many applications. However, the Windows command line and bat files use the OEM codepage as they are interpreted by cmd.exe. You can use CHCP to display or change the codepage used by the command line. Note that these anomalies occur only on Windows systems.
To avoid these Windows codepage anomalies, you may need to change the codepage used by STAF using one of these methods:
Caution: You should NOT change the ACP value to the OEMCP value.
Note: To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage. For example:
STAF testmach1 VAR RESOLVE STRING {STAF/Config/CodePage}
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.
You can install STAF to a directory with an existing version of STAF already installed. In this case the installer will prompt you to decide if you want to do an upgrade installation. If you choose to do the upgrade installation, all of STAF files will be upgraded to the new version. Any files created after STAF was installed (e.g. additional services, log files, updated STAF.cfg, etc) will not be removed.
Note that if you are upgrading from a pre-V3.0 version of STAF, the installer will perform a silent uninstallation of the existing version of STAF, before proceeding with the upgrade installation.
When upgrading an existing version of STAF, it is recommended that you shutdown the existing version of STAF before beginning the upgrade installation.
You can have multiple versions of STAF installed on the same system (note that they must be installed to different installation directories).
The operating system must have IPv6 support to install a IPv6 enabled version of STAF.
If you select to have the support for IPv6 installed, but you do not have the machine configured with an IPv6 IP address, if you use the default STAF.cfg file, you will get an error "No supported IPv6 address" when starting STAF, and STAF will fail to start. This is because by default the TCP Connnection Provider will use the default (IPv4_IPv6) option for the PROTOCOL option. If you do not have an IPv6 IP address configured on the machine, you will need to see the PROTOCOL option to IPv4. See section 4.3.2, "STAFTCP Connection Provider" for more details on setting this option.
STAF provides the following two methods to install STAF on Windows. Both methods use InstallShield MultiPlatform 11.5:
java -jar STAF320-setup-win32.jar
STAF320-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 V3.x.x" 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 if you have more than one version of STAF installed on a machine, only the last installed version will be displayed in Add/Remove Programs. If you wish to uninstall the earlier versions, there is an "Uninstall STAF" icon in the Start Programs folder for that version of STAF. Note that if the earlier version is 2.6.5 or earlier, you will need to open a command prompt, go to the _uninst directory in the root install location, and run "uninstaller.exe". For STAF versions 2.6.6 or later, there will be an "Uninstall STAF" icon in the Start Programs folder for that version of STAF.
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.
If you need to install or uninstall the same STAF configuration multiple times or in multiple locations, you can bypass the InstallShield MultiPlatform 11.5 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:
STAF320-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept"or
java -Dis:debug=1 -jar STAF320-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 InstallShield MultiPlatform 11.5 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:
STAF320-setup-win32 -options-record settings.txt
To specify a response file for a silent STAF installation, issue the following command:
STAF320-setup-win32 -is:log c:\temp\ismplog.txt -silent -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:
STAF320-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. |
| -W setupTypes.selectedSetupTypeId= | "Typical" | Indicates the type of installation. The valid values are "Typical", "Full", and "Minimal". |
| -W stafOptions.updateEnvironmentVariables= | "System" | Indicates the type of environment variables and Windows menus to update. The valid values are "System", "User", and "None". |
| -W stafOptions.defaultIPvVersion= | "IPv4 only" | Indicates whether to install support for IPv4 only or for IPv4 and IPv6. The valid values are "IPv4 only" and "IPv4 and IPv6". |
For example, to do a silent installation of type "Mimimal", without updating environment variables, and with the support for IPv4 and IPv6:
STAF320-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept" -W setupTypes.selectedSetupTypeId="Minimal" -W stafOptions.updateEnvironmentVariables="None" -W stafOptions.defaultIPvVersion="IPv4 and IPv6"
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 InstallShield MultiPlatform 11.5 (for operating systems that are supported by InstallShield MultiPlatform 11.5).
java -jar STAF320-setup-xxxxx.jar
./STAF320-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 InstallShield MultiPlatform 11.5 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.):
bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept"or
java -Dis:debug=1 -jar STAF320-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 InstallShield MultiPlatform 11.5 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:
STAF320-setup-xxxxx.bin -options-record settings.txt
To specify a response file for a silent STAF installation, issue the following command:
STAF320-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -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:
STAF320-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= | "/usr/local/staf" | The directory in which STAF should be installed. |
| -W setupTypes.selectedSetupTypeId= | "Typical" | Indicates the type of installation. The valid values are "Typical", "Full", and "Minimal". |
| -W stafOptions.updateEnvironmentVariables= | "System" | Indicates the type of environment variables to update. The valid values are "System", "User", and "None". |
| -W stafOptions.defaultIPvVersion= | "IPv4 only" | Indicates whether to install support for IPv4 only or for IPv4 and IPv6. The valid values are "IPv4 only" and "IPv4 and IPv6". |
For example, to do a silent installation of type "Mimimal", without updating environment variables, and with the support for IPv4 and IPv6:
STAF320-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept" -W setupTypes.selectedSetupTypeId="Minimal" -W stafOptions.updateEnvironmentVariables="None" -W stafOptions.defaultIPvVersion="IPv4 and IPv6"
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 11.5, such as Linux IA-64, Linux AMD-64, z/OS, AS/400, 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 command. 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 STAF320-linux-ia64.tar.gz tar -xvf STAF320-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 STAF320-zos.tar.Z tar -xvf STAF320-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 | r | f >] [-verbose] [-warn]
[-ro <mode>] [-rx <mode>] [-rw <mode>] [-dp <mode>]
[-noreg | [-name <name>] [-email <email>] [-org <org>]]
[-acceptlicense] [-option name=value]...
-source specifes the directory in which the STAF files were untar'd. In our example above, this would be /tmp/STAF/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. If this option is not specified, softlinks to executables will not be created.
-lib specifies the directory where softlinks to libraries will be created. If this option is not specified, softlinks to libraries will not be created.
-type specifies the type of installation (the default is rs). Possible values are
-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.
-acceptlicense indicates that you accept the terms of the license agreement for this software. If not specified, the license agreement will be displayed at the beginning of the installation.
-option allows you to specify options for the installed components. The allowed name=value pairs are:
IMPORTANT! In order to start STAF or to use STAF, you must set some environment variables as described in section 3.10, "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, you would simply enter
./STAFInst -acceptlicense
To perform a recommended install of STAF into /usr/local/staf, and have softlinks placed into /usr/bin and /usr/lib, you would enter
./STAFInst -acceptlicense -bin /usr/bin -lib /usr/lib
To perform a minimum installation of STAF into /opt/staf, you would enter
./STAFInst -acceptlicense -target /opt/staf -type m
To perform a preview of a full STAF installation into the default /usr/local/staf, you would enter
./STAFInst -acceptlicense -type f -preview
To perform a default install of STAF and provide your name and e-mail address for registration, you would enter
./STAFInst -acceptlicense -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 -acceptlicense -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, "Upgrading/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>
For information on Linux operating system library compatability, see 3.13, "Operating System Library Compatability (Linux/Solaris)".
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.2, "JSTAF service proxy library".
Note: STAF will only run on OS/400 V5R2 or newer.
Follow these instructions to install STAF:
CALL QP2TERM
cd /QIBM/stafinst gunzip STAF320-as400.tar.gz tar xf STAF320-as400.tar cd staf . ./STAFInst -target /QIBM/staf -acceptlicense
Notes:
cd /QIBM/staf cp bin/STAF.cfg bin/STAF.cfg_save . ./STAFUninst cd /QIBM/stafinst/staf . ./STAFInst -target /QIBM/staf -acceptlicense cd /QIBM/staf cp bin/STAF.cfg_save bin/STAF.cfg
rm -Rf /QIBM/stafinst
Follow these instructions to start STAFProc:
CALL QP2TERM
cd /QIBM/staf . ./STAFEnv.sh
Running STAFEnv.sh should set the following environment variables needed to use STAF:
nohup STAFProc &
Note that the default shell for processes is /bin/sh. If you need to use the "qsh" shell for the OS/400 PASE environment, then you will either need to specify
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"You must shutdown and restart STAFProc for any changes to the STAF.cfg file to take effect.
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.5.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. However, if you are going to be running two or more versions of STAF on the same machine, the install creates STAFEnv script files that you can use to easily switch environment settings for each version of STAF. See section 5.1.1, "Running Multiple Instances of STAFProc" for more information on using the STAFEnv script files when running multiple instances of STAF on the same machine.
Please verify that the following environment variables have been set as follows before using STAF:
You can install different versions of STAF on the same machine in different locations. You can also run multiple instances of the same or different versions of STAF at the same time on a single machine. See section 5.1.1, "Running Multiple Instances of STAFProc" for more information on running multiple instances of STAF on a single machine.
If you have a problem while installing STAF, please check the STAF V3 FAQ, 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.10, "Environment Variable Settings"). Also, check the STAF V3 FAQ.
If you are getting an error such as "Error while loading shared libraries: libstdc++.so.6: cannot open shared object file: No such file or directory" when starting STAFProc on Linux or Solaris, then see 3.13, "Operating System Library Compatability (Linux/Solaris)".
Some platforms (Linux and Solaris) on which we build and provide STAF are linked to C++/GCC operating system libraries. In previous versions of STAF, these operating system library files were packaged/installed with STAF. However, these library files could cause some incompatibility issues with the operating system and other native applications. Starting in STAF V3.2.0, these library files will no longer be packaged/installed with STAF. However, in order to run STAF on these platforms, you will need these library files or compatible library files.
As a STAF user, what this means is that you may need to make some one-time setup/configuration changes on your test machine(s) in order to get STAF V3.2.0+ working correctly. There are several possible user scenarios:
Here are the affected operating systems and details about the specifc platforms
on which we build STAF:
| OS Name | STAF Installers | OS Details | Library file(s) |
|---|---|---|---|
| Linux IA32 | STAF32x-setup-linux.bin STAF32x-setup-linux.jar STAF32x-linux.tar.gz | Red Hat Linux release 8.0 (Psyche)
gcc version 3.4.0, GNU Make version 3.79.1 Linux 2.4.20-28.8 #1 Thu Dec 18 12:53:39 EST 2003 i686 i686 i386 GNU/Linux GNU C Library stable release version 2.3.2 Compiled by GNU CC version 3.2 20020903 (Red Hat Linux 8.0 3.2-7). Compiled on a Linux 2.4.9-9 system on 2003-11-05. | libstdc++.so.6 |
| Linux AMD64 | STAF32x-linux-amd64.tar.gz | Red Hat Enterprise Linux AS release 4 (Nahant Update 4)
gcc version 3.4.6 20060404 (Red Hat 3.4.6-3), GNU Make 3.80 Linux 2.6.9-42.ELsmp #1 SMP Wed Jul 12 23:32:02 EDT 2006 x86_64 x86_64 x86_64 GNU/Linux GNU C Library stable release version 2.3.4 Compiled by GNU CC version 3.4.6 20060404 (Red Hat 3.4.6-2). Compiled on a Linux 2.4.20 system on 2006-07-04. |
libstdc++.so.6
|
| Linux IA64 | STAF32x-linux-ia64.tar.gz | Red Hat Enterprise Linux AS release 3 (Taroon Update 6)
gcc version 3.2.3 20030502 (Red Hat Linux 3.2.3-53) Linux 2.4.21-20.EL #1 SMP Wed Aug 18 20:30:22 EDT 2004 ia64 ia64 ia64 GNU/Linux GNU C Library stable release version 2.3.2 Compiled by GNU CC version 3.2.3 20030502 (Red Hat Linux 3.2.3-53). Compiled on a Linux 2.4.20 system on 2005-09-16. |
libstdc++.so.5
|
| Linux PPC64 (32-bit Java support) | STAF32x-linux-ppc64-32.tar.gz | SuSE SLES-8 (PPC) VERSION = 8.1
gcc version 3.2.2 Linux 2.4.21-309-pseries64 #1 SMP Tue May 16 22:59:04 UTC 2006 ppc64 unknown GNU C Library stable release version 2.2.5 Compiled by GNU CC version 3.2.2. Compiled on a Linux 2.4.19 system on 2006-01-26. | libstdc++.so.5 |
| Linux PPC64 (64-bit Java support) | STAF32x-linux-ppc64-64.tar.gz | SUSE LINUX Enterprise Server 9 (ppc) VERSION = 9 PATCHLEVEL = 2
gcc version 3.3.3 (SuSE Linux) Linux 2.6.5-7.191-pseries64 #1 SMP Tue Jun 28 14:58:56 UTC 2005 ppc64 ppc64 ppc64 GNU/Linux GNU C Library stable release version 2.3.3 (20040412) Configured for ppc-suse-linux. Compiled by GNU CC version 3.3.3 (SuSE Linux). Compiled on a Linux 2.6.5 system on 2005-06-05. | libstdc++.so.5 |
| Solaris Sparc | STAF32x-setup-solaris-sparc.bin STAF32x-setup-solaris-sparc.jar STAF32x-solaris-sparc.tar.gz | SunOS 5.6
gcc version 2.95.3 20010315 (release) SunOS 5.6 Generic_105181-39 sun4u sparc SUNW,Ultra-2 |
libstdc++.so.2.10.0
|
STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF Configuration File is read and processed line by line. Whitespace at the front of the line is removed before processing. Blank lines, or lines containing only whitespace are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line. The maximum length for a line in the STAF Configuration File is 2048 characters. The various configuration statements are described in the following sections.
You may use variables for all the values of configuration statement options, with the exception of the SET VAR configuration statement itself. However, these variables must be either predefined STAF variables (see 2.4, "Variables") or be previously defined in the STAF Configuration File via the SET VAR configuration statement (see below).
You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.
# This is a comment line
You may specify a nickname for your machine using the MACHINENICKNAME configuration statement.
This allows you to override the machine nickname which is set to the value of the STAF/Config/Machine system variable by default. This primarily effects the data stored by services such as the Log and Monitor services, which store data based on the machine from which it came by using the STAF/Config/MachineNickname system variable as part of the directory path when creating logs and monitor data. By allowing the STAF/Config/MachineNickname system variable to be overridden, it allows you to better manage your data.
The machine nickname is not used to communicate with other systems and does not have any effect on trust.
This option is used in both connected and disconnected modes (e.g. disconnected mode is when you are not using a network interface).
MACHINENICKNAME <Nickname>
<Nickname> is the nickname you wish to use for your machine. It is case sensitive.
MACHINENICKNAME testmachine1 MACHINENICKNAME JohnDoe
You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement. The INTERFACE configuration statement registers connection providers (also called network interfaces, or interfaces for short).
INTERFACE <Name> LIBRARY <Implementation Library> [OPTION <Name[=value]>]...
<Name> is the name by which this network interface (aka Connection Provider) will be known on this machine.
LIBRARY is the name of the shared library / DLL which implements the network interface (aka Connection Provider). STAF V3.0.0 provides one connection provider that supports unencrypted TCP/IP communication. This is the same type of support that STAF V2.x supports. The implementation library for this connection provider is called STAFTCP.
OPTION specifes a configuration option that will be passed on to the shared library / DLL which implements the connection provider. You may specify multiple OPTIONs for a given connection provider. See 4.3.2, "STAFTCP Connection Provider" for acceptable options for the STAFTCP shared library / DLL.
INTERFACE tcp LIBRARY STAFTCP INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6600 INTERFACE serial LIBRARY STAFSER
The STAFTCP connection provider shared library / DLL supports unencrypted TCP/IP communication. STAF supports both IPv4 and IPv6. IPv6 is supported in the IPv6 enabled version of STAF.
The STAFTCP connection provider supports the following OPTIONs:
PORT=<Name> specifies the TCP/IP port on which this connection provider listens for connections. The default is 6500. All machines in the same STAF Environment must use the same port.
PROTOCOL=<Name> specifies the communication protocol that this connection provider uses. The possible values are IPv6, IPv4, or IPv4_IPv6. When this option is absent, the default is IPv4_IPv6 which indicates to use both IPv6 and IPv4 protocols. This option is only valid for IPv6 enabled versions of STAF.
CONNECTTIMEOUT=<Number> specifies the maximum time in milliseconds to wait for a connection attempt to a remote system to succeed. The default is 5000 (5 seconds). You may need to increase this value if you are consistently receiving return code 16 when trying to communicate with distant STAF systems. Note that the total time to wait for a connection to a remote system to succeed is (CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1)). If using the defaults, the maximum total time to wait for a connection to a remote system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds. The CONNECTATTEMPTS and CONNECTRETRYDELAY values are operational parameters that can be set in the STAF configuration file.
INTERFACE tcp LIBRARY STAFTCP INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6600 INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6700 OPTION PROTOCOL=IPv6 INTERFACE tcp4 LIBRARY STAFTCP OPTION CONNECTTIMEOUT=15000
External services are registered with the SERVICE configuration statement.
SERVICE <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
or
SERVICE <Name> DELEGATE <Machine> [TONAME <Remote Service Name>]
<Name> is the name by which this service will be known on this machine.
LIBRARY is the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, for a Java service, this might be the name of the Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See below for information regarding the JSTAF service proxy library. Otherwise, see the documentation provided by the service proxy library.
OPTION 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 JSTAF service proxy library. 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. This machine must be running STAF V3.0.0 or later.
Note: From a trust perspective, the tcp interface names on the "delegated to" service machine and on the machine delegating service requests to it must match or the trust statement for the machine that is delegating service requests must use a wildcard to match any interface.
TONAME is the name of the service on <Machine> to which the delegated requests will be sent. The default is the same name as specified with <Name>.
SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096"
SERVICE LOG LIBRARY STAFLog
SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\service\STAX.jar \
OPTION J2=-Xmx128m
SERVICE SAMPLEJ LIBRARY JSTAF EXECUTE C:\STAF\services\Sample.jar \
PARMS {STAF/Config/STAFRoot}\bin\sample.dft
SERVICE MYLOG DELEGATE TestSrv1
SERVICE PAGER DELEGATE pagesrv.austin.ibm.com
SERVICE EVENT DELEGATE EventSrv TONAME DB2EVENT
SERVICE NOTIFY LIBRARY Notify PARMS "24 Hours 7 Days"
SERVICE ZIP LIBRARY STAFZip
The library JSTAF acts as a proxy for STAF services implemented in the Java language. JSTAF works with Java 1.3 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/DataDir}/lang/java/jvm/<JVMName> directory and contain JVM start information such as the date/time when the JVM was started, the JVM executable, and the J2 options used to start the JVM. In addition, it contains any other information logged by the JVM, including any errors that may have occurred while the JVM was running. The current JVM log file is named JVMLog.1 and saved JVM log files, if any, are named JVMLog.2 to JVMLog.<MAXLOGS>. Note, this option is only valid for the first service created with a given JVMName.
MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the JVM log file(s). The default is 1048576 (1M). This option determines when to create a new JVM log file. When the JVM is started, if the size of a JVM log file exceeds the maximum size specified by this option, a new JVM log file will be created. Note, this option is only valid for the first service created with a given JVMName.
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 proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the service loader. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.
OPTION specifes a configuration option that will be passed on to the service loader library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service loader implementation. You may specify multiple OPTIONs for a given service loader. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the service loader during initialization.
SERVICELOADER LIBRARY STAFDSLS SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/services/CustomServiceLoader.jar
Authenticator services are registered with the AUTHENTICATOR configuration statement. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter.
AUTHENTICATOR <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
<Name> is the name by which this authenticator service will be known on this machine. The name cannot be "none" as this is reserved for use by STAF. If you want to authenticate across systems, you must register the authenticator on each system using the same name (case-insensitive).
LIBRARY is the name of the shared library / DLL which implements the authenticator service or acts as a proxy for the authenticator service. See the information for each authenticator to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the authenticator service. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.
OPTION specifes a configuration option that will be passed on to the shared library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given authenticator service. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the authenticator service during initialization.
AUTHENTICATOR MyAuth LIBRARY JSTAF EXECUTE C:/STAF/services/MyAuth.jar
AUTHENTICATOR AuthSample LIBRARY JSTAF \
EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
OPTION JVMName=Auth \
PARMS "UserPropertiesFile {STAF/Config/STAFRoot}/services/authsample.properties"
A sample authenticator service is provided by STAF and is available via the Download STAF website. It is called AuthSample and is available as a jar file called AuthSampleV300.jar.
To try out user trust, you can register the sample authenticator as follows (assuming you downloaded it to a services directory created in the STAF root directory).
AUTHENTICATOR AuthSample LIBRARY JSTAF \
EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/authsample.properties"
LIBRARY must be JSTAF for this sample authenticator as it is implemented in Java.
EXECUTE must be the fully-qualified name of the AuthSampleV300.jar file.
This sample authenticator has the following required parameter:
To perform user authentication across systems, the authenticator must be registered as the same name (case-insensitive) on all machines where you want to use user trust authentication and with the same user properties file (e.g. one that supports the same user identifiers and passwords).
An example of a user properties file is:
# User Properties File for the Sample Authenticator User1=Password1 User2=Password2 User3=Password3 User4=Password4 User5=Password5
You can specify any user identifiers and passwords that you want in a user properties file. However, do not specify any confidential information (e.g. any real passwords that you want to protect) as this information is not protected when sent over the network in STAF V3.0.0. In STAF V3.1, a secure TCP interface will be provided.
STAFProc allows you to set various parameters which affect the general operation of STAF. The SET configuration statement lets you set these general operational parameters.
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
[MAXQUEUESIZE <Number>]
[INITIALTHREADS <Number>] [THREADGROWTHDELTA <Number>]
[DATADIR <Directory Name>]
[INTERFACECYCLING <Enabled | Disabled>]
[DEFAULTINTERFACE <Name>]
[DEFAULTAUTHENTICATOR <Name>]
[ENABLEDIAGS]
[STRICTFSCOPYTRUST]
[RESULTCOMPATIBILITYMODE <Mode>]
[DEFAULTSTOPUSING <Method>]
[DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE]
[DEFAULTFOCUS <Background | Foreground | Minimized>]
[PROCESSAUTHMODE <Authentication Mode>]
[DEFAULTAUTHUSERNAME] [DEFAULTAUTHPASSWORD]
[DEFAULTAUTHDISABLEDACTION <Disabled Action>]
[DEFAULTSHELL <Shell>]
[DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
CONNECTATTEMPTS specifies the maximum number of times to attempt to connect to a remote system. The default is 2. Note that a trace warning message is generated for each failed attempt if the Warning trace point is enabled. You may also change this setting dynamically using the MISC service's SET command.
CONNECTRETRYDELAY specifies the maximum time in milliseconds to wait after a failed connection attempt to a remote system before trying to connect again (if the maximum number of times to attempt to connect to a remote system has not been reached yet). The default is 1000 (i.e., 1 second). You may also change this setting dynamically using the MISC service's SET command.
MAXQUEUESIZE specifies the maximum size of the queue associated with each process' handle. The default is 100. You may also change this setting dynamically using the MISC service's SET command.
INITIALTHREADS specifies the number of threads initially created to handle service requests. The default is 5.
THREADGROWTHDELTA specifies the number of additional threads which should be created when all existing threads are busy. The default is 1.
DATADIR specifies the directory that STAF and its services will use to write data. The default is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}. Note that this directory name must be unique per instance of STAFProc running on a single machine. Also, make sure to include the "SET DATADIR" line in the STAF configuration file at the beginning of the file, before any services are registered, since the data directory can be used during service registration. See 4.14, "Data Directory Structure" for more information about the STAF data directory and its contents.
INTERFACECYCLING specifies whether to enable or disable automatic interface cycling. The default is to enable automatic interface cycling. You may also change this setting dynamically using the MISC service's SET command. Recognized values are the following:
Note that automatic interface cycling only has an effect if there are multiple interfaces configured in the STAF configuration file on the machine that is submitting a STAF request. Also, note that the MISC service provides a LIST ENDPOINTCACHE request to show the cached endpoints and a PURGE ENDPOINTCACHE request to purge one or more cached endpoints.
DEFAULTINTERFACE specifies the name of the network interface (aka connection provider) to use, by default. If not specified, the first interface registered is the default. You may also change this setting dynamically using the MISC service's SET command.
DEFAULTAUTHENTICATOR specifies the name of the Authenticator to use, by default. If not specified, the first Authenticator registered is the default. If no authenticators are registered, the default authenticator is none. You may also change this setting dynamically using the MISC service's SET command.
ENABLEDIAGS specifies to enable diagnostics. The default is to disable diagnostics. You may also enable (or disable) recording diagnostics dynamically using the DIAG service.
STRICTFSCOPYTRUST specifies to enable strict trust checking when copying a file or directory using the FS service. The default is to disable strict trust checking (e.g. do lenient trust checking) on a FS COPY request when the machine submitting the request is the same as the machine where which the file/directory is being copied. That is, STRICTFSCOPYTRUST specifies that a trust check should be done to verify that MachineA trusts MachineB when MachineA submits a COPY request to the FS service on MachineB to copy a file or directory back to MachineA. The default is to do lenient trust checking so that MachineA does not have to trust MachineB since why would MachineA ask MachineB to copy the file/directory if he didn't want the copy to work. You may also change this setting dynamically using the FS service's SET command.
RESULTCOMPATIBILITYMODE specifies the compatibility mode used when sending the result from a STAF service request back to a pre-STAF V3 system. Recognized values are the following:
DEFAULTSTOPUSING allows you to specify the default method used to STOP processes. See 8.11.3, "STOP" for more information on available methods. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTNEWCONSOLE specifies that processes should be STARTed in a new console window. This is the default for Windows systems. This option has no effect on Unix systems. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTSAMECONSOLE specifies that processes should be STARTed in the same console as STAFProc. This is the default on Unix systems. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTFOCUS specifies the focus that is to be given to new windows opened when starting a process on a Windows system. The default focus mode is Background. This option only has effect on Windows systems. This option will resolve variables. See 8.11.2, "START" for more information on the FOCUS option. You may also change this setting dynamically using the PROCESS service's SET command.
PROCESSAUTHMODE specifies the mode by which usernames/passwords are authenticated when starting processes. The value of this option is platform specific. Recognized values are the following:
Note: Previously, PASSWD and SHADOW were supported values for the PROCESSAUTHMODE on Unix systems, but support for for these modes has been removed.
You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHUSERNAME specifies the username under which processes will be started, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHPASSWORD specifies the password with which processes will be authenticated, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHDISABLEDACTION specifies what default action should be taken if the user specifies a username/password on a request to start a process when process authentication has been disabled. The following values are recognized:
DEFAULTSHELL specifies the default shell to use when starting a process via a separate shell. The default shell used for Unix systems is /bin/sh. The default shell used for Windows NT/2000/XP/2003/Vista systems is "cmd.exe /c". The default shell used for Windows 95/98/ME systems is "command.com /c". You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTNEWCONSOLESHELL specifies the default shell to use when starting a process in a new console window (e.g. NEWCONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTSAMECONSOLESHELL specifies the default shell to use when starting a process in the same console as STAFProc (e.g. SAMECONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.
A shell value can contain substitution characters described in the following table.
Table 4. Substitution Characters for Shells
| Substitution character | Description | Supported systems |
|---|---|---|
| %c | Substitute the values specified by the COMMAND and PARMS options. | Windows and Unix |
| %C | Same as %c, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %p | Substitute the value specified by the PASSWORD option, or an empty string if no PASSWORD is provided. | Windows and Unix |
| %P | Same as %p, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %t | Substitute the value specified by the TITLE option, or <Unknown> if no TITLE is provided. | Windows and Unix |
| %T | Same as %t, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %u | Substitute the value specified by the USERNAME option, or an empty string if no USERNAME is provided. | Windows and Unix |
| %U | Same as %u, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %w | Substitute the value specified by the WORKLOAD option, or <Unknown> if no WORKLOAD is provided. | Windows and Unix |
| %W | Same as %w, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %x | Substitute the values specified by the COMMAND and PARMS options followed by input/output redirection, if I/O options are specified on the PROCESS START request (e.g. STDIN, STDOUT). When using this option, do not specify any redirection in the COMMAND/PARMS values. | Windows and Unix |
| %X | Same as %x, except the substituted value will be quoted (with all nested quotes properly escaped). | Windows and Unix |
| %% | Substitute a %. | Windows and Unix |
Notes:
SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2000 SET MAXQUEUESIZE 1000 SET INITIALTHREADS 10 THREADGROWTHDELTA 3 SET DATADIR /test/stafdata SET DEFAULTINTERFACE tcp SET DEFAULTAUTHENTICATOR SampleAuth SET ENABLEDIAGS SET RESULTCOMPATIBILITYMODE none SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE SET DEFAULTFOCUS minimized SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C" SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C" SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X" SET DEFAULTSHELL "su - %u -c %C"
You may set STAF variables in the system or shared variable pool at startup by using the SET VAR configuration statement. SET VAR will set a variable to a certain value. The variable is created if it does not exist.
Note that you may SET multiple variables with a single request.
SET [SYSTEM | SHARED] VAR <Name=Value> [VAR <Name=Value>] ...
SYSTEM means the variable is to be set in system variable pool. This is the default.
SHARED means the variable is to be set in shared variable pool.
VAR means the variable to be set. Name is the name of the variable and Value is the value of the variable.
SET VAR WebServer=testsrv1.test.austin.ibm.com
SET SHARED VAR "Author1=Jane Tester" VAR "Author2=John Tester"
SET SYSTEM VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
You may grant access to machines or users by using the TRUST configuration statement.
Trust configuration statements for machines are based on the network identification of the system. In particular, different trust levels can be given to the same system coming in through different networking interfaces. Both logical and pysical identifiers may be used in trust configuration statements for machines.
Trust configuration statements for users require that you have an authenticator registered.
TRUST LEVEL <Level> < DEFAULT | MACHINE <Machine> [MACHINE <Machine>]... |
USER <User> [USER <User>]... >
LEVEL is the level of trust that you wish to grant, see 2.5, "Security" for a list of trust levels.
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. The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).
Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.
Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)
USER indicates a user for which to set a trust level. The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
If multiple trust specifications would match the same user, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
If multiple trust specifications would match the same system, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
Note: The user authentication overrides the machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.
TRUST DEFAULT LEVEL 3 TRUST LEVEL 5 MACHINE local://local TRUST LEVEL 5 MACHINE client1.austin.ibm.com MACHINE client3.raleigh.ibm.com TRUST LEVEL 5 MACHINE 9.3.224.16 TRUST LEVEL 4 MACHINE tcp://mysystem.site.com TRUST LEVEL 0 MACHINE badguy.austin.ibm.com TRUST LEVEL 3 MACHINE tcp2://9.3.224.* TRUST LEVEL 2 MACHINE *.austin.ibm.com TRUST LEVEL 2 MACHINE tcp*://*.site.com TRUST LEVEL 5 USER John@company.com USER Jane@company.com TRUST LEVEL 0 USER badguy@company.com TRUST LEVEL 3 USER *@company.com TRUST LEVEL 4 USER SampleAuth://*@company.com TRUST LEVEL 1 USER *://*
You may specify that you want notifications sent to certain machines/processes when STAF is either started or shutdown. You do this by using the NOTIFY configuration statement. Notifications are handled by the STAF Queue service, see 8.12, "Queue Service" for more information.
Note: You may also dynamically register for SHUTDOWN notifications via the SHUTDOWN service, see 8.16, "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 type of the message will be the string STAF/Start with a blank message.
ONSHUTDOWN indicates that a notification should be sent when STAF is shutdown. The type of the message will be the string STAF/Shutdown with a blank message.
MACHINE indicates the machine to receive the message.
PRIORITY indicates the priority of the message. The default is 5.
NAME specifies that all processes with the given registered name on the given machine should be notified. This option is usually preferred over HANDLE, as it is difficult to know the desired handle in advance.
HANDLE specifies that the process with the given handle on the given machine should be notified.
NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager
STAF provides various tracing facilities to help in auditing and debugging. STAF externalizes these facilities through trace points. Enabling a particular trace point causes trace messages to be generated whenever a particular event occurs, such as a service request resulting in an "Insufficient Trust Level" (aka "Access Denied") error code. Care should be taken when enabling trace points, as certain trace points, such as ServiceResult, can lead to large quantities of trace messages being generated. In these cases, it is best to limit tracing to only specific services.
You may enable or disable STAF trace points and STAF services for tracing using the TRACE configuration statement. In addition, you can set the trace output destination and set the default tracing state for newly registered services. By default, all STAF services are enabled for tracing. Also, if you are using the default STAF configuration file provided, only the ERROR and DEPRECATED trace points are enabled by default.
Note: The TRACE ENABLE/DISABLE SERVICE(S) statements effect the current list of services. So, if you add line TRACE DISABLE ALL SERVICES to the configuration file and then register any external services later in the configuration file, those services will not necessarily be disabled. To ensure that all registered services are disabled, either set the default service state to disabled, or add the TRACE statements after the SERVICE configuration statements in the configuration file.
TRACE ENABLE ALL [ TRACEPOINTS | SERVICES ] TRACE ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> TRACE ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... TRACE ENABLE SERVICE <Service> [SERVICE <Service>]... TRACE DISABLE ALL [ TRACEPOINTS | SERVICES ] TRACE DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> TRACE DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... TRACE DISABLE SERVICE <Service> [SERVICE <Service>]... TRACE SET DESTINATION TO < STDOUT | STDERR | FILE <File name> > TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled>
See the TRACE service, section 8.17, "Trace Service", for information on the above options.
See table 8.17.2, "Trace Points Reference" for a list of valid trace points.
TRACE SET DESTINATION TO STDERR
TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc
TRACE ENABLE ALL
TRACE DISABLE SERVICE "Sem"
TRACE ENABLE TRACEPOINTS "Error ServiceAccessDenied"
TRACE DISABLE SERVICES "Process Queue Var"
TRACE SET DEFAULTSERVICESTATE Enabled
In order to ensure that you are only tracing service results on the var and sem services, and that tracing for all other services is disabled (including services registered in the future) do this :
TRACE SET DEFAULTSERVICESTATE Disabled TRACE DISABLE ALL SERVICES TRACE DISABLE ALL TRACEPOINTS TRACE ENABLE TRACEPOINTS "ServiceResult" TRACE ENABLE SERVICES "VAR SEM"
This is the default configuration file provided with STAF.
# Turn on tracing of internal errors and deprecated options trace enable tracepoints "error deprecated" # Enable TCP/IP connections interface tcp library STAFTCP # Set default local trust trust machine local://local level 5 # Add default service loader serviceloader library STAFDSLS
Warning: This configuration file contains references to fictional services, machines, etc. and is provided for informational purposes only. Please do not try to use this as your actual STAF.cfg file. It is unlikely to work.
# ---------------------------------------------------------------------
# STAF Configuration File
# ---------------------------------------------------------------------
# Set the writeable location where STAF can write data
SET DATADIR E:\test\stafdata
# Enable TCP/IP connections
interface tcp library STAFTCP option ConnectTimeout=10000
# Set default local trust
trust machine local://local level 5
# Add default service loader
serviceloader library STAFDSLS
# ---------------------------------------------------------------------
# STAF Log Mask Variable
# ---------------------------------------------------------------------
SET SHARED VAR STAF/Service/Log/Mask="START STOP WARNING FATAL ERROR"
# ---------------------------------------------------------------------
# Setup Trust Levels
# ---------------------------------------------------------------------
TRUST DEFAULT LEVEL 2
TRUST LEVEL 3 MACHINE test1.austin.ibm.com MACHINE test2.test.austin.ibm.com
TRUST LEVEL 5 MACHINE automate.austin.ibm.com
TRUST LEVEL 4 MACHINE *.test.austin.ibm.com
TRUST LEVEL 3 USER IBM://*@us.ibm.com
TRUST LEVEL 4 USER JohnDoe@company.com
TRUST LEVEL 0 USER BadGuy@company.com
# ---------------------------------------------------------------------
# Delegated Services
# ---------------------------------------------------------------------
SERVICE pager DELEGATE globpager.test.austin.ibm.com
# ---------------------------------------------------------------------
# Java Services
# ---------------------------------------------------------------------
# Operating system independent name for my STAF services directory
SET SYSTEM VAR myServiceDir={STAF/Config/STAFRoot}{STAF/Config/Sep/File}services
SERVICE STAX LIBRARY JSTAF \
EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAX.jar \
OPTION J2=-Xms64m OPTION J2=-Xmx128m
SERVICE Event LIBRARY JSTAF \
EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAFEvent.jar
# ---------------------------------------------------------------------
# C++ Services
# ---------------------------------------------------------------------
SERVICE log LIBRARY STAFLog
SERVICE monitor LIBRARY STAFMon
SERVICE respool LIBRARY STAFPool
# ---------------------------------------------------------------------
# Notifications
# ---------------------------------------------------------------------
NOTIFY ONSTART MACHINE automate.austin.ibm.com PRIORITY 3 NAME EventManager
NOTIFY ONSHUTDOWN MACHINE automate.austin.ibm.com NAME EventManager
# ---------------------------------------------------------------------
# Activate tracing
# ---------------------------------------------------------------------
TRACE SET DESTINATION TO FILE {STAF/DataDir}/user/STAF.trc
TRACE ENABLE TRACEPOINTS "ServiceAccessDenied Error"
TRACE ENABLE SERVICES "Process Trust"
STAF provides a way to tune its thread stack size. This is done via setting a "STAF_THREAD_STACK_SIZE" environment variable before STAFProc gets started. User can use this environment variable to set STAF's thread stack size in kilobytes.
On Unix: export STAF_THREAD_STACK_SIZE=128 On Windows: set STAF_THREAD_STACK_SIZE=128
By default, STAF and its services will write data to: {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}. For example: C:\STAF\data\STAF on Windows systems or /usr/local/staf/data/STAF on Unix systems. The STAF/DataDir system variable is set to the fully-qualified name of this directory.
You may use the DATADIR operational parameter to change the writeable data directory for STAF. This directory name must be unique per instance of STAF running on a single machine.
Note that the ability to change the data directory allows you to install STAF to a shared location (e.g. a read-only directory that is accessible via a mounted drive, etc.) and use a unique writeable data directory per instance of STAF.
The following table describes the structure of the STAF data directory:
Table 5. Data Directory Structure
| Directory Name | Description |
|---|---|
| {STAF/DataDir}/tmp | This is the location where temporary data can be stored. This directory and all of its contents will be removed and an empty tmp directory is created whenever STAFProc is restarted. |
| {STAF/DataDir}/user | Other user data (e.g. from testcases, applications, etc.) can be stored in this directory. You should create subdirectories within this directory to when storing your data. |
| {STAF/DataDir}/service | This directory exists if one or more external services are (or have been) registered.
If a service stores persistent data, it should create a subdirectory within this
directory using its registered service name (in lower-case) and store its data in this
subdirectory. For example:
{STAF/DataDir}/service/event
{STAF/DataDir}/service/log
{STAF/DataDir}/service/stax
|
| {STAF/DataDir}/lang/java/jvm | This directory exists if one or more external Java services are (or have been) registered.
For each JVM created for Java services, STAF will create a subdirectory within this
directory using the name of the JVM. The log files for the JVM (e.g. JVMLog.1)
will be stored in this subdirectory. For example:
{STAF/DataDir}/lang/java/STAFJVM1/JVMLog.1
{STAF/DataDir}/lang/java/STAX/JVMLog.1
|
| {STAF/DataDir}/lang/java/service | This directory exists if one or more external Java services are (or have been) registered.
For each Java service registered, STAF will create a subdirectory within this
directory using the registered service name and a subdirectory with it named jars.
This subdirectory will contain nested jar files for the service, if any are provided
by the service. For example:
{STAF/DataDir}/lang/java/service/Event/jars
{STAF/DataDir}/lang/java/service/STAX/jars
|
| {STAF/DataDir}/register | For STAF's use only. This directory is used for storing registration data, if any, specified when this version of STAF was installed. |
STAFProc is what starts STAF running on a machine.
STAFProc [STAF Configuration File]
STAFProc d:\staf\bin\mystaf.cfg
If [STAF Configuration File] is not specified, STAFProc will try to use the file staf.cfg. It will search for this file in the current directory, as well as the directory in which STAFProc resides.
Warning: In order to stop the STAFProc daemon process, you should enter the command "STAF local shutdown shutdown" (or use the associated program in your "Start" menu on Windows systems). Pressing CTRL-C (or issuing a "kill" command) will terminate STAFProc, but will not allow it to properly cleanup, which may cause problems and/or delays when trying to restart STAFProc. See section 8.16, "Shutdown Service" for more information on the SHUTDOWN service.
Note: Any changes made to the STAF Configuration File after STAFProc has been started will not take effect until you shutdown and restart STAFProc.
Multiple instances of STAFProc can be run at the same time on the same system . This makes it possible to use STAF to install/upgrade STAF itself. To run multiple instances of STAF, system-specific resources need to be differentiated. There is a special environment variable, STAF_INSTANCE_NAME, that can be used to specify a name for each STAFProc instance to differentiate between multiple instances of STAF. If this environment variable is not set, the default value, "STAF", is used for the instance name. If the STAF_INSTANCE_NAME environment variable is not set to a unique value prior to starting a new instance of STAFProc, you will see a "STAFProc already started" error.
For each instance of STAFProc running on a system, the following settings must be unique:
The ports used by STAF TCP connection providers must be unique, otherwise, you'll get a "Error starting tcp interface" error when starting STAFProc. If one instance of STAF is running using a tcp interface with default port 6500, then to start another instance of STAF that also uses a tcp interface, you must specify a different port in its STAF configuration file. For example:
interface tcp library STAFTCP option port=6501
Each STAFProc instance must use a different data directory. However, since the default setting for the data directory is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}, the data directory names will be different if they are not overridden using the DATADIR operational setting (and as long as the STAF_INSTANCE_NAME environment variable is set to a unique value). If the data directory for a STAFProc instance is not unique, you'll get a "Data directory is already in use" error when starting STAFProc
The installer creates a STAFEnv script file in the root STAF install location that can be used to set the required environment variables for a version of STAF. On Windows, the script file is called STAFEnv.bat and on Unix, the script file is called STAFEnv.sh. The STAFEnv script files are especially useful if you are going to be running two versions of STAF on the same machine and need a convenient way to switch settings for each version of STAF. An optional argument specifying the STAF instance name can be passed to a STAFEnv script file. A similar STAFEnv script file will also be created for setting up the environment for STAF V2, if STAF V2 is installed on the same machine as STAF V3.
Here's a sample STAFEnv.bat file for Windows:
@echo off REM STAF environment variables for 3.0.2 set PATH=C:\STAF\bin;%PATH% set CLASSPATH=C:\STAF\bin\JSTAF.jar;C:\STAF\samples\demo\STAFDemo.jar;%CLASSPATH% set STAFCONVDIR=C:\STAF\codepage if "%1" EQU "" set STAF_INSTANCE_NAME=STAF if "%1" NEQ "" set STAF_INSTANCE_NAME=%1
Here's a sample STAFEnv.sh file for Linux:
#!/bin/sh
# STAF environment variables for 3.0.2
PATH=/usr/local/staf/bin:$PATH
LD_LIBRARY_PATH=/usr/local/staf/lib:$LD_LIBRARY_PATH
CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar:$CLASSPATH
STAFCONVDIR=/usr/local/staf/codepage
if [ $# = 0 ]
then
STAF_INSTANCE_NAME=STAF
else
STAF_INSTANCE_NAME=$1
fi
export PATH LD_LIBRARY_PATH CLASSPATH STAFCONVDIR STAF_INSTANCE_NAME
The sample scripts that are created automatically by STAF will use the actual install directories in the STAFEnv script files.
Here's an example of starting STAF V2 and STAF V3 on a Windows system, where STAF V2 is installed in C:\STAF and STAF V3 is installed in C:\STAF3. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.
C: cd \STAF STAFEnv.bat STAFProcIn another command prompt:
C: cd \STAF3 STAFEnv.bat STAFProc
Here's an example of starting two instances of STAF V3 on a Unix system, specifying instance name STAF (the default) for one instance and instance name STAF2 for another instance. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.
cd /usr/local/staf . ./STAFEnv.sh STAFProc /usr/local/staf/bin/STAF.cfg & . ./STAFEnv.sh STAF2 STAFProc /usr/local/staf/bin/STAF2.cfg &
Note: The STAF_INSTANCE_NAME environment variable must be set to the same value for a given STAFProc daemon and any applications/testcases that want to communicate to the instance of STAF.
On Windows Vista with UAC (User Account Controls) enabled, STAFProc is run using the least amount of privileges (e.g. that of a standard user) even if you are logged in as an administrator. If you want to run a process via the STAF PROCESS START request that requires administrative privileges, such as an install program, and not get UAC prompts, you may need to run STAFProc as an administrator. There are several ways to do this:
Note: When STAFProc.exe is run as an administrator, you must also run STAF.exe as an administrator if you want to submit local STAF requests from a command prompt on the local Windows Vista machine. Otherwise, you'll get "Error registering with STAF, RC: 21".
STAF is an executable that is used to submit requests to STAF from the command line. Please see "Using the STAF command from shell-scripts" for more information on using the STAF command from within shell-scripts.
STAF [-verbose] <Endpoint> <Service> <Request>
[<Interface>://]<System Identifier>[@<Port>]where:
STAF local PING PING STAF local sem event SynchSem post STAF testmach1 PROCESS START COMMAND notepad STAF testmach1.company.com PROCESS LIST STAF -verbose testmach1.company.com PROCESS LIST STAF tcp://testmach1 TRUST LIST STAF alt-tcp2://9.3.283.13 SERVICE LIST STAF testmach1@6600 PROCESS START COMMAND notepad NOTIFY ONEND STAF tcp://testmach.company.com@6500 MISC WHOAMI STAF local ECHO ECHO "Hi there" STAF 9.3.823.20 LOG MACHINE LOGNAME MyLog LEVEL info MESSAGE "This is a message" STAF local var set SYSTEM var "SomeName=Some text string"
set STAF_INSTANCE_NAME=MySTAF staf local ping ping
On a successful STAF request (i.e., a request with a zero return code), the output from the STAF command will be as follows
Response -------- <Result string>
where <Result string> is any information that was returned from the STAF service request.
For example, the output of STAF LOCAL PING PING should be
Response -------- PONG
On an unsuccessful STAF request (i.e., a request with a non-zero return code), the output from the STAF command will be as follows
Error submitting request, RC: <Return code> Additional info --------------- <Result string>
where <Return code> is the actual return code from the request, and <Result string> is any information returned from the request. <Result string> usually contains information that explains why the error occurred. Note, the "Additional info" will only be present if a non-empty result string was returned. Additionally, you may refer to Appendix A, "API Return Codes" for information about the <Return code>
For example, the output of STAF LOCAL SEM LIST should be
Error submitting request, RC: 7 Additional info --------------- You must have at least 1, but no more than 1 of the option(s), MUTEX EVENT
Note: If the <Result string> from a STAF command contains any null characters, you can set the environment variable STAF_REPLACE_NULLS to any non-empty value. This will cause the STAF command to replace any null characters in the <Result string> with the specified value. Otherwise, the <Result string> will be truncated at the first null character found.
When structured data (see 6.1, "Marshalling Structured Data") is returned in the result strings above, the STAF command will automatically unmarshall the data and print it in the most appropriate format. If the data is a <List> of <String>, then each entry in the list will be printed on its own line. For example,
C:\> staf local fs list directory c:\ Response -------- AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT
If the data is a <Map> (or <Map:<Class>>) which has values which are all of type <String>, then each key/value pair will be printed on its own line. For example,
C:\> staf local monitor list settings Response -------- Max Record Size : 1024 Resolve Message : Disabled Resolve Message Var: Disabled
The above two types of formatted output are frequently referred to as "default format".
If the data is a <List> of <Map:<Class>> where every item in the list is an instance of the same map class, then the data will be printed out in a tabular format, called "table format". For example,
$ staf local handle list handles Response -------- Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20040929-13:57:40 2 STAF/Service/STAFServiceLoader1 InProcess 20040929-16:06:47 5 STAF/Service/LOG InProcess 20040929-13:57:52 7 STAF/Service/RESPOOL InProcess 20040929-13:58:04 51 STAF/Service/MONITOR InProcess 20040929-16:06:47 57 STAF/Client Registered 20040929-16:09:35
The column headings in the table format are determined using the display name specified for each key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.
By default a single record in the table format will only display the first 20 lines (the last line will show "(More...)" to indicate that there were more lines in the record). You can override the maximum number of lines that are displayed per record by setting the environment variable STAF_TABLE_LINES_PER_RECORD to the maximum number of lines.
You can disable the output of tables by setting the environment variable STAF_PRINT_NO_TABLES to any value. If you disable the output of tables, their data will show up in the more verbose mode (described below).
If the data is more complex than the above (or tables have been turned off), the output will be printed in a hierarchical nested format, called "verbose format". The best way to describe it is with an example.
C:\> staf local sem query event Test
Response
--------
{
State : Reset
Last Posted: {
Machine : crankin3
Handle Name: STAF/Client
Handle : 62
User : none://anonymous
Date-Time : 20040929-16:20:56
}
Last Reset : {
Machine : crankin3
Handle Name: STAF/Client
Handle : 65
User : none://anonymous
Date-Time : 20040929-16:21:43
}
Waiters : [
{
Machine : crankin3
Handle Name: TestHandle
Handle : 67
User : none://anonymous
Date-Time : 20040929-16:22:16
}
]
}
You can change the amount of indentation used by setting the environment variable STAF_INDENT_DELTA to any non-negative integer.
You can use the -verbose option to force the use of the verbose mode on a command basis. For example,
C:\> staf -verbose local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
You can force the exclusive use of the verbose mode by setting the environment variable STAF_PRINT_MODE to "verbose". For example,
C:\> set STAF_PRINT_MODE=verbose C:\> staf local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
If you should ever need to get at the raw result string (instead of the structured output), you can set the environment variable STAF_PRINT_MODE to "raw". For example,
C:\> set STAF_PRINT_MODE=raw
C:\> staf local fs list directory C:/temp/docs
Response
--------
@SDT/*:267:@SDT/{:26::13:map-class-map@SDT/{:0:@SDT/[10:218:@SDT/$S:11:STAFTcl.h
tm@SDT/$S:12:STAFPerl.htm@SDT/$S:14:STAFPython.htm@SDT/$S:7:History@SDT/$S:12:ST
AFCMDS.htm@SDT/$S:11:STAFFAQ.htm@SDT/$S:10:STAFGS.pdf@SDT/$S:12:STAFHome.htm@SDT
/$S:10:STAFRC.htm@SDT/$S:10:STAFUG.htm
Note, by default, any <String> value that looks as though it, itself, is a marshalled data structure will be recursively unmarshalled. For example, if someone marshalls a data structure and uses the resultant string as the message for a log request, and then you query the log, the data structure in the log message string will automatically be unmarshalled. If you want to turn off this behavior from the command line, and, instead, see the marshalled string in the message, set the environment variable STAF_IGNORE_INDIRECT_OBJECTS to any value.
There are two special environment variables that can be used to make the STAF command blend in with shell-scripts. The first is STAF_QUIET_MODE. Setting this environment variable to any non-null value will cause the STAF command to only output the <Result string> that the request generated. For example, the "STAF local ping ping" command above would simply return
PONG
This makes it easy to call STAF from shell-scripts. For example,
export STAF_QUIET_MODE=1 STAFResult=`STAF local ping ping` if [ $? -ne 0 ]; then echo "Non-zero return code from ping request"; elif [ "$STAFResult" != "PONG" ]; then echo "Expected PONG, received $STAFResult"; else echo "ping request succeeded" fi
The second environment variable is STAF_STATIC_HANDLE. If this environment variable is set, the STAF command will use the handle number indicated by this environment variable. This ensures that the shell-script can use the same handle throughout its execution. You may obtain a static handle in one of two ways. The first is using the CREATE command of the HANDLE service (see 8.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 supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure.
STAF supports the following generic data types with its marshalling.
Most languages support some form of the None, String, List, and Map data types. However, a map class and a marshalling context are likely new concepts.
A map class is really just a specialized map that is associated with a map class definition. The map class definition is used to reduce the size of a marshalling map class in comparison to a map containing the same data. It also contains information about how to display instances of the map class. A map class definition contains for following information for each key defined for a map class:
You indicate that a map is an instance of a map class by setting the key "staf-map-class-name" to the name of the map class. And, when you unmarshall a data structure, if you see that a map has a key called "staf-map-class-name", you know that the map is really an instance of a map class. You get and set map class definitions using a marshalling context.
A marshalling context is simply a container for map class definitions and a data structure that uses (or is defined in terms of) them. In order to use a map class when marshalling data, you must add the map class definition to the marshalling context, set the root object of the marshalling context to the object you want to marshall, and then marshall the marshalling context itself. When you unmarshall a data structure, you will always receive a marshalling context. Any map class definitions referenced by map classes within the data structure will be present in the marshalling context.
When a string is unmarshalled into a data structure, it is possible that one of the string objects that is unmarshalled is itself the string form of another marshalled data structure. By default, STAF will recursively unmarshall these nested objects. However, each language has a way to disable these additional processing.
STAF externalizes six primary APIs to C/C++ programs. These APIs allow you to register/unregister with STAF, submit service requests, and free the memory associated with service request results. In addition, STAF provides a wide range of APIs for defining, manipulating, and marshalling data structures. Also, STAF provides some APIs for handling private data.
Note: STAF-enabled programs written in C must be linked with the C++ compiler (or by using any other means which allows the C++ runtime to get initialized). Otherwise, the C++ runtime won't get a chance to initialize so the STAF static data doesn't get initialized. Most systems require mixed C and C++ code to get linked by the C++ compiler.
The STAFRegister call is used by a C program to register with STAF.
STAFRC_t STAFRegister(char *handleName, STAFHandle *handle)
handleName points to the name by which you want this handle to be known.
handle is a pointer to the STAFHandle that will be set on successful return from the function. You will use this handle on all other subsequent STAF calls.
char *myName = "MyProgram"; STAFHandle_t myHandle = 0; STAFRC_t rc = STAFRegister(myName, &myHandle);
The STAFRegisterUTF8 API is identical in all respects with STAFRegister, except that handleName is a string in UTF-8 format. This API is used primarily by the Java interfaces.
The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.
STAFRC_t STAFUnRegister(STAFHandle handle)
handle is the handle that you received on the call to STAFRegister.
/* myHandle was previously set by STAFRegister */ STAFRC_t rc = STAFUnRegister(myHandle);
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
STAFRC_t STAFSubmit(STAFHandle handle, char *where, char *service,
char *request, unsigned int requestLength,
char **resultPtr, unsigned int *resultLength);
handle is the handle you received on the call to STAFRegister.
where points to a string containing the destination machine for the service request. This should be either LOCAL or the name of a machine.
service points to the name of the service to which you are submitting the request.
request points to the actual request that you are sending to the service. This request may contain NULL (0x00) bytes.
requestLength indicates the length of the request buffer passed in.
resultPtr points to a char * that will contain the address of the result on return from the function. If, on return from STAFSubmit, *resultPtr is not 0, you must use STAFFree to free the result, even if the return code from STAFSubmit was non-zero. Note, if resultPtr is non-zero, then the buffer that resultPtr points to will always be NULL terminated. However, this buffer may contain NULL (0x00) bytes, therefore, it is not safe to determine the length of the buffer via strlen(). Instead, you should use the length provided by resultLength below.
resultLength points to an unsigned int which, on return from STAFSubmit, will contain the length of the result buffer.
/* myHandle was previously set by STAFRegister */
char *someMachine = "testmach1";
char *service = "PING";
char *request = "PING";
unsigned int requestLength = strlen(request);
char *result = 0;
unsigned int resultLength = 0;
STAFRC_t rc = 0;
rc = STAFSubmit(myHandle, someMachine, service, request, requestLength,
&result, &resultLength);
The STAFSubmit2 API is identical to the STAFSubmit API except that it has an additional parameter, syncOption, which allows submission of asynchronous requests.
STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption,
char *where, char *service,
char *request, unsigned int requestLength,
char **resultPtr, unsigned int *resultLength)
syncOption can be any of the following:
The format of the queued message obtained when specifying kSTAFReqQueue or
kSTAFReqQueueRetain will be a marshalled <Map:STAF/RequestComplete>
which represents the request completion information. See table
Table 6 for the map class definition.
Table 6. Definition of map for "STAF/RequestComplete" type message
| Description: This map represents STAF/RequestComplete message information. | ||
| Key Name | Type | Format / Value |
|---|---|---|
| requestNumber | <String> |
|
| rc | <String> |
|
| result | <String> |
|
For example, if you submitted the request "RESOLVE STRING {STAF/Config/OS/Name}" to the VAR service using kSTAFReqQueue, and received a request number of 42, then the message you would receive when the request completed might look like
{
requestNumber: 42
rc : 0
result : WinNT
}
The queued message will always be delivered with the default priority of 5.
The STAFSubmitUTF8 API is identical in all respects with STAFRegister, except that where, service, request, and *resultPtr are all strings in UTF-8 format. This API is used primarily by the Java interfaces.
The STAFSubmit2UTF8 API is identical in all respects with STAFSubmit2, except that where, service, request, and *resultPtr are all strings in UTF-8 format. This API is used primarily by the Java interfaces.
STAFFree is used to free the memory occupied by the result buffer on a call to STAFSubmit. You only need to call this if result buffer pointer is not zero on return from STAFSubmit.
STAFRC_t STAFFree(STAFHandle handle, char *result);
handle is the handle you received on the call to STAFRegister.
result is the pointer passed back from the STAFSubmit call.
/* myHandle was previously set by STAF */ /* result was previously set by STAFSubmit */ STAFRC_t rc = 0; if (result != 0) rc = STAFFree(myHandle, result);
STAF externalizes a wide range of APIs for defining data structures and (un)marshaling data structures. Here is a list of the APIs. A later version of this documentation will provide more details.
typedef enum
{
kSTAFNoneObject = 0,
kSTAFScalarStringObject = 1,
kSTAFListObject = 2,
kSTAFMapObject = 3,
kSTAFMarshallingContextObject = 4
} STAFObjectType_t;
typedef enum
{
kSTAFMarshallingDefaults = 0x00000000
} STAFObjectMarshallingFlags_t;
typedef enum
{
kSTAFUnmarshallingDefaults = 0x00000000,
kSTAFIgnoreIndirectObjects = 0x00000001
} STAFObjectUnmarshallingFlags_t;
// Object constructors/destructors
//
// Note: When a STAFObject is destructed, it recursively deletes all nested
// objects
STAFRC_t STAFObjectConstructCopy(STAFObject_t *copy, STAFObject_t source);
STAFRC_t STAFObjectConstructReference(STAFObject_t *ref, STAFObject_t source);
STAFRC_t STAFObjectConstructNone(STAFObject_t *pNone);
STAFRC_t STAFObjectConstructScalarString(STAFObject_t *pScalar,
STAFStringConst_t string);
STAFRC_t STAFObjectConstructList(STAFObject_t *list);
STAFRC_t STAFObjectConstructMap(STAFObject_t *map);
STAFRC_t STAFObjectConstructMarshallingContext(STAFObject_t *context);
STAFRC_t STAFObjectDestruct(STAFObject_t *object);
// General functions
STAFRC_t STAFObjectIsStringMarshalledData(STAFStringConst_t string,
unsigned int *isMarshalledData);
// Object functions
STAFRC_t STAFObjectGetType(STAFObject_t object, STAFObjectType_t *type);
STAFRC_t STAFObjectGetSize(STAFObject_t object, unsigned int *size);
STAFRC_t STAFObjectIsReference(STAFObject_t object, unsigned int *isRef);
STAFRC_t STAFObjectUnmarshallFromString(STAFObject_t *newContext,
STAFStringConst_t string,
STAFObject_t context,
unsigned int flags);
STAFRC_t STAFObjectMarshallToString(STAFObject_t object, STAFObject_t context,
STAFString_t *string, unsigned int flags);
STAFRC_t STAFObjectGetStringValue(STAFObject_t object, STAFString_t *string);
// Scalar functions
STAFRC_t STAFObjectScalarGetStringValue(STAFObject_t object,
STAFStringConst_t *string);
STAFRC_t STAFObjectScalarGetUIntValue(STAFObject_t object,
unsigned int *uInt,
unsigned int defaultValue);
// List functions
STAFRC_t STAFObjectListAppend(STAFObject_t list, STAFObject_t object);
// Iterator functions
STAFRC_t STAFObjectConstructListIterator(STAFObjectIterator_t *iter,
STAFObject_t list);
STAFRC_t STAFObjectIteratorHasNext(STAFObjectIterator_t iter,
unsigned int *hasNext);
STAFRC_t STAFObjectIteratorGetNext(STAFObjectIterator_t iter,
STAFObject_t *object);
STAFRC_t STAFObjectIteratorDestruct(STAFObjectIterator_t *iter);
// Map functions
STAFRC_t STAFObjectMapGet(STAFObject_t map, STAFStringConst_t key,
STAFObject_t *object);
STAFRC_t STAFObjectMapPut(STAFObject_t map, STAFStringConst_t key,
STAFObject_t object);
STAFRC_t STAFObjectMapHasKey(STAFObject_t map, STAFStringConst_t key,
unsigned int *hasKey);
STAFRC_t STAFObjectConstructMapKeyIterator(STAFObjectIterator_t *pIter,
STAFObject_t map);
STAFRC_t STAFObjectConstructMapValueIterator(STAFObjectIterator_t *pIter,
STAFObject_t map);
// Marshalling Context functions
STAFRC_t STAFObjectMarshallingContextSetMapClassDefinition(
STAFObject_t context,
STAFStringConst_t name,
STAFObject_t mapClassDefinition);
STAFRC_t STAFObjectMarshallingContextGetMapClassDefinition(
STAFObject_t context,
STAFStringConst_t name,
STAFObject_t *mapClassDefinition);
STAFRC_t STAFObjectMarshallingContextHasMapClassDefinition(
STAFObject_t context,
STAFStringConst_t name,
unsigned int *pHasMapClassDefinition);
STAFRC_t STAFObjectMarshallingContextSetRootObject(STAFObject_t context,
STAFObject_t object);
STAFRC_t STAFObjectMarshallingContextGetRootObject(STAFObject_t context,
STAFObject_t *object);
STAFRC_t STAFObjectMarshallingContextAdoptRootObject(STAFObject_t context,
STAFObject_t *object);
STAFRC_t STAFObjectMarshallingContextGetPrimaryObject(STAFObject_t context,
STAFObject_t *object);
STAFRC_t STAFObjectConstructMapClassDefinitionIterator(
STAFObjectIterator_t *pIter, STAFObject_t context);
STAF externalizes some APIs for handling private data in STAF command request options. Here are the definitions for these APIs.
// This method adds privacy delimiters to the data.
// For example, if data passed in is "secret", sets result
// to "!!@secret@!!".
STAFRC_t STAFAddPrivacyDelimiters(STAFStringConst_t data,
STAFString_t *result);
// This method removes the specified number of levels of privacy
// delimiters from the data. Set numLevels to 0 to remove all
// levels of privacy delimiters.
// For example, if data passed in is "!!@secret@!!", sets
// result to "secret".
STAFRC_t STAFRemovePrivacyDelimiters(STAFStringConst_t data,
unsigned int numLevels,
STAFString_t *result);
// This method masks any private data indicated by the privacy
// delimiters by replacing the private data with asterisks.
// For example, if data passed in is "!!@secret@!!", sets
// result to "************".
STAFRC_t STAFMaskPrivateData(STAFStringConst_t data, STAFString_t *result);
// This method escapes any privacy delimiters found in the data.
// For example, if data passed in is "!!@secret@!!", sets
// result to "^!!@secret^@!!".
STAFRC_t STAFEscapePrivacyDelimiters(STAFStringConst_t data,
STAFString_t *result);
STAF externalizes some other general utility APIs. Here are the definitions for these APIs.
/*********************************************************************/
/* STAFUtilFormatString - Generates a string based on a format */
/* string, ala printf(). This is generally */
/* used to format STAF request strings. */
/* */
/* Accepts: (In) The format string */
/* (Out) A pointer to the output string */
/* (In) All data indicated in the format string */
/* */
/* Returns: Standard return codes */
/* */
/* Notes : 1) The caller is responsible for destructing the */
/* output string */
/*********************************************************************/
/* Valid format string specifiers: */
/* */
/* %d - an unsigned integer */
/* %s - a STAFString_t */
/* %C - a STAFString_t which will be formatted in colon-length-colon */
/* delimited format */
/* %% - a percent sign */
/* */
/* Any other %<char> is simply ignored (and not copied) */
/*********************************************************************/
unsigned int STAFUtilFormatString(STAFStringConst_t formatString,
STAFString_t *outputString, ...);
/*********************************************************************/
/* STAFUtilFormatString2 - Generates a string based on a format */
/* string, ala printf(). This is generally */
/* used to format STAF request strings. */
/* */
/* Accepts: (In) The format string */
/* (Out) A pointer to the output string */
/* (In) A variable argument list */
/* */
/* Returns: Standard return codes */
/* */
/* Notes : 1) The caller is responsible for destructing the */
/* output string */
/* 2) Valid format strings are the same as defined for */
/* STAFUtilFormatString() */
/*********************************************************************/
unsigned int STAFUtilFormatString2(STAFStringConst_t formatString,
STAFString_t *outputString, va_list args);
/*********************************************************************/
/* STAFUtilStripPortFromEndpoint - Removes @<Port> from the end of */
/* an endpoint if present. */
/* */
/* Accepts: (In/Out) A pointer to a string containing the endpoint */
/* with format: */
/* [<Interface>://<Machine Identifier>[@<Port>] */
/* (Out) A pointer to a string containing the stripped */
/* endpoint with format: */
/* [<Interface>://<Machine Identifier> */
/* */
/* Returns: 0 */
/* Notes : 1) The caller is responsible for destructing the output */
/* string containing the stripped endpoint */
/*********************************************************************/
STAFRC_t STAFUtilStripPortFromEndpoint(STAFStringConst_t endpoint,
STAFString_t *strippedEndpoint);
STAF externalizes other APIs that fall into the following general classes
Please see the indicated header files for more information on syntax and use of these families of APIs.
STAF externalizes five primary classes to C++ programs. These class are
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.
The utility function stripPortFromEndpoint returns an endpoint with the @port removed from the end of the endpoint, if present.
Several utility functions are provided to handle private data that can be specified in values in a STAF request string. These functions are addPrivacyDelimiters, escapePrivacyDelimiters, removePrivacyDelimiters, and maskPrivateData. See 7.3, "Private Data" for more information about handling private data.
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);
// This returns the colon-length-colon delimited version of a string
static STAFString wrapData(const STAFString &data);
// This will format a string for you. See STAFUtilFormatString() in
// STAFUtil.h
//
// Note: DO NOT try to pass STAFString's into the ... portion of this
// function. The only supported data types are "unsigned int" and
// STAFString_t. Therefore be sure to call getImpl() on all
// STAFString's before passing them to this method.
static STAFString formatString(STAFStringConst_t formatString, ...);
// This returns the endpoint without the port (strips @nnnn from the end
// of the endpoint, if present)
static STAFString stripPortFromEndpoint(const STAFString &endpoint);
// This method returns the data with privacy delimiters added.
// For example, if pass in "secret", it returns "!!@secret@!!".
static STAFString addPrivacyDelimiters(const STAFString &data);
// This method removes any privacy delimiters from the data.
// For example, if pass in "!!@secret@!!", it returns "secret".
static STAFString removePrivacyDelimiters(const STAFString &data,
unsigned int numLevels = 0);
// This method masks any private data indicated by the privacy delimiters
// by replacing the private data with asterisks.
// For example, if pass in "!!@secret@!!", it returns "************".
static STAFString maskPrivateData(const STAFString &data);
// This method returns the data with privacy delimiters escaped.
// For example, if pass in "!!@secret@!!", it returns "^!!@secret^@!!".
static STAFString escapePrivacyDelimiters(const STAFString &data);
STAFHandle_t getHandle();
STAFHandle_t adoptHandle();
bool getDoUnreg();
void setDoUnreg(bool doUnreg);
~STAFHandle();
};
#include "STAF.h"
#include "STAF_iostream.h"
int main(void)
{
STAFHandlePtr handle;
unsigned int rc = STAFHandle::create("MyApplication", handle);
if (rc != 0)
{
cout << "Error registering with STAF, RC: " << rc << endl;
return 1;
}
STAFResultPtr result = handle->submit("LOCAL", "PING", "PING");
cout << "PING RC: " << result->rc << ", Result: " << result->result << endl;
STAFString semName("Sem name with spaces");
result = handle->submit("LOCAL", "SEM", "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;
}
The STAFObject class is used to represent a variety of structured data types. Unlike newer languages, C++ doesn't have a reflective type system allowing us to marshall arbitrary data structures. Therefore, we introduced a class which would allow us to provide general data structures which could be reflectively marshalled. Note, that all data structure methods are provided in the one STAFObject class.
All data types are created via static methods. Note the createReference() method. This allows you to create a reference to another object. This is important to note, as when you add an object to another object (for example, adding a string to a list) the recipient takes ownership of the object. Thus, if you want to keep ownership of the object, you will need to add a reference of the object to the other object, instead of the object itself.
Note, when a STAFObject is destructed, all objects it contains are destructed (recursively) as well. At this point, any references to objects that were contained in that data structure are now "dangling". The only valid methods for a "dangling" reference are isRef(), type(), and destruction.
typedef enum
{
kSTAFNoneObject = 0,
kSTAFScalarStringObject = 1,
kSTAFListObject = 2,
kSTAFMapObject = 3,
kSTAFMarshallingContextObject = 4
} STAFObjectType_t;
typedef enum
{
kSTAFMarshallingDefaults = 0x00000000
} STAFObjectMarshallingFlags_t;
typedef enum
{
kSTAFUnmarshallingDefaults = 0x00000000,
kSTAFIgnoreIndirectObjects = 0x00000001
} STAFObjectUnmarshallingFlags_t;
typedef STAFRefPtr<STAFObject> STAFObjectPtr;
class STAFObject
{
public:
// Creation methods
static STAFObjectPtr createReference(const STAFObject &source);
static STAFObjectPtr createReference(const STAFObjectPtr &source);
static STAFObjectPtr createReference(STAFObject_t source);
static STAFObjectPtr createNone();
static STAFObjectPtr createScalar(const STAFString &aString);
static STAFObjectPtr createList();
static STAFObjectPtr createMap();
static STAFObjectPtr createMarshallingContext();
// General methods
static bool isMarshalledData(const STAFString &aString);
// General object methods
STAFObjectType_t type();
unsigned int size();
bool isRef();
STAFObjectPtr reference();
STAFString asString();
STAFString marshall(unsigned int flags = kSTAFMarshallingDefaults);
void marshall(STAFString &output,
unsigned int flags = kSTAFMarshallingDefaults);
// Note: This method always returns a Marshalling Context
static STAFObjectPtr unmarshall(const STAFString &input,
unsigned int flags =
kSTAFUnmarshallingDefaults);
// List methods
void append(const STAFObjectPtr &objPtr);
void append(const STAFString &aString);
STAFObjectIteratorPtr iterate();
// Map methods
bool hasKey(const STAFString &key);
STAFObjectPtr get(const STAFString &key);
void put(const STAFString &key, const STAFObjectPtr &objPtr);
void put(const STAFString &key, const STAFString &aString);
STAFObjectIteratorPtr keyIterator();
STAFObjectIteratorPtr valueIterator();
// Marshalling Context methods
void setMapClassDefinition(const STAFMapClassDefinitionPtr &defPtr);
STAFMapClassDefinitionPtr getMapClassDefinition(const STAFString &name);
bool hasMapClassDefinition(const STAFString &name);
STAFObjectIteratorPtr mapClassDefinitionIterator();
void setRootObject(const STAFObjectPtr &objPtr);
STAFObjectPtr getRootObject();
// Destructor
~STAFObject();
};
This example submits a request to the PROCESS service to start a command and wait for it to complete. The result from this request is a marshalled map containing the process completion information, so this example demonstrates how to unmarshall the result and get the process return code.
#include "STAF.h"
#include "STAF_iostream.h"
int main(void)
{
STAFHandlePtr handlePtr;
unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr);
if (rc != 0)
{
cout << "Error registering with STAF, RC: " << rc << endl;
return rc;
}
// Submit a request to start a process on a machine and wait for
// it to complete. For this example, simply starting the process
// on the local machine and listing and contents of C:/temp.
STAFString machine = STAFString("local");
STAFString command = STAFString("dir C:/temp");
STAFResultPtr res = handlePtr->submit(
machine, "PROCESS", "START COMMAND " +
STAFHandle::wrapData(command) + " RETURNSTDOUT RETURNSTDERR WAIT");
if (res->rc != kSTAFOk)
{
cout << "PROCESS START request failed with RC=" << STAFString(res->rc)
<< " Result=" << res->result << endl;
return res->rc;
}
// The result buffer from a successful PROCESS START WAIT request
// returns a marshalled map containing the process completion information
// Unmarshall the result from the PROCESS START WAIT request to get
// the marshalling context
STAFObjectPtr mc = STAFObject::unmarshall(res->result);
// Print the result from the PROCESS START WAIT request in a
// "Pretty Print" format using the asFormattedString() method
cout << "Process Result (Pretty Printed): " << endl
<< mc->asFormattedString()
<< endl << endl;
// Get the root object for the marshalling context (which, in this
// case, is a map)
STAFObjectPtr processResultMap = mc->getRootObject();
// Check if the process RC is 0 by getting the "rc" key from the
// process completion map
if (processResultMap->get("rc")->asString() == "0")
cout << "Process completed successfully" << endl;
else
cout << "Process failed with RC="
<< processResultMap->get("rc")->asString() << endl;
return 0;
}
The STAFObjectIterator class represents an iterator over other objects. You can not directly create a STAFObjectIterator. You obtain a STAFObjectIterator via calling an iteration method on a STAFObject. You can iterate over the items in a list, the keys in a map, the values in a map, and the names of the map class definitions in a marshalling context.
typedef STAFRefPtr<STAFObjectIterator> STAFObjectIteratorPtr;
class STAFObjectIterator
{
public:
bool hasNext();
STAFObjectPtr next();
~STAFObjectIterator();
};
This example submits a request to the FS service to list the contents of a directory (in the long, detailed format). The result from this request is a marshalled list of maps, so this example demonstrates how to unmarshall the result and get the root object (a list) and shows how to iterate through this list using the STAFObjectIterator class.
#include "STAF.h"
#include "STAF_iostream.h"
int main(void)
{
STAFHandlePtr handlePtr;
unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr);
if (rc != 0)
{
cout << "Error registering with STAF, RC: " << rc << endl;
return rc;
}
// Submit a request to the FS service to list the contents of a
// directory in the long format with detailed information about
// the entries in the directory
STAFString directory = "C:/temp/staf";
STAFResultPtr res = handlePtr->submit(
machine, "FS", "LIST DIRECTORY " +
STAFHandle::wrapData(directory) + " LONG DETAILS");
if (res->rc != kSTAFOk)
{
cout << "FS LIST DIRECTORY " << directory << " LONG DETAILS request"
<< " failed with RC=" << STAFString(res->rc)
<< " Result=" << res->result << endl;
return res->rc;
}
// The result buffer from a successful LIST DIRECTORY LONG DETAILS
// request returns a marshalled list of maps containing information
// about the entries in the directory
// Unmarshall the result from the LIST DIRECTORY LONG DETAILS
// request to get the marshalling context
STAFObjectPtr mc = STAFObject::unmarshall(res->result);
// Print the result in a "Pretty Print" format using the
// asFormattedString() method
cout << endl << "LIST DIRECTORY Result (Pretty Printed): " << endl
<< mc->asFormattedString()
<< endl << endl;
STAFObjectPtr outputList = mc->getRootObject();
// Iterate through the unmarshalled result (which is a List
// containing a Map for each entry in the directory).
// Check if the directory contains a file named test.txt that
// was last modified after 20060306-00:00:00.
STAFObjectIteratorPtr iter = outputList->iterate();
while (iter->hasNext())
{
STAFObjectPtr entryMap = iter->next();
if (entryMap->get("name")->asString() == "test.txt")
{
if (entryMap->get("lastModifiedTimestamp")->asString() >
"20060306-00:00:00")
{
cout << "Entry test.txt was modified at "
<< entryMap->get("lastModifiedTimestamp")->asString()
<< endl;
}
}
}
return 0;
}
The STAFMapClassDefinition class is used to represent the metadata associated with a map class. Note, the order with which keys are added determines their display order.
typedef STAFRefPtr<STAFMapClassDefinition> STAFMapClassDefinitionPtr;
class STAFMapClassDefinition
{
public:
static STAFMapClassDefinitionPtr create(const STAFString &name);
static STAFMapClassDefinitionPtr createReference(
STAFMapClassDefinitionPtr source);
STAFObjectPtr createInstance();
STAFMapClassDefinitionPtr reference();
void addKey(const STAFString &keyName);
void addKey(const STAFString &keyName, const STAFString &displayName);
void setKeyProperty(const STAFString &keyName, const STAFString &propName,
const STAFString &propValue);
STAFObjectIteratorPtr keyIterator();
STAFString name() const;
STAFObjectPtr getMapClassDefinitionObject();
};
STAF externalizes three APIs to Rexx programs. These APIs allow you to register/unregister with STAF and submit service requests. These APIs are located in the RXStaf DLL. A Rexx program wishing to use these APIs must be sure to load them from the DLL, with the following two lines of code.
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs" call STAFLoadFuncs
STAF also provides wrapper interfaces around the LOG, MONITOR, and RESPOOL services, as well as a small set of utility functions. These wrapper interfaces and utility functions are provided in Rexx Library files which have the extension .rxl. In order to incorporate these wrappers into your Rexx programs, you may do one of the following:
The names of these libraries are as follows:
The STAFRegister call is used by a Rexx program to register with STAF.
call STAFRegister handleName[, handleVarName]
handleName is the name by which you want this handle to be known.
handleVarName is the name of the Variable which you want to contain the handle that you will use on all other subsequent STAF calls. If this parameter is not specified, the handle will be placed in the variable STAFHandle.
call STAFRegister "MyHandleName", "MyHandle" say "My handle is:" MyHandle
or
call STAFRegister "MyHandleName" say "My handle is:" STAFHandle
The STAFUnRegister call is used by a Rexx program to unregister with STAF, which frees up any internal STAF resources used by the handle.
call STAFUnRegister [handle]
handle is the handle that you received on the call to STAFRegister. If this parameter is not specified, the handle will be retrieved from the STAFHandle variable.
call STAFUnRegister MyHandle
or
call STAFUnRegister
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
call STAFSubmit [handle,] where, service, request [, resultVarName]
handle is the handle you received on the call to STAFRegister. If this parameter is not specified, the handle will be retrieved from the STAFHandle variable.
where is the destination machine for the service request. This should be either LOCAL or the name of a machine.
service is the name of the service to which you are submitting the request.
request is the actual request that you are sending to the service.
resultVarName is the name of a variable that will contain the result of the service request. If you specify resultVarName, you must also specify handle
Note: The Rexx variable "STAFResult" will always be set to the result of the service request. However, resultVarName allows you to get another variable set if needed.
Note: To define whether a submit request should be synchronous or asynchronous, the STAFSyncOption variable should be set prior to calling STAFSubmit (if it is not set, the submit will be synchronous). The possible values for STAFSyncOption are defined in STAFUtil.
/* myHandle was previously set by a call to STAFRegister */ someMachine = "testmach1" service = "PING" request = "PING" call STAFSubmit myHandle, someMachine, service, request, "SomeVar" say "STAFSubmit return code :" RESULT say "Service request result :" STAFResult say "Also service request result:" SomeVar
or
/* STAFHandle was previously set by a call to STAFRegister */ someMachine = "testmach1" service = "PING" request = "PING" call STAFSubmit someMachine, service, request say "STAFSubmit return code :" RESULT say "Service request result :" STAFResult call STAFSyncValues STAFSyncOption = STAFSync.!ReqRetain call STAFSubmit someMachine, service, request say "Asynchronous Service request number :" STAFResult
The STAFMon wrapper library provides a wrapper around the MONITOR service. The following functions are provided:
call STAFMonErrorText call STAFMonitor <Message>[, <Extra request data>]
<Message> is the message that you wish to log to the MONITOR service.
<Extra request data> is any additional information that should be passed along with the MONITOR service LOG request, such as additional options like RESOLVEMESSAGE.
/* STAFHandle was set by a previous call to STAFRegister */
call STAFMonErrorText
do i = 1 to numLoops
call STAFMonitor "Beginning of loop #"i
...
...
end
The STAFLog wrapper library provides a wrapper around the LOG service. The following functions are provided:
call STAFLogErrorText call STAFInitLog <Reference>, <Log name>[, [Log type], [Monitor mask]] call STAFSetCurrentLog <Reference> call STAFLog <Log level>, <Message>[, <Extra request data>]
<Reference> is a text string of your desire that is used to refer to a log. This facilitates switching between several different log files.
<Log name> is the name of the log to which you wish to log messages
[Log type] is the type of log. This should be one of GLOBAL, MACHINE, or HANDLE. The default is MACHINE.
[Monitor mask] is a string which specifies which logging levels should also be sent to the MONITOR service. The default is "FATAL ERROR WARNING INFO STATUS"
<Log level> is the logging level of the message to be logged, e.g. ERROR or WARNING.
<Message> is the message that you wish to log to the LOG service.
<Extra request data> is any additional information that should be passed along with the LOG service LOG request, such as additional options like RESOLVEMESSAGE.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFLogErrorText call STAFInitLog "Public", "Testcase1", "MACHINE" call STAFInitLog "Private", "Testcase1", "HANDLE", "FATAL ERROR WARNING" call STAFSetCurrentLog "Public" call STAFLog "INFO", "Beginning testcase 1" ... call STAFSetCurrentLog "Private" call STAFLog "DEBUG", "Some private debug data"
The STAFPool wrapper library provides a wrapper around the RESPOOL service. The following functions are provided:
call STAFPoolErrorText call STAFPoolRequest <Pool name>, <Entry variable name>[, [Entry type], [Timeout]] call STAFPoolRelease <Pool name>, <Entry>[, <Force>]
<Pool name> is the name of the pool from which to request or release an entry.
<Entry variable name> is the name of the variable in which to place the actual requested entry's value.
[Entry type] is the type of entry requested. This should be either FIRST or RANDOM. The default is RANDOM.
[Timeout] is an amount of time, in milliseconds, after which the request should timeout. The default is to wait indefinitely.
<Force> specifies whether the entry should be forceable released. This should be either FORCE or NOFORCE. The default is NOFORCE.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFPoolErrorText call STAFPoolRequest "Pool1", "Entry1" say "The entry obtained was:" Entry1 ... call STAFPoolRelease Entry1
The STAFUtil library provides some utilitiy functions for use by Rexx programs. The following functions are provided:
call STAFErrorText call STAFSyncValues wrappedData = STAFWrapData(<Data>) serviceResult = MakeSTAFResult(<Return code>[, <Result string>])
<Data> is the data for which to generate the colon delimited version.
<Return code> is the service request's return code.
<Result string> is the service request's result string.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFErrorText someData = "..." wrappedData = STAFWrapData(someData) /* The following would only be used by a service provider */ returnCode = 0 resultString = "..." serviceResult = MakeSTAFResult(returnCode, resultString) /* The following sets the STAFSyncOption variable to one of the STAFSync constants */ STAFSyncOption = STAFSync.!ReqRetain
For information on STAF's V3 support for the Java language, see the STAF Java User's Guide.
For information on STAF's V3 support for the Perl language, see the STAF Perl User's Guide.
For information on STAF's V3 support for the Python language, see the STAF Python User's Guide.
For information on STAF's V3 support for the Tcl language, see the STAF Tcl User's Guide.
Services are what provide all the capabilities of STAF.
When examining the syntax statements for each service, keep the following rules in mind.
For example,
LOG <GLOBAL | MACHINE | HANDLE> MESSAGE <Message>
indicates that option LOG is required and requires no value, option MESSAGE is required and requires a value, and exactly one of options GLOBAL, MACHINE, and HANDLE must be specified (and none of these options requires a value).
START COMMAND <Command> [WORKLOAD <Name>] [WAIT | ASYNC]indicates that option START is required and requires no value, option COMMAND is required and requires a value, option WORKLOAD is not required, but, if specified, requires a value, and one of the options WAIT and ASYNC may be specified, and neither requires a value.
Values for options may be specified in one of three ways.
MESSAGE Hello
MESSAGE "Hello World"
specifies the message Hello World
MESSAGE "He said, \"What is that\""
specifies the message He said, "What is that"
MESSAGE "c:\\MyApp\\Some directory with spaces"
specifies the message c:\MyApp\Some directory with spaces
MESSAGE :11:Hello World
specifies the message Hello World
MESSAGE :23:He said, "What is that"
specifies the message He said, "What is that"
MESSAGE :35:c:\MyApp\Some directory with spaces
specifies the message c:\MyApp\Some directory with spaces
The first two formats are most 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.
Some command options allow their values to contain private data which will be handled by the service. This will be noted in the command options that allow it.
Private data is denoted by surrounding the private data, e.g. a password, between an opening privacy delimiter (!!@) and a closing privacy delimiter (@!!). For example, !!@password@!!. Because of this special significance of "!!@" and "@!!", if you do not want them to denote private data, use a caret (^), as an escape character for "!!@" and "@!!". Nested private data is allowed.
Using privacy delimiters indicates that the data enclosed between opening and closing privacy delimiters should be protected so that if the private data is displayed (e.g. in a LIST or QUERY request), any private data will be masked (replaced with asterisks).
The Process service's START request handles private data in the COMMAND, PARMS, and/or PASSWORD options. If the command contains a password (e.g. secret) that you want to keep private, enclose the password between privacy delimiters as follows:
START SHELL COMMAND "C:/tests/myTest.exe -password !!@secret@!!"The above command would be displayed as "myTest.exe -password ************" in a LIST or QUERY request.
If you want to start command "TestA.exe" as another user (e.g. userid testuser and password secret), you can indicate that the password is private as follows:
START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@secret@!!
If the password in the above example actually contained !!@ or @!! (e.g. pass@!!rd), then you need to escape the privacy delimiter. For example:
START COMMAND C:/tests/TestA.exe USER testuser PASSWORD !!@pass^@!!rd@!!
You can nest private data. For example the following string contains two levels of nested private data:
!!@Top secret info: password=^!!@secret^@!!.@!!Note that a caret (^) is added to escape any !!@ and @!! characters that are nested within another set of privacy delimiters.
When specifying private data for a command option in a program, use the method provided by STAF to add privacy delimiters. STAF also provides methods to escape privacy delimiters, to mask privacy delimiters, and to remove privacy delimiters. See the STAF API documentation for more information.
Most command options allow their values to contain variable references which will be resolved by the service. This will be noted in the command options that allow it. In addition, the machine and service specified when submitting a STAF request may contain variable references.
The following potential variable pools are available for use in variable resolution in a service request:
Unless otherwise specified, variable resolution is handled in one of two ways, based on whether the request is performed locally (i.e., on the originating system) or on another system.
Note: Since, by definition, a delegated service request will not be handled locally, the variable pool associated with the requesting process will never be used for variable resolution in a delegated service request.
While all services technically return strings in the result buffer, many times this string will actually be the marshalled form of a data structure. This section describes how a service's result is defined in this documentation. See 6.1, "Marshalling Structured Data" for more information on marshalled data structures (and how they are mapped to the various languages that STAF supports).
In the simplest case, a service will return no value or a simple string (i.e., a string which is not the marshalled form of a data structure). In this case, the service result will simple describe what the simple string contains. For example, the HANDLE service documentation (see 8.5.2, "CREATE") indicates that when creating a static handle the result buffer will simply contain the handle number that was created.
If the service result contains the marshalled form of a data structure (which will now be referred to as "structured data"), the service documentation will describe it in terms of various structured content. The following are the types of structured data you will encounter.
In some cases, the structured data that is returned will be one of a number of possible values. In that case, you will see the "or" symbol, '|', used to list the possible choices. Two common cases are
<String> | <None>and
<Map:<Class>> | <None>
In the first case, this means that you will either get a string object or the special <None> object. In the second case, it means you will either get an instance of the specified map class or the special <None> object.
To further document map classes, each map class will have an associated table defining the metadata associated with the map class. The general format of this table is as follows.
Table 7. Definition of map class <Map Class Name>
| Description: This contains a description of the map class | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| key1 | Key 1 display name
(Key 1 short display name) if one is provided | key1 type | key1 format/value information |
| ... | ... | ... | ... |
| keyX | Key X display name
(Key 1 short display name) if one is provided | keyX type | keyX format/value information |
| Notes: Any notes about the definition of the map class. | |||
The "Display Name" field shows the display name for each key, and, optionally, a "short" display name may be specified (in parenthesis) for a key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.
The "Format / Value" field is used predominantly to document the data present in <String> objects. When, the string will contain one of a limited set of possible values, then the set of possible values will be listed in this column. This might look like the following
'Default' | 'Enabled' | 'Disabled'
When the string will be in a particular format, the format will be documented in this column. For example, a common string value is a timestamp, which is documented in the "Format / Value" column as follows
<YYYYMMDD-HH:MM:SS>
All STAF services provide a HELP command that list basic service syntax information.
It is recommended that external service writers also provide a HELP facility.
The following table contains a brief description of the services provided
with STAF. The chapter that follows provides a detailed explanation of each
service.
| Service name | Description String Representation |
|---|---|
| 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 such as displaying the version of STAF that is currently running. |
| MONITOR | Provides a means to monitor the status of running programs |
| PING | Provides a simple is-alive message |
| PROCESS | Handles starting, stopping, and querying processes |
| QUEUE | Interacts with STAF queues |
| RESPOOL | Manages pools of named elements |
| SEM | Provides named event and mutex semaphores |
| SERVICE | Provides information on available STAF services |
| SHUTDOWN | Provides a means to shutdown STAF and register for shutdown notifications |
| TRACE | Provides tracing information for STAF services |
| TRUST | Interfaces with STAF's security |
| VAR | Allows inspection and manipulation of STAF variable pools |
| ZIP | Provides a means to zip/unzip/list/delete PKZip/WinZip compatible archives |
The foundation services that STAF provides are described in this chapter. For each service the following sections are listed.
The 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 is only valid if submitted to the local machine, not to remote machines.
All return codes from RECORD are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RECORD command.
LIST allows you to list all the information in the diagnostics map, or just the triggers or sources, or a particular trigger or source. It also allows you to list current operational settings.
LIST <[TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES]
[SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE]> |
SETTINGS
If no options are specified (other than a SORTBY option), it will list all the trigger/source combinations that were recorded and the number of times each was recorded.
TRIGGER indicates you want to list all the sources for the specified trigger and the number of times each source was recorded for this trigger. This option will resolve variables.
SOURCE indicates you want to list all the triggers for the specified source and the number of times each trigger was recorded for this source. This option will resolve variables.
TRIGGERS indicates you want to list all the triggers that have been recorded and the number of times they were recorded.
SOURCES indicates you want to list all the sources that have been recorded and the number of times they were recorded.
SORTBYCOUNT specifies to sort the listing by count in descending order. This is the default.
SORTBYTRIGGER specifies to sort the listing by trigger in ascending order.
SORTBYSOURCE specifies to sort the listing by source in ascending order.
SETTINGS indicate you want to list the current operational settings for the service.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the LIST request based on the options specified:
The result buffer for a LIST request (without specifying options
TRIGGER, SOURCE, TRIGGERS, SOURCES, or SETTINGS) will contain a
marshalled <List> of <Map:STAF/Service/Diag/AllDiagInfo>
representing all of the unique trigger/source combinations.
The maps are defined as follows:
Table 9. Definition of map class STAF/Service/Diag/AllDiagInfo
| Description: This map class represents the diagnostics information for all of the unique trigger/source combinations. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfTriggers | Number of Triggers | <String> |
|
| numberOfSources | Number of Sources | <String> |
|
| comboList | Trigger/Source Combinations | <List> of <Map:STAF/Service/Diag/ComboCount> |
|
Notes:
| |||
Table 10. Definition of map class STAF/Service/Diag/ComboCount
| Description: This map class represents a unique trigger/source combination and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| trigger | Trigger | <String> |
|
| source | Source | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times each trigger/source combination has been recorded. | |||
The result buffer for a LIST TRIGGERS request will contain a
marshalled <List> of <Map:STAF/Service/Diag/TriggersInfo>
representing all of the unique triggers that have been recorded.
The maps are defined as follows:
Table 11. Definition of map class STAF/Service/Diag/TriggersInfo
| Description: This map class represents the diagnostics information for all of the unique triggers that have been recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfTriggers | Number of Triggers | <String> |
|
| triggerList | Triggers | <List> of <Map:STAF/Service/Diag/TriggerCount> |
|
Notes:
| |||
Table 12. Definition of map class STAF/Service/Diag/TriggerCount
| Description: This map class represents a trigger and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| trigger | Trigger | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times a trigger has been recorded. | |||
The result buffer for a LIST SOURCES request will contain a
marshalled <List> of <Map:STAF/Service/Diag/SourcesInfo>
representing all of the unique sources that have been recorded.
The maps are defined as follows:
Table 13. Definition of map class STAF/Service/Diag/SourcesInfo
| Description: This map class represents the diagnostics information for all of the unique sources that have been recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| numberOfSources | Number of Sources | <String> |
|
| sourceList | Sources | <List> of <Map:STAF/Service/Diag/SourceCount> |
|
Notes:
| |||
Table 14. Definition of map class STAF/Service/Diag/SourceCount
| Description: This map class represents a source and a count of how many times it was recorded. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| source | Source | <String> |
|
| count | Count | <String> |
|
| Notes: "Count" specifies the number of times a source has been recorded. | |||
The result buffer for a "LIST TRIGGER <Trigger>" request
will contain a marshalled
<List> of <Map:STAF/Service/Diag/TriggerInfo>
representing all of the unique sources that have been recorded for
the specified trigger.
The maps are defined as follows:
Table 15. Definition of map class STAF/Service/Diag/TriggerInfo
| Description: This map class represents the diagnostics information for the specified trigger. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| trigger | Trigger | <String> |
|
| numberOfSources | Number of Sources | <String> |
|
| sourceList | Sources | <List> of <Map:STAF/Service/Diag/SourceCount> |
|
Notes:
| |||
The result buffer for a "LIST SOURCE <Source>" request
will contain a marshalled
<List> of <Map:STAF/Service/Diag/SourceInfo>
representing all of the unique triggers that have been recorded for
the specified source.
The maps are defined as follows:
Table 16. Definition of map class STAF/Service/Diag/SourceInfo
| Description: This map class represents the diagnostics information for the specified source. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fromTimestamp | From Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| toTimestamp | To Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| elapsedTime | Elapsed Time | <String> | <None> | <[H]HH:MM:SS> |
| source | Source | <String> |
|
| numberOfTriggers | Number of Triggers | <String> |
|
| triggerList | Triggers | <List> of <Map:STAF/Service/Diag/TriggerCount> |
|
Notes:
| |||
The result buffer for a "LIST SETTINGS" request
will contain a marshalled
<Map:STAF/Service/Diag/Settings>
representing the current operational settings for the DIAG service.
The maps are defined as follows:
Table 17. Definition of map class STAF/Service/Diag/Settings
| Description: This map class represents the current operational settings for the DIAG service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| diagnostics | Diagnostics | <String> | 'Enabled' | 'Disabled'. |
| lastResetTimestamp | Last Reset / First Enabled | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| lastDisabledTimestamp | Last Disabled | <String> | <YYYYMMDD-HH:MM:SS> |
Notes:
| |||
Syntax: LIST
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:20:05
Elapsed Time : 00:05:01
Number of Triggers : 3
Number of Sources : 2
Trigger/Source Combinations: [
{
Trigger: MYSERVICE QUERY
Source : MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Trigger: MYSERVICE QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 4
}
{
Trigger: MYSERVICE LIST
Source : myApp2;machine1.austin.ibm.com;97
Count : 1
}
]
}
Syntax: LIST SORTBYTRIGGER
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:21:09
Elapsed Time : 00:06:05
Number of Triggers : 3
Number of Sources : 2
Trigger/Source Combinations: [
{
Trigger: MYSERVICE LIST
Source : myApp2;machine1.austin.ibm.com;97
Count : 1
}
{
Trigger: MYSERVICE QUERY
Source : MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Trigger: MYSERVICE QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Source : myApp2;machine1.austin.ibm.com;97
Count : 4
}
]
}
Syntax: LIST TRIGGERS SORTBYTRIGGER
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Timestamp : 20040926-12:28:20
Elapsed Time : 00:13:16
Number of Triggers: 3
Triggers : [
{
Trigger: MYSERVICE LIST
Count : 1
}
{
Trigger: MYSERVICE QUERY
Count : 17
}
{
Trigger: SAMPLE1 QUERY
Count : 4
}
]
}
Syntax: LIST SOURCES
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:32:53
Elapsed Time : 00:17:49
Number of Sources: 2
Sources : [
{
Source: MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Source: MyApp2;machine1.austin.ibm.com;97
Count : 12
}
]
}
Syntax: LIST TRIGGER "MYSERVICE QUERY" SORTBYSOURCE
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:36:18
Elapsed Time : 00:21:14
Trigger : MYSERVICE QUERY
Number of Sources: 2
Sources : [
{
Source: MyApp;machine1.austin.ibm.com;77
Count : 10
}
{
Source: MyApp2;machine1.austin.ibm.com;97
Count : 7
}
]
}
Syntax: LIST SOURCE "MyApp2;machine1.austin.ibm.com;97"
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
From Date-Time : 20040926-12:15:04
To Date-Time : 20040926-12:40:08
Elapsed Time : 00:25:04
Source : MyApp2;machine1.austin.ibm.com;97
Number of Triggers: 3
Triggers : [
{
Trigger: MYSERVICE QUERY
Count : 7
}
{
Trigger: SAMPLE1 QUERY
Count : 4
}
{
Trigger: MYSERVICE LIST
Count : 1
}
]
}
Syntax: LIST SETTINGS
Results: If the request is issued from the command line, the result, in default format, could look like:
Diagnostics : Enabled Last Reset / First Enabled: 20040926-12:15:04 Last Disabled : 20040926-12:14:53
RESET allows you to clear all data from the diagnostics map.
RESET FORCE
FORCE is a confirmation that you want to clear all data.
This command requires trust level 4.
All return codes from RESET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RESET command.
ENABLE allows you to enable recording diagnostics.
Note: You may also enable diagnostics when STAF starts by setting operational parameter ENABLEDIAGS in the STAF configuration file.
ENABLE
This command requires trust level 4.
All return codes from ENABLE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a ENABLE command.
DISABLE allows you to disable recording diagnostics.
DISABLE
This command requires trust level 4.
All return codes from DISABLE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a DISABLE command.
The ECHO service is an internal STAF service. ECHO provides a 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 <Name> | TODIRECTORY <Name>] [TOMACHINE <Machine>]
[TEXT [FORMAT <Format>]] [FAILIFEXISTS | FAILIFNEW]
FILE specifies the name of the file to copy. This option will resolve variables.
TOFILE specifies the name of the file to create. If neither TOFILE nor TODIRECTORY is specified, this defaults to the same, unresolved, name as specified in FILE. This option will resolve variables. These variables will be resolved on the target machine.
TODIRECTORY specifies the name of the directory to copy the file to. The name of the "to file" will be the same as specified in FILE. This directory must already exist on the target machine. This option will resolve variables. These variables will be resolved on the target machine.
TOMACHINE specifies the machine to copy the file to. This defaults to the machine which originated the request. Specifying local indicates to copy the file to the same machine that the file is being copied from. 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 as follows:
An exception to these trust requirements is if the orgMachine is the same as the toMachine and the STRICTFSCOPYTRUST operational setting is disabled (which it is by default), then the toMachine does not have to give trust level 4 to the sourceMachine. See 4.7, "Operational parameters" for more information on the STRICTFSCOPYTRUST operational parameter.
All return codes from COPY FILE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a COPY FILE command.
In the following examples, assume the command is being submitted locally from machine TestSrv1.
Syntax: COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1
Syntax: Note that both of these COPY FILE examples are equivalent.
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT FORMAT Native
Syntax: COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " "
In the following examples, assume the command is being submitted to machine Client1 from machine TestSrv1.
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TODIRECTORY h:\Logs TOMACHINE LogSrv
Syntax: COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local
Syntax: COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT
COPY DIRECTORY allows you to copy 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 as follows:
An exception to these trust requirements is if the orgMachine is the same as the toMachine and the STRICTFSCOPYTRUST operational setting is disabled (which it is by default), then the toMachine does not have to give trust level 4 to the sourceMachine. See 4.7, "Operational parameters" for more information on the STRICTFSCOPYTRUST operational parameter.
All return codes from COPY DIRECTORY are documented in Appendix A, "API Return Codes".
Table 18. Definition of map class STAF/Service/FS/ErrorInfo
| Description: This map class represents error information for an entry in a directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| rc | RC | <String> |
|
| osRC | OS RC | <String> | <None> |
|
Notes:
| |||
For example, if a copy directory request is submitted from the command line, and two errors occurred during the copy, the result, in table format, could look like:
Name RC OS RC ------------------- -- ------ c:\tmp\project.htm 17 <None> c:\tmp\project5.xml 10 32
In the following examples, assume the command is being issued locally from machine TestSrv1.
In the following examples, assume the command is being issued locally from machine TestSrv1 and the following directory structures exist under the c:/testcase directory:
c:\testcase c:\testcase\error.txt c:\testcase\web.exe c:\testcase\web.txt c:\testcase\web.xml c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2 c:\testcase\subdir\subdir_2\readme.txt
The expected result is that the following entries exist on machine Client1:
c:\testcase c:\testcase\error.txt c:\testcase\web.exe c:\testcase\web.txt c:\testcase\web.xml c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2 c:\testcase\subdir\subdir_2\readme.txt
The expected result is that the following entries were created on machine Client1:
c:\testcase c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2
Syntax: Note that both of these COPY DIRECTORY examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
NAME web TEXTEXT txt TEXTEXT xml
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
NAME web TEXTEXT txt TEXTEXT xml FORMAT Native
The expected result is that the following entries were created on machine Client1. Note that error.txt was not copied since its name is not 'web'.
/testcase /testcase/web.exe /testcase/web.txt /testcase/web.xml
Syntax: Note that both of these COPY DIRECTORY examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
EXT txt TEXTEXT "*" RECURSE
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
EXT txt TEXTEXT txt FORMAT Native RECURSE
The expected result is that the following entries were created on machine Client1.
/testcase /testcase/error.txt /testcase/subdir /testcase/subdir/subdir_2 /testcase/subdir/subdir_2/readme.txt
In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.
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.
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT FORMAT Native
GET FILE c:/testcases/test1.cmp BINARY GET FILE c:/testcases1/test1.cmp BINARY FORMAT HEX
GET ENTRY retrieves an attribute of a file system entry, such as its type, size, 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.
Table 19. 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 |
Table 20. Definition of map class STAF/Service/FS/SizeInfo
| Description: This map class represents the 64-bit size of the file system entry. in a directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| upperSize | Upper 32-bit Size | <String> |
|
| lowerSize | Lower 32-bit Size | <String> |
|
F
20040512-18:07:52
Upper 32-bit Size: 0 Lower 32-bit Size: 340488704
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 for a QUERY request
will contain a marshalled <Map:STAF/Service/FS/QueryInfo>
representing information about the file system entry attributes.
The map is defined as follows:
Table 21. Definition of map class STAF/Service/FS/QueryInfo
| Description: This map class represents information about a file system entry attributes. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| type | Type | <String> |
|
| upperSize | Upper 32-bit Size | <String> |
|
| lowerSize | Lower 32-bit Size | <String> |
|
| lastModifiedTimestamp | Modified Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| Notes: The values for "Type", "Upper 32-bit Size", "Lower 32-bit Size", and "Last Modification Time" are formatted as specified in section 8.4.5, "GET ENTRY". | |||
Name : /tests/project.tar.gz Type : F Upper 32-bit Size : 0 Lower 32-bit Size : 340488704 Modified Date-Time: 20040512-18:07:52
LIST DIRECTORY retrieves the contents of a directory.
LIST DIRECTORY <Name> [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
[CASESENSITIVE | CASEINSENSITIVE] [LONG [DETAILS]] [RECURSE]
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 (and child entries in its subdirectories if the RECURSE option is specified). 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. (and child entries in its subdirectories if the RECURSE option is specified). 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.
DETAILS specifies to provide more details about the child entries. Specifically, the upper 32-bit size and lower 32-bit size will be shown in separate fields and the size will be shown in bytes instead of rounding the size in kilobytes or megabytes.
RECURSE specifies that any subdirectories will be recursively listed.
This command requires trust level 2.
All return codes from LIST DIRECTORY are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the contents of the specified directory as follows:
Table 22. Definition of map class STAF/Service/FS/ListLongInfo
| Description: This map class represents information about an entry in a specified directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| type | Type | <String> |
|
| size | Size | <String> |
|
| lastModifiedTimestamp | Modified Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| name | Name | <String> |
|
| Notes: The "Size" value 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. | |||
Table 23. Definition of map class STAF/Service/FS/ListDetailsInfo
| Description: This map class represents detailed information about an entry in a specified directory. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| type | Type | <String> |
|
| upperSize | U-Size | <String> |
|
| lowerSize | L-Size | <String> |
|
| lastModifiedTimestamp | Modified Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| Notes: The "U-Size" value is the upper 32-bits of the size and the "L-Size" value is the lower 32-bits of the size. The sizes are shown in bytes. | |||
en_platformsdk_win2003.exe 2-ltp-logfile test1 project-docs.tar ACME_NEW2.xml project.htm AutoFVT.bsh
Type Size Modified Date-Time Name ---- ----- ------------------ -------------------------- F 324M 20040512-18:07:52 en_platformsdk_win2003.exe F 323 20040706-16:13:10 2-ltp-logfile D 0 20040728-11:21:44 test1 F 1210K 20040517-11:57:10 project-docs.tar F 258K 20040412-11:49:06 ACME_NEW2.xml F 12505 20030506-19:14:40 project.htm F 44 20040928-16:24:40 AutoFVT.bsh
Name Type U-Size L-Size Modified Date-Time -------------------------- ---- ------ --------- ------------------ test1 D 0 0 20040728-11:21:44 AutoFVT.bsh F 0 44 20040928-16:24:40 2-ltp-logfile F 0 323 20040706-16:13:10 project.htm F 0 12505 20030506-19:14:40 ACME_NEW2.xml F 0 264691 20040412-11:49:06 project-docs.tar F 0 1239040 20040517-11:57:10 en_platformsdk_win2003.exe F 0 340488704 20040512-18:07:52
Type Size Modified Date-Time Name ---- ----- ------------------ -------------------------- F 323 20040706-16:13:10 2-ltp-logfile F 258K 20040412-11:49:06 ACME_NEW2.xml F 44 20040928-16:24:40 AutoFVT.bsh F 324M 20040512-18:07:52 en_platformsdk_win2003.exe F 1210K 20040517-11:57:10 project-docs.tar F 12505 20030506-19:14:40 project.htm
javacore.20030420.041412.7713.txt windoc.txt mytest.txt svt-spa02dynos390.txt
hello.txt test1/docs/hello.txt test1/backup/docs/hello.txt test4/hello.txt
Name Type U-Size L-Size Modified Date-Time ---------------------------------- ---- ------ ------ ------------------ icu\source\test\testdata\test1.ucm F 0 871 20031028-19:18:22 test1 D 0 0 20030707-11:47:40 test1.bak F 0 83 20030919-11:10:22 test4\test1.txt F 0 34 20060331-13:03:04
LIST COPYREQUESTS displays the File System copy requests currently in progress.
LIST COPYREQUESTS [LONG] [INBOUND] [OUTBOUND]
[FILE [[BINARY] [TEXT]]] [DIRECTORY[
COPYREQUESTS specifies to list the COPY requests currently in progress.
LONG specifies to list more detailed information about the copy requests, such as the copy mode and current state of the copy request.
INBOUND specifies to list COPY requests that are copying to the machine.
OUTBOUND specifies to list COPY requests that are copying from the machine.
FILE specifies to list COPY FILE requests.
BINARY specifies to list COPY FILE requests that are copying a file in binary format.
TEXT specifies to list COPY FILE requests that are copying a file in text format.
DIRECTORY specifies to list COPY DIRECTORY requests.
If none of the optional options are specified (other than a LONG option), all of the copy requests currently in progress will be shown.
This command requires trust level 2.
All return codes from LIST COPYREQUESTS are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a list of the copy requests currently in progress as follows:
Table 24. Definition of map class STAF/Service/FS/CopyRequest
| Description: This map class represents a copy request in progress. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | Name | <String> |
|
| type | Type | <String> | 'D' | 'F' |
Notes:
| |||
The maps used in representing detailed information about copy requests
are defined as follows:
Table 25. Definition of map class STAF/Service/FS/CopyFile
| Description: This map class represents detailed information about a file being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | File Name | <String> |
|
| type | Type | <String> | 'F' |
| mode | Mode | <String> | 'Binary' | 'Text' |
| state | Transfer State | <Map:STAF/Service/FS/FileCopyState> |
|
Notes:
| |||
Table 26. Definition of map class STAF/Service/FS/FileCopyState
| Description: This map class represents detailed information about the state of a file being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| fileSize | File Size | <String> | <None> |
|
| bytesCopied | Bytes Copied | <String> |
|
Notes:
| |||
Table 27. Definition of map class STAF/Service/FS/CopyDirectory
| Description: This map class represents detailed information about a directory being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| io | In/Out
(I/O) | <String> | 'In' | 'Out' |
| machine | Machine | <String> |
|
| name | File Name | <String> |
|
| type | Type | <String> | 'D' |
| state | Transfer State | <Map:STAF/Service/FS/DirectoryCopyState> |
|
| Notes: | |||
Table 28. Definition of map class STAF/Service/FS/DirectoryCopyState
| Description: This map class represents detailed information about the state of the directory being copied. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| mode | Mode | <String> | 'Binary' | 'Text' |
| fileSize | File Size | <String> | <None> |
|
| bytesCopied | Bytes Copied | <String> |
|
Notes:
| |||
Start Date-Time I/O Machine Name Type
----------------- --- ---------------------- ------------------------- ----
20050725-18:31:32 Out tcp://client2.company. c:/temp/TestA D
com
20050725-18:31:38 Out tcp://client1.company. c:/tests/Instructions.txt F
com@6500
20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F
20050725-18:31:41 Out tcp://client3.company. c:/tests/TestB/TestB.zip F
com
20050725-18:32:05 In client2.company.com c:/tests/TestC D
[
{
Start Date-Time: 20050725-18:31:32
In/Out : Out
Machine : tcp://client2.company.com
Directory Name : c:/temp/TestA
Type : D
Transfer State : {
Name : c:/temp/TestA/TestA.zip
Mode : Binary
File Size : 9873006
Bytes Copied: 1288000
}
}
{
Start Date-Time: 20050725-18:31:38
In/Out : Out
Machine : tcp://client1.company.com@6500
File Name : c:/tests/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : 26019
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:38
In/Out : In
Machine : client1.company.com
File Name : c:/temp/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : <None>
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
{
Start Date-Time: 20050725-18:32:05
In/Out : In
Machine : client2.company.com
Directory Name : c:/temp/TestC
Type : D
Transfer State : {
Name : c:/temp/TestC/TestC.txt
Mode : Text
File Size : <None>
Bytes Copied: 8000
}
}
]
Start Date-Time In/Out Machine Name Type ----------------- ------ ------------------- ------------------------ ---- 20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F
[
{
Start Date-Time: 20050725-18:31:38
In/Out : Out
Machine : tcp://client1.company.com@6500
File Name : c:/tests/Instructions.txt
Type : F
Mode : Text
Transfer State : {
File Size : 26019
Bytes Copied: 12000
}
}
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
]
[
{
Start Date-Time: 20050725-18:31:41
In/Out : Out
Machine : tcp://client3.company.com
File Name : c:/temp/TestB/TestB.zip
Type : F
Mode : Binary
Transfer State : {
File Size : 70483006
Bytes Copied: 63614000
}
}
]
LIST SETTINGS shows the operational settings for the FS service.
LIST SETTINGS
SETTINGS specifies that you want to list the current operational settings for the FS service.
This command requires trust level 2.
All return codes from LIST SETTINGS are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a marshalled
<Map:STAF/Service/FS/Settings> representing the current
settings for the File System service.
The map is defined as follows:
Table 29. Definition of map class STAF/Service/FS/Settings
| Description: This map class represents the operational settings for the File System service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| strictFSCopyTrust | Strict FS Copy Trust | <String> | 'Enabled' | 'Disabled' |
Strict FS Copy Trust: Disabled
CREATE creates a directory.
CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
DIRECTORY specifies the name of the directory to create. This option will resolve variables.
FULLPATH specifies that any intermediate parent directories should be created if they don't exist.
FAILIFEXISTS specifies that the request should generate an error if the specified directory 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.
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".
Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.
SET STRICTFSCOPYTRUST <Enabled | Disabled>
See section 4.7, "Operational parameters" for a description of this option. Note that setting STRICTFSCOPYTRUST Enabled is equivalent to setting the STRICTFSCOPYTRUST operational parameter in the STAF configuration file. Setting STRICTFSCOPYTRUST Disabled is equivalent to not setting the STRICTFSCOPYTRUST operational parameter in the STAF configuration file.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET STRICTFSCOPYTRUST Enabled
The HANDLE service is one of the internal STAF services. It provides the following commands.
CREATE creates a static handle. A static handle is a handle which can be shared by several processes on the same system. This is most directly useful for shell-scripts which rely on the STAF command, and need to ensure that the same handle is used for every request. See "Using the STAF command from shell-scripts" for more information on how to use static handles with the STAF command.
Note: Be sure to DELETE any static handles you create via the CREATE command.
CREATE HANDLE NAME <Handle Name>
NAME specifies the registered name of the handle.
This command 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.
DELETE deletes a static handle.
DELETE HANDLE <Number>
HANDLE specifies the handle number to delete.
This command requires trust level 5.
Note: This command is only valid if submitted to the local machine, not to remote machines.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
LIST allows you to display brief information about all handles, or about groups of handles by name or state. Note that if you do not specify a set of states to display, it will show only those that are in REGISTERED, INPROCESS, and STATIC states. To see all processes, specify PENDING, REGISTERED, INPROCESS, and STATIC.
LIST [HANDLES [NAME <Handle Name>] [LONG]
[PENDING] [REGISTERED] [INPROCESS] [STATIC]]
HANDLES specifies that you want to list information about handles.
NAME specifies that you only want information on handles with the name <Handle Name>.
LONG specifies to list more detailed information on the handles, such as the process id (PID) used by each handle.
PENDING shows handles that are in a pending state. A handle is in pending state when a process has been started via the PROCESS service, but that process has not yet registered with STAF.
REGISTERED shows handles that are registered with STAF.
INPROCESS shows handles for external services that are running within the same process as STAFProc.
STATIC shows static handles. A static handle is a handle which was created using the CREATE command of the HANDLE service or by using the STATICHANDLENAME option when starting a process through the PROCESS service.
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 handles as follows:
Table 30. Definition of map class STAF/Service/Handle/HandleInfo
| Description: This map class represents status of a handle. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| name | Handle Name
(Name) | <String> | <None> |
|
| state | State | <String> |
|
| lastUsedTimestamp | Last Used Date-Time
(Last Used) | <String> | <YYYYMMDD-HH:MM:SS> |
Table 31. Definition of map class STAF/Service/Handle/HandleInfoLong
| Description: This map class represents detailed information about the status of a handle. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| name | Handle Name
(Name) | <String> | <None> |
|
| state | State | <String> |
|
| lastUsedTimestamp | Last Used Date-Time
(Last Used) | <String> | <YYYYMMDD-HH:MM:SS> |
| pid | PID | <String> |
|
| Notes: The "PID" value will contain the process id assigned by the operating system. The process id for a static handle will be 0. | |||
Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20051205-12:41:42 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 4 STAF/Service/STAX Registered 20051205-12:41:51 5 STAF/Service/LOG InProcess 20051205-12:41:53 6 STAF/SERVICE/Event Registered 20051205-12:41:51 14 MyTest Registered 20051205-13:08:53 16 STAF/Client Registered 20051205-13:08:40 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time PID ------ ------------------------------- ---------- ------------------- ---- 1 STAF_Process InProcess 20051205-12:41:42 1636 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 2360 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 1636 4 STAF/Service/STAX Registered 20051205-12:41:51 2844 5 STAF/Service/LOG InProcess 20051205-12:41:53 1636 6 STAF/SERVICE/Event Registered 20051205-12:41:51 2844 14 MyTest Registered 20051205-13:08:53 2892 16 STAF/Client Registered 20051205-13:16:40 2900
Handle Handle Name State Last Used Date-Time ------ ----------- ---------- ------------------- 14 MyTest Registered 20051205-13:08:53
Handle Handle Name State Last Used Date-Time ------ ----------- ------ ------------------- 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time ------ ----------- ------- ------------------- 17 <None> Pending 20051205-13:16:55 23 <None> Pending 20051205-13:18:59
QUERY will allow you to display detailed information about a given handle number.
QUERY HANDLE <Handle>
HANDLE specifies the handle number you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a marshalled
<Map:STAF/Service/Handle/QueryHandle> representing
the handles, handle name, state, last used date and time,
operating system process id, authenticator, and user identifier.
The map is defined as follows:
Table 32. Definition of map class STAF/Service/Handle/QueryHandle
| Description: This map class represents status of a handle. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle | <String> |
|
| name | Handle Name | <String> | <None> |
|
| state | State | <String> |
|
| lastUsedTimestamp | Last Used Date-Time
(Last Used) | <String> | <YYYYMMDD-HH:MM:SS> |
| pid | PID | <String> |
|
| user | User | <String> | <Authenticator>://<UserID> |
Notes:
| |||
Handle : 1 Handle Name : STAF_Process State : InProcess Last Used Date-Time: 20051205-12:41:42 PID : 1636 User : none://anonymous
AUTHENTICATE authenticates the handle submitting the request. An authenticated handle has the specified user identifier and authentiator associated with it. you
AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials>
[AUTHENTICATOR <Name>]
USER specifies the user identifier to authenticate.
CREDENTIALS specifies the credentials for the user identifier, such as a password.
AUTHENTICATOR specifies the name of the Authenticator to use to authenticate the handle instead of the default Authenticator.
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 AUTHENTICATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
UNAUTHENTICATE un-authenticates the handle submitting the request. An unauthenticated handle has user 'none://anonymous' associated with it. you
UNAUTHENTICATE
This command requires trust level 5.
Note: This command is only valid if submitted to the local machine, not to remote machines.
All return codes from UNAUTHENTICATE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will be empty.
Note: Error codes of 4000 and beyond are service specific return codes, and not all external services register their return codes with the Help service. Therefore, if you don't find information on a 4000+ return code returned by a service, be sure to check the documentation provided with the service.
The Help service provides the following commands.
LIST SERVICES | [SERVICE <Service name>] ERRORS
SERVICES will list all the services that have registered their return codes with the Help service.
SERVICE specifies that return codes for the specified service should be listed, as opposed to the common return codes.
ERRORS will list return codes and a short description of each.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
The result buffer for a "LIST ERRORS" or
"LIST ERRORS SERVICE <Service Name>" request will contain a
marshalled <List> of <Map:STAF/Service/Help/ErrorInfo>
representing the errors that can be generated by STAF internal services or
for a specific external service. The map is defined as follows:
Table 33. Definition of map class STAF/Service/Help/ErrorInfo
| Description: This map class represents information about an error. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| returnCode | Return Code | <String> |
|
| description | Description | <String> |
|
| Notes: The value for "Description" will be a short description of the error. | |||
Syntax: LIST ERRORS
Results:
Return Code Description ----------- ------------------------------ 0 No error 1 Invalid API 2 Unknown service 3 Invalid handle 4 Handle already exists 5 Handle does not exist 6 Unknown error 7 Invalid request string 8 Invalid service result 9 REXX Error 10 Base operating system error 11 Process already complete 12 Process not complete 13 Variable does not exist 14 Unresolvable string 15 Invalid resolve string 16 No path to endpoint 17 File open error 18 File read error 19 File write error 20 File delete error 21 STAF not running 22 Communication error 23 Trusteee does not exist 24 Invalid trust level 25 Insufficient trust leevl 26 Registration error 27 Service configuration error 28 Queue full 29 No queue element 30 Notifiee does not exist 31 Invalid API level 32 Service not unregisterable 33 Service not available 34 Semaphore does not exist 35 Not sempahore owner 36 Semaphore has pending requests 37 Timeout 38 Java error 39 Converter error 40 Not used 41 Invalid object 42 Invalid parm 43 Request number not found 44 Invalid asynchronous option 45 Request not complete 46 Process authentication denied 47 Invalid value 48 Does not exist 49 Already exists 50 Directory Not Empty 51 Directory Copy Error 52 Diagnostics Not Enabled 53 Handle Authentication Denied 54 Handle Already Authenticated 55 Invalid STAF Version 4000+ Service specific errors
Syntax: LIST SERVICE Log ERRORS
Results: If the request is issued from the command line, the result, in table format, could look like:
Return Code Description ----------- ------------------------------- 4004 Invalid level 4007 Invalid file format 4008 Unable to purge all log records
Syntax: LIST SERVICES
Results: If the request is issued from the command line, the result, in default format, could look like:
EVENT LOG RESPOOL STAX
[SERVICE <Service name>] ERROR <Return code>
SERVICE indicates that only information specific to the given service should be return. Otherwise, information will be returned for all services which have registered the indicated return code.
ERROR specifies the return code about which you want information
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 34. Definition of map class STAF/Service/Help/ErrorDetails
| Description: This map class represents information about an error. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| description | Description | <String> |
|
| details | Details | <String> |
|
Table 35. Definition of map class STAF/Service/Help/ErrorDetails
| Description: This map class represents information about an error registered by an external service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| service | Service | <String> |
|
| description | Description | <String> |
|
| details | Details | <String> |
|
Syntax: ERROR 22
Results: If the request is issued from the command line, the result, in default format, could look like:
Description: Communication error Details : This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request.
Syntax: ERROR 4007
Results: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Service : LOG
Description: Invalid file format
Details : An invalid/unknown record format was encountered while reading the log file
}
{
Service : RESPOOL
Description: Resource pool has no entries available
Details : The resource pool has no entries
}
]
Syntax: SERVICE Log ERROR 4007
Results: If the request is issued from the command line, the result, in default format, could look like:
Description: Invalid file format Details : An invalid/unknown record format was encountered while reading the log file
REGISTER SERVICE <Service name> ERROR <Return code>
INFO <String> DESCRIPTION <String>
SERVICE indicates the service for which to register information
ERROR indicates the return code for which to register information
INFO specifies a short description string which is displayed when using the Help service's LIST command.
DESCRIPTION specifies the full information about the return code. This information is displayed when using the Help service's ERROR command.
This command requires trust level 3.
This command is only valid when issued by local services.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
REGISTER SERVICE Log ERROR 4008 INFO "Unable to purge all log records" DESCRIPTION "Your PURGE criteria selected every record in the log file. Use DELETE if you{STAF/Config/Sep/Line}really want to delete every record. Or, modify your PURGE criteria."
UNREGISTER SERVICE <Service name> ERROR <Return code>
SERVICE indicates the service for which to unregister information
ERROR indicates the return code for which to unregister information
This command is only valid when issued by local services.
All return codes are documented in Appendix A, "API Return Codes".
If successful, the result buffer will be empty.
Syntax:
UNREGISTER SERVICE Log ERROR 4008
All return codes from Help are documented in Appendix A, "API Return Codes".
The purpose of the Log service is to allow a test case to easily and flexibly manage information that needs to be logged. It allows you to specify a log mask which defines which messages actually get logged to the log file. This log mask can be dynamically changed to alter the set of log messages written to the log file(s). This can greatly assist in debugging. For example, while a test case is running, you can dynamically alter the log mask to allow debug and trace log messages to start being logged. The log query mechanism allows for record selection based on many selection criteria matches.
The Log service can be run in one of two modes. In local mode, all log requests are handled locally, and all log files are stored locally. In remote mode, all log requests are forwarded to a central system for processing. In addition, all log files are stored on the central system. While it is possible to delegate the log service to a central system, this has some unwanted side effects. The primary one being that many unwanted messages are likely to be sent over the network, consuming time and bandwidth.
The following is an example of the major difference between delegating the Log service and using the Log service in remote logging mode.
Example Delegated Log
NETWORK
start ! start
info ! info
warning ! warning
+------+ trace +-----------+ ! trace +-------+
! TEST !-> debug -> ! STAF !-> ! debug -> ! STAF ! -> WRITE LOG
! CASE ! trace ! DELEGATED ! ! trace ! LOG ! =========
+------+ error ! LOG ! ! error ! Mask= ! error
debug +-----------+ ! debug ! Error ! fail
trace ! trace ! Fail !
debug ! debug +-------+
fail ! fail
Example Remote Logging
NETWORK
start !
info !
warning !
+------+ trace +-----------+ ! +------+
! TEST !-> debug -> ! LOG !-> ! error -> ! STAF ! -> WRITE LOG
! CASE ! trace ! Mask= ! ! fail ! LOG ! =========
+------+ error ! Error ! ! +------+ error
debug ! Fail ! ! fail
trace +-----------+ !
debug !
fail !
In the above Delegated Log service example, all the messages flowed over the network to the ultimate log server even though only error and fail conditions were selected to be logged. In the above Remote Logging example, the selection of the messages occur at the local box and only those messages that are selected get sent over the network to the ultimate log server.
Note: When using the Log service in remote logging mode, you should have the log mask disabled (i.e. log everything) at the ultimate log server to avoid confusion and multiple log mask filtering.
SERVICE <Name> LIBRARY STAFLog [PARMS <Log parameters>]
<Name> is the name by which the Log service will be known on this machine. The recommended name of the Log service is "LOG"
<Log parameters> are valid log parameters described below.
service log library STAFLog
service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata ResolveMessage"
The Log service accepts a parameter string in the following formats
[DIRECTORY <Log Directory Root>] [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>] [RESOLVEMESSAGE | NORESOLVEMESSAGE] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]or
ENABLEREMOTELOGGING REMOTELOGSERVER <Server name>
[REMOTELOGSERVICE <Service Name>]
DIRECTORY specifies the root directory under which log files are stored. The default is {STAF/DataDir}/service/<Service Name (lower-case)>.
Note: Previously, in STAF 2.x, the default root directory was {STAF/Config/STAFRoot}/data/log. So, if you want to continue to use the STAF 2.x log files with the current version of STAF, move the log files to the new default root directory or specify the old root directory for the DIRECTORY parameter.
MAXRECORDSIZE specifies the maximum length (in characters) of a logged message. The default is 100000.
DEFAULTMAXQUERYRECORDS specifies the maximum number of records that will be returned if your query criteria selects more records than this number. The default is 100. If no limit on the maximum number of records returned by a query is desired, specify 0. If a non-zero value is specified, it's equivalent to specifying LAST <Number>. This limit is only used if none of the following options are specified on a QUERY request: FIRST, LAST, ALL, TOTAL, or STATS.
RESOLVEMESSAGE specifies that variables in log messages should be resolved by default.
NORESOLVEMESSAGE specifies that variables in log messages should not be resolved by default. This is the default.
ENABLERESOLVEMESSAGEVAR specifies that the log service should check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. This option will adversely affect the performance of the Log service. See below for more information.
DISABLERESOLVEMESSAGEVAR specifies that the log service should not check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. See below for more information. This is the default.
ENABLEREMOTELOGGING specifies that the Log service should operate in remote/forwarding mode.
REMOTELOGSERVER specifies the server to which forwarded log requests should be sent. This machine must be running STAF V3.0.0 or later.
Note: From a trust perspective, the tcp interface names on the remote log server and on the machine forwarding requests to it must match or the remote log server must use a wildcard to match any interface in the trust statement for the machine that is forwarding log requests to it.
REMOTELOGSERVICE specifies the service to which forwarded log requests should be sent. The default is the same name under which the Log service was registered on the local machine.
Note: All these parameters, with the exception of DIRECTORY, ENABLEREMOTELOGGING, REMOTELOGSERVER, and REMOTELOGSERVICE may be changed with the SET command, see 8.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. Any private data in the message will be masked before writing to the log.
RESOLVEMESSAGE causes the LOG service to call the STAF variable service to resolve any variables in the message before being written. This 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.
The result buffer will contain no data on return from a LOG command.
Allows you to query records from a log based on a set of selection criteria.
Note: A stand-alone utility also exists, called FmtLog, that can read a log file and write the data to an output file in a readable format. See 9.1, "Format Log Utility" for additional information.
QUERY <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
[LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
[NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
[CONTAINS <String>]... [CSCONTAINS <String>]...
[STARTSWITH <String>]... [CSSTARTSWITH <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
[FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG]
[LEVELBITSTRING]
GLOBAL indicates you want to query to a global log. The global log is intended to facilitate multiple testcases on multiple machines all writing to a common log.
MACHINE indicates you want to query to a machine log. Specify the machine nickname. The machine log is intended to facilitate multiple testcases on a single machine all writing to a common log. This option will resolve variables.
HANDLE indicates you want to query to a handle log. The handle log is intended to facilitate each testcase writing to a separate log. This option will resolve variables.
LOGNAME contains the name of the log you want to query. All log files have the ".log" extension automatically added to the file name. This option will resolve variables.
LEVELMASK determines the levels that are selected. This can be in the form of "FATAL ERROR WARNING" or a 32 byte bit string such as "00000000000000000000000000000111". This option will resolve variables.
QMACHINE selects only those records that originated from a certain machine. Multiple QMACHINE statements are handled as an "or" condition. This option will resolve variables.
QHANDLE selects only those records that are associated with a certain handle. Multiple QHANDLE statements are handled as an "or" condition. This option will resolve variables.
NAME selects only those records with a certain registered name. Multiple NAME statements are handled as an "or" condition. This option will resolve variables.
USER selects only those records with a certain user. <User> format is <Authenticator>://<User Identifier> (e.g. none://anonymous, SampleAuth://johnDoe@company.com). Multiple USER statements are handled as an "or" condition. This option will resolve variables.
ENDPOINT selects only those records with a certain endpoint. Multiple ENDPOINT statements are handled as an "or" condition. This option will resolve variables.
CONTAINS selects only those records that contain a specified string in the message. Note that this match is case insensitive. Multiple CONTAINS statements are handled as an "or" condition. This option will resolve variables.
CSCONTAINS selects only those records that contain a specified string in the message. Note that this match is case sensitive. Multiple CSONTAINS statements are handled as an "or" condition. This option will resolve variables.
STARTSWITH selects only those records that start with a specified string in the message. Note that this match is case insensitive. Multiple STARTSWITH/CSSTARTSWITH statements are handled as an "or" condition. This option will resolve variables.
CSSTARTSWITH selects only those records that start with a specified string in the message. Note that this match is case sensitive. Multiple CSSTARTSWITH/STARTSWITH statements are handled as an "or" condition. This option will resolve variables.
FROM selects only those records that have a date and/or time from the specified format. This option will resolve variables.
AFTER selects only those records that have a date and/or time after the specified format. This option will resolve variables.
TO selects only those records that have a date and/or time to the specified format. This option will resolve variables.
BEFORE selects only those records that have a date and/or time before the specified format. This option will resolve variables.
Note: <Timestamp> format is date, @time, or date@time (e.g. 19980214, @16:30:45, 19980214@16:30:45)
Note: The keyword TODAY can be used for the current date in the FROM, AFTER, TO, BEFORE options.
FIRST selects only the first <num> records. This option will resolve variables.
LAST selects only the last <num> records. This option will resolve variables.
ALL selects all the records that meet the query criteria.
TOTAL display only the total number of records selected instead of the records themselves.
STATS display the totals for each level instead of the records themselves.
LONG displays all of the fields for each log record instead of just the timestamp, level, and message fields.
LEVELBITSTRING displays the selected records with the level displayed as a 32 byte binary bit string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error. See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.
This command requires trust level 2.
In addition to the return codes documented in Appendix A, "API Return Codes", QUERY also returns codes documented in 8.7.12, "Log Error Code Reference".
If the query criteria selects more records than allowed by the DefaultMaxQueryRecords parameter/setting (and none of the following options are specified: FIRST, LAST, ALL, TOTAL, or STATS), the return code will be set to 4010 and the result buffer will contain only the 'last' default maximum number of query records.
If successful, the result buffer will contain data based on the QUERY command:
Table 36. Definition of map class STAF/Service/Log/QueryStats
| Description: This map class represents the totals for the log levels of the selected records in the log. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| fatal | Fatal | <String> |
|
| error | Error | <String> |
|
| warning | Warning | <String> |
|
| info | Info | <String> |
|
| trace | Trace | <String> |
|
| trace2 | Trace2 | <String> |
|
| trace3 | Trace3 | <String> |
|
| debug | Debug | <String> |
|
| debug2 | Debug2 | <String> |
|
| debug3 | Debug3 | <String> |
|
| start | Start | <String> |
|
| stop | Stop | <String> |
|
| pass | Pass | <String> |
|
| fail | Fail | <String> |
|
| status | Status | <String> |
|
| user1 | User1 | <String> |
|
| user2 | User2 | <String> |
|
| user3 | User3 | <String> |
|
| user4 | User4 | <String> |
|
| user5 | User5 | <String> |
|
| user6 | User6 | <String> |
|
| user7 | User7 | <String> |
|
| user8 | User8 | <String> |
|
Table 37. Definition of map class STAF/Service/Log/LogRecordLong
| Description: This map class represents detailed information for a log record. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| machine | Machine | <String> |
|
| handle | Handle
(H#) | <String> |
|
| handleName | Handle Name
(Name) | <String> |
|
| user | User | <String> |
|
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| level | Level | <String> |
|
| message | Message | <String> |
|
Table 38. Definition of map class STAF/Service/Log/LogRecord
| Description: This map class represents a log record. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| level | Level | <String> |
|
| message | Message | <String> |
|
Assume this example log file called STRESSTST contains the following records:
Date-Time Machine H# Name User Endpoint Level Message ----------------- ---------------------- -- ------ ---------------- --------------------------------- ------- ---------------------------------- 20040810-18:04:00 automate.austin.ibm.com 37 Test1A none://anonymous local://local Start Stress Test 1A Initiated 20040810-19:37:15 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 1: processing time: 01:31:26 20040810-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 1: debug: files=23 threads=37 20040810-22:20:34 automate.austin.ibm.com 37 Test1A none://anonymous local://local Warning Step 2: File not ready, retry=3 20040810-22:21:01 automate.austin.ibm.com 37 Test1A none://anonymous local://local Info Step 2: File ready on retry 3 20040811-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 2: processing time: 03:02:41 20040811-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 20040810-01:37:25 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Trace Step 1: processing time: 03:11:53 20040810-01:43:46 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug Step 1: debug: files=43 threads=67 20040811-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local Error Step 3: Sharing buffer exceeded 20040811-02:54:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local User1 Step 3: Error recovery started 20040811-04:32:53 automate.austin.ibm.com 37 Test1A none://anonymous local://local User2 Step 3: Error recovery completed 20040811-04:33:49 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 3: processing time: 03:10:41 20040811-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 3: debug: files=78 threads=98 20040811-08:46:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local Stop Stress Test 1A Completed 20040811-08:47:21 automate.austin.ibm.com 37 Test1A none://anonymous local://local Pass Stress Test 1A: Errors=1 Recover=1 20040811-08:48:46 automate.austin.ibm.com 37 Test1A none://anonymous local://local Status Step1=P, Step2=P, Step3=W, TC=P
Note: The output for these examples are formatted for ease of reading in this document, the actual format will vary depending on whether the command is submitted via STAF.exe or via a program's submit(), etc. method.
Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
Results: If the request was issued from the command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ----- ---------------------------------- 20040810-19:37:15 Trace Step 1: processing time: 01:31:26 20040810-19:39:09 Debug Step 1: debug: files=23 threads=37 20040811-01:21:39 Trace Step 2: processing time: 03:02:41 20040811-01:21:58 Debug Step 2: debug: files=31 threads=54 20040810-01:37:25 Trace Step 1: processing time: 03:11:53 20040810-01:43:46 Debug Step 1: debug: files=43 threads=67 20040811-04:33:49 Trace Step 3: processing time: 03:10:41 20040811-04:34:07 Debug Step 3: debug: files=78 threads=98
Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "ERROR"
Results: If the request was issued from the command line, the result in table format, could look like:
Date-Time Level Message ----------------- ----- ------------------------------- 20040811-02:53:20 Error Step 3: Sharing buffer exceeded
Syntax: QUERY GLOBAL LOGNAME stresstst total
Results:
17
Syntax: QUERY GLOBAL LOGNAME stresstst FROM 20040810@19:00:00 QMACHINE automate to today@08:00:00
Results: If the request was issued from the command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ------- ---------------------------------- 20040810-19:37:15 Trace Step 1: processing time: 01:31:26 20040810-19:39:09 Debug Step 1: debug: files=23 threads=37 20040810-22:20:34 Warning Step 2: File not ready, retry=3 20040810-22:21:01 Info Step 2: File ready on retry 3 20040811-01:21:39 Trace Step 2: processing time: 03:02:41 20040811-01:21:58 Debug Step 2: debug: files=31 threads=54 20040811-02:53:20 Error Step 3: Sharing buffer exceeded 20040811-02:54:22 User1 Step 3: Error recovery started 20040811-04:32:53 User2 Step 3: Error recovery completed 20040811-04:33:49 Trace Step 3: processing time: 03:10:41 20040811-04:34:07 Debug Step 3: debug: files=78 threads=98
Syntax: QUERY LONG GLOBAL LOGNAME stresstst FROM 20040810@19:00:00 to today@08:00:00 CONTAINS threads CONTAINS buffer
Results: If the request was issued from the command line, the result, in table format, could look like:
Date-Time Machine H# Name User Endpoint Level Message ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 20040810-01:43:46 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug Step 1: debug: files=43 threads=67 20040810-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 1: debug: files=23 threads=37 20040811-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 20040811-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local Error Step 3: Sharing buffer exceeded 20040811-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 3: debug: files=78 threads=98
Syntax: QUERY LONG GLOBAL LOGNAME stresstst CSCONTAINS "Step 1:" CSCONTAINS "Step 2:"
Results: If the request was issued from the command line, the result, in verbose format, could look like:
[
{
Date-Time : 20040810-19:39:09
Machine : crazy8s.austin.ibm.com
Handle : 41
Handle Name: Test2
User : none://anonymous
Endpoint : tcp://crazy8s.austin.ibm.com@6500
Level : Debug
Message : Step 1: debug: files=43 threads=67
}
{
Date-Time : 20040810-19:39:09
Machine : automate.austin.ibm.com
Handle : 37
Handle Name: Test1A
User : none://anonymous
Endpoint : local://local
Level : Debug
Message : Step 1: debug: files=23 threads=37
}
{
Date-Time : 20040811-01:21:58
Machine : automate.austin.ibm.com
Handle : 37
Handle Name: Test1A
User : none://anonymous
Endpoint : local://local
Level : Debug
Message : Step 2: debug: files=31 threads=54
}
]
Syntax: QUERY GLOBAL LOGNAME stresstst STATS
Results: If the request was issued from the command line, the result, in default format, could look like:
Fatal : 0 Error : 1 Warning: 1 Info : 1 Trace : 4 Trace2 : 0 Trace3 : 0 Debug : 4 Debug2 : 0 Debug3 : 0 Start : 1 Stop : 1 Pass : 1 Fail : 0 Status : 1 User1 : 1 User2 : 1 User3 : 0 User4 : 0 User5 : 0 User6 : 0 User7 : 0 User8 : 0
LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLES | HANDLE <Handle>]or
LIST SETTINGS
GLOBAL indicates you want to list all global logs.
MACHINES indicates you want to list all the machines which have created machine logs.
MACHINE indicates you want to list all the machine logs for the specified machine nickname. This option will resolve variables.
HANDLES indicates you want to list all the handles that have created handle logs for the given machine.
HANDLE indicates you want to list all the handle logs for the specified handle of the specified machine. This option will resolve variables.
SETTINGS indicates you want to list the current operational settings.
This command requires trust level 2.
In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns codes documented in 8.7.12, "Log Error Code Reference".
If successful, the result buffer will contain data based on the LIST command:
If option MACHINE is specified without the HANDLES option, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Log/ListLogs>, which represents the machine logs for the specified machine nickname.
If both options MACHINE and HANDLE are specified, the result buffer will contain a marshalled <List> of <Map:STAF/Service/Log/ListLogs>, which represents the handle logs for the specified machine nickname and handle.
The map is defined as follows:
Table 39. Definition of map class STAF/Service/Log/ListLogs
| Description: This map class represents a log file. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| logName | Log Name | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| upperSize | U-Size | <String> |
|
| size | L-Size | <String> |
|
| Notes: The "U-Size" value is the upper 32-bits of the size and the "L-Size" value is the lower 32-bits of the size. The sizes are shown in bytes. | |||
Table 40. Definition of map class STAF/Service/Log/ListLocalSettings
| Description: This map class represents the settings for a Log service whose logging mode is local. | |||
| Key Name | Display Name | Type | Value / Format |
|---|---|---|---|
| loggingMode | Logging Mode | <String> | 'Local' |
| directory | Directory | <String> |
|
| maxRecordSize | Max Record Size | <String> |
|
| defaultMaxQueryRecords | Default Max Query Records | <String> |
|
| resolveMessage | Resolve Message | <String> | 'Enabled' | 'Disabled' |
| resolveMessageVar | Resolve Message Var | <String> | 'Enabled' | 'Disabled' |
Table 41. Definition of map class STAF/Service/Log/ListRemoteSettings
| Description: This map class represents the settings for a Log service whose logging mode is remote. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| loggingMode | Logging Mode | <String> | 'Remote' |
| remoteLogServer | Remote Log Server | <String> |
|
| remoteLogService | Remote Log Service | <String> |
|
Syntax: LIST GLOBAL
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size --------- ----------------- ------ ------ StressTST 20040810-14:17:00 0 120823 Suite100 20040811-15:45:00 0 2622
Syntax: LIST MACHINES
Results: If the request is submitted from the command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
Syntax: LIST MACHINE automate.austin.ibm.com
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ AutoGlob 20040810-10:54:00 0 1168
Syntax: LIST MACHINE automate.austin.ibm.com HANDLES
Results: If the request is submitted from the command line, the result could look like:
42 43 44 45
Syntax: LIST MACHINE automate.austin.ibm.com HANDLE 43
Results: If the request is submitted from the command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ HandLog1 20040810-10:54:00 0 19043 HandLog2 20040811-18:23:00 0 45264
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Logging Mode : Local Directory : C:\STAF\data\STAF\service\log Max Record Size : 100000 Default Max Query Records: 100 Resolve Message : Disabled Resolve Message Var : Disabled
DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME<Logname> CONFIRM
GLOBAL indicates you want to delete a global log.
MACHINE indicates you want to delete a machine log. Specify the machine nickname. This option will resolve variables.
HANDLE indicates you want to delete a handle log. This option will resolve variables.
LOGNAME contains the name of the log you want to delete. This option will resolve variables.
CONFIRM confirms you really want to delete the log file.
This command requires trust level 4.
In addition to the return codes documented in Appendix A, "API Return Codes", DELETE also returns codes documented in 8.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>]... [USER <User>]... [ENDPOINT <Endpoint>]...
[CONTAINS <String>]... [CSCONTAINS <String>]...
[STARTSWITH <String>]... [CSSTARTSWITH <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
[FIRST <Num> | LAST <Num>]
GLOBAL indicates you want to purge a global log.
MACHINE indicates you want to purge a machine log. Specify the machine nickname. This option will resolve variables.
HANDLE indicates you want to purge a handle log. This option will resolve variables.
LOGNAME contains the name of the log you want to purge. This option will resolve variables.
CONFIRM confirms you really want to purge the log file.
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 TOTAL, STATS, ALL, LONG, and LEVELBITSTRING 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.
In addition to the return codes documented in Appendix A, "API Return Codes", PURGE also returns codes documented in 8.7.12, "Log Error Code Reference".
The result buffer will contain a marshalled
<Map:STAF/Service/Log/PurgeStats>, representing
the number of log records that were purged and the total number of
log records. The map is defined as follows:
Table 42. Definition of map class STAF/Service/Log/PurgeStats
| Description: This map class respresents the purge statistics for the log. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| purgedRecords | Purged Records | <String> |
|
| totalRecords | Total Records | <String> |
|
For example, suppose you submitted a PURGE request for a log that contained 129 records and 21 of the records met the purge criteria you specified. If the PURGE request was submitted from the command line, the result could look like:
Purged Records: 21 Total Records : 129
Syntax: PURGE GLOBAL LOGNAME stresstst CONFIRM LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
Results: If the PURGE request was issued from the command line, the result could look like:
Purged Records: 8 Total Records : 17
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
[RESOLVEMESSAGE | NORESOLVEMESSAGE]
See section 8.7.3, "Parameters" for a description of these options.
This command requires trust level 5.
In addition to the return codes documented in Appendix A, "API Return Codes", SET also returns codes documented in 8.7.12, "Log Error Code Reference".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET MaxRecordSize 150000
Syntax: SET DefaultMaxQueryRecords 50
Syntax: SET ResolveMessage
Table 43. Logging Levels Reference
| Level Definition | 32 Byte Bit String Representation |
|---|---|
| Fatal | 00000000000000000000000000000001 |
| Error | 00000000000000000000000000000010 |
| Warning | 00000000000000000000000000000100 |
| Info | 00000000000000000000000000001000 |
| Trace | 00000000000000000000000000010000 |
| Trace2 | 00000000000000000000000000100000 |
| Trace3 | 00000000000000000000000001000000 |
| Debug | 00000000000000000000000010000000 |
| Debug2 | 00000000000000000000000100000000 |
| Debug3 | 00000000000000000000001000000000 |
| Start | 00000000000000000000010000000000 |
| Stop | 00000000000000000000100000000000 |
| Pass | 00000000000000000001000000000000 |
| Fail | 00000000000000000010000000000000 |
| Status | 00000000000000000100000000000000 |
| <Reserved1> | 00000000000000001000000000000000 |
| <Reserved2> | 00000000000000010000000000000000 |
| <Reserved3> | 00000000000000100000000000000000 |
| <Reserved4> | 00000000000001000000000000000000 |
| <Reserved5> | 00000000000010000000000000000000 |
| <Reserved6> | 00000000000100000000000000000000 |
| <Reserved7> | 00000000001000000000000000000000 |
| <Reserved8> | 00000000010000000000000000000000 |
| <Reserved9> | 00000000100000000000000000000000 |
| User1 | 00000001000000000000000000000000 |
| User2 | 00000010000000000000000000000000 |
| User3 | 00000100000000000000000000000000 |
| User4 | 00001000000000000000000000000000 |
| User5 | 00010000000000000000000000000000 |
| User6 | 00100000000000000000000000000000 |
| User7 | 01000000000000000000000000000000 |
| User8 | 10000000000000000000000000000000 |
Note: The User1-8 logging levels have been set aside for the user of STAFLog to implement as deemed necessary. You may decide that for a testcase or test suite that you want to log a certain behavior as "User1" for example. This will enable you to easily extract log records associated with level "User1".
Note: The <Reserved1-8> levels cannot be used and as the name implies, they are reserved by STAF for future use. If you would like to see a common logging level added to this list, please contact the document owners for discussion.
In addition to the common STAF return codes (see Appendix A, "API Return Codes" for additional information),
the following Log return codes are defined:
Table 44. Log Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4004 | Invalid level specified | An invalid logging level was specified, See 8.7.11, "Logging Levels Reference" for a complete list of logging levels. |
| 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. |
| 4010 | Exceeded default maximum query records | Your query criteria selected more records than allowed by the DefaultMaxQueryRecords setting. Use the FIRST <Num> or LAST <Num> option to specify the number of records or the ALL option if you really want all of the records. |
The MISC service is one of the internal STAF services. It provides a home for miscellaneous commands.
VERSION will display the STAF version number that is currently running.
VERSION
This command requires trust level 1.
All return codes from VERSION are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain the version number.
Syntax:
VERSION
Results:
3.0.0
WHOAMI will display information about who a system thinks you are. This can be useful in debugging trust issues and other problems.
WHOAMI
This command requires trust level 1.
All return codes from WHOAMI are documented in Appendix A, "API Return Codes".
On successful return, the result buffer for a WHOAMI request
will contain a marshalled <Map:STAF/Service/Misc/Whoami>
representing information about who a system thinks you are.
The map is defined as follows:
Table 45. Definition of map class STAF/Service/Misc/Whoami
| Description: This map class represents information about who a system thinks you are. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| instanceName | Instance Name | <String> |
|
| instanceUUID | Instance UUID | <String> |
|
| requestNumber | Request Number | <String> |
|
| interface | Interface | <String> |
|
| logicalID | Logical ID | <String> |
|
| physicalID | Physical ID | <String> |
|
| endpoint | Endpoint | <String> |
|
| machine | Macine | <String> |
|
| machineNickname | Machine Nickname | <String> |
|
| isLocalRequest | Local Request | <String> | 'Yes' | 'No' |
| handle | Handle | <String> |
|
| handleName | Handle Name | <String> |
|
| user | User | <String> |
|
| trustLevel | Trust Level | <String> |
|
Notes:
| |||
Syntax:
WHOAMI
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Request Number : 1812 Interface : tcp Logical ID : server1.austin.ibm.com Physical ID : 9.41.53.147 Endpoint : tcp://server1.austin.ibm.com@6500 Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : No Handle : 33 Handle Name : myHandle User : authSample://User1 Trust Level : 5
Syntax:
WHOAMI
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Request Number : 92 Interface : local Logical ID : local Physical ID : local Endpoint : local://local Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : Yes Handle : 29 Handle Name : STAF/Client User : none://anonymous Trust Level : 5
WHOAREYOU will display information a system, usch as the STAF instance name, instance UUID, machine name (the value of the STAF/Config/Machine system variable for the machine), machine nickname, (the value of the STAF/Config/MachineNickname variable for the machine) and if it's the same system as the machine who submitted the request.
WHOAREYOU
This command requires trust level 1.
All return codes from WHOAREYOU are documented in Appendix A, "API Return Codes".
On successful return, the result buffer for a WHOAREYOU request
will contain a marshalled <Map:STAF/Service/Misc/WhoAreYou>
representing information about a system.
The map is defined as follows:
Table 46. Definition of map class STAF/Service/Misc/WhoAreYou
| Description: This map class represents information about a system. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| instanceName | Instance Name | <String> |
|
| instanceUUID | Instance UUID | <String> |
|
| machine | Macine | <String> |
|
| machineNickname | Machine Nickname | <String> |
|
| isLocalRequest | Local Request | <String> | 'Yes' | 'No' |
Notes:
| |||
Syntax:
WHOAREYOU
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : No
Syntax:
WHOAREYOU
Results: If the request is issued from the command line, the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Machine : client2.austin.ibm.com Machine Nickname: client2.austin.ibm.com Local Request : Yes
LIST allows you to obtain information about the interfaces (aka connection providers) that are enabled for a system, or you can list the current operational settings for STAF, or you can show the cached endpoints used by automatic interface cycling.
LIST INTERFACES | SETTINGS | ENDPOINTCACHE
INTERFACES specifies that you want information for interfaces.
SETTINGS specifies that you want to list the current operational settings for STAF.
ENDPOINTCACHE specifies that you want to show the cached endpoints used by automatic interface cycling.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
Table 47. Definition of map class STAF/Service/Misc/Interface
| Description: This map class represents an interface. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Interface Name | <String> |
|
| library | Library | <String> |
|
| optionMap | Options | <Map> of <String> |
|
Notes:
| |||
Table 48. Definition of map class STAF/Service/Misc/Settings
| Description: This map class represents the operational settings for STAF. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| connectAttempts | Connection Attempts | <String> |
|
| connectRetryDelay | Connect Retry Delay | <String> |
|
| interfaceCycling | Interface Cycling | <String> | 'Enabled' | 'Disabled' |
| maxQueueSize | Maximum Queue Size | <String> |
|
| initialThreads | Initial Threads | <String> |
|
| threadGrowthDelta | Thread Growth Delta | <String> |
|
| dataDir | Data Directory | <String> |
|
| defaultInterface | Default Interface | <String> |
|
| defaultAuthenticator | Default Authenticator | <String> |
|
| resultCompatibilityMode | Result Compatibility Mode | <String> | 'Verbose' | 'None' |
Table 49. Definition of map class STAF/Service/Misc/EndpointCache
| Description: This map class represents an cached endpoint. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| endpoint | Endpoint | <String> |
|
| interface | Interface | <String> |
|
| createdTimestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
Notes:
| |||
Syntax:
LIST INTERFACES
Results: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Interface Name: local
Library : STAFLIPC
Options : {
IPCName: STAF
}
}
{
Interface Name: tcp
Library : STAFTCP
Options : {
ConnectTimeout: 5000
Port : 6500
Protocol : IPv4
}
}
{
Interface Name: alt-tcp
Library : STAFTCP
Options : {
ConnectTimeout: 30000
Port : 6502
Protocol : IPv6
}
}
]
Syntax:
LIST SETTINGS
Results: If the request is issued from the command line, the result, in default format, could look like:
Connection Attempts : 2 Connect Retry Delay : 1000 Interface Cycling : Enabled Maximum Queue Size : 10000 Initial Threads : 10 Thread Growth Delta : 1 Data Directory : c:\STAF\data\STAF Default Interface : tcp Default Authenticator : none Result Compatibility Mode: Verbose
Syntax:
LIST ENDPOINTCACHE
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Endpoint Interface Date-Time -------------------- --------- ----------------- machine1 tcp2 20051101-16:42:41 machine1.company.com tcp2 20051102-11:11:37 machine2.company.com tcp3 20051101-15:23:59 machine3 tcp2 20051102-09:05:34
QUERY allows you to obtain detailed information about an enabled interface (aka connection provider).
QUERY INTERFACE <Name>
INTERFACE specifies the name of the interface you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
On successful return, the result buffer for a QUERY INTERFACE
request will contain a marshalled
<Map:STAF/Service/Misc/Interface>
representing the specified interface (aka connection provider).
The map is defined as follows:
Table 50. Definition of map class STAF/Service/Misc/Interface
| Description: This map class represents an interface. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Interface Name | <String> |
|
| library | Library | <String> |
|
| optionMap | Options | <Map> of <String> |
|
Notes:
| |||
Syntax:
QUERY INTERFACE tcp
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Interface Name: tcp
Library : STAFTCP
Options : {
ConnectTimeout: 5000
Port : 6500
Protocol : IPv4
}
}
Syntax:
QUERY INTERFACE local
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Interface Name: local
Library : STAFLIPC
Options : {
IPCName: STAF
}
}
Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
[MAXQUEUESIZE <Number>] [INTERFACECYCLING <Enabled | Disabled>]
[DEFAULTINTERFACE <Name>] [DEFAULTAUTHENTICATOR <Name>]
[RESULTCOMPATIBILITYMODE <Verbose | None>]
See section 4.7, "Operational parameters" for a description of these options.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET MAXQUEUESIZE 50
Syntax: SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2000
Syntax: SET INTERFACECYCLING Disabled
Syntax: SET DEFAULTINTERFACE tcp
PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM>
ENDPOINTCACHE indicates that you want to purge one or more endpoints from the endpoint cache.
ENDPOINT specifies the endpoint that you want to purge. This option will resolve variables.
CONFIRM indicates that you really want to purge the entire contents of the endpoint cache.
This command requires trust level 5.
All return codes from PURGE are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain a marshalled
<Map:STAF/Service/Misc/PurgeStats>, representing the number
of endpoints that were purged and the number of endpoints remaining in the
endpoint cache. The map is defined as follows:
Table 51. Definition of map class STAF/Service/Misc/PurgeStats
| Description: This map class represents the purge statistics for the endpoint cache. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| numPurged | Purged Endpoints | <String> |
|
| numRemaining | Remaining Endpoints | <String> |
|
Syntax: PURGE ENDPOINTCACHE ENDPOINT client1 ENDPOINT client1.company.com
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Purged Endpoints : 2 Remaining Endpoints: 8
Syntax: PURGE ENDPOINTCACHE CONFIRM
Results: If the request is issued from the command line, the result, in tabular format, could look like:
Purged Endpoints : 8 Remaining Endpoints: 0
SERVICE <Name> LIBRARY STAFMon PARMS <Parms>
<Name> is the name by which the Monitor service will be known on this machine.
<Parms> is any parameters that are accepted at initialization time. The same parameters for the Monitor SET command can be specified during initialization time. See the Monitor SET command for details on the available parameters.
service Monitor library STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 512"
Note: Note that this variable will only be examined if the ENABLERESOLVEMESSAGEVAR option is set either during the Monitor registration (via the PARMS options) or by use of the SET ENABLERESOLVEMESSAGEVAR Monitor command.
Note: The default if STAF/Service/<Name>/ResolveMessage is not specified, is not to resolve messages. This is due to the fact that you can resolve variables yourself before logging messages and the fact that the messages could be quite large. This can be overridden on a per message basis by using the RESOLVEMESSAGE or NORESOLVEMESSAGE option.
LOG MESSAGE <Message> [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 LOG are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a LOG command.
QUERY MACHINE <Machine Nickname> HANDLE <Handle>
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 Appendix A, "API Return Codes".
The result buffer will contain a marshalled
<Map:STAF/Service/Monitor/MonitorInfo>, representing
the last monitor message generated by the specified machine/handle.
The map is defined as follows:
Table 52. Definition of map class STAF/Service/Monitor/MonitorInfo
| Description: This map class represents a monitor message. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| message | Message | <String> |
|
| Notes:
The "Date-Time" is the date/time at which the last monitor
message was logged.
| |||
Syntax: QUERY MACHINE automate.austin.ibm.com HANDLE 32
Results: If the request is submitted from the command line, the result, in default format, could look like:
Date-Time: 20040911-16:00:32 Message : Testcase aborted with error "255"
Syntax: QUERY MACHINE testmachine1 HANDLE 85
Results: If the request is submitted from the command line, the result, in default format, could look like:
Date-Time: 20041022-17:58:01 Message : TestC: Step 2 of 5
LIST MACHINES | MACHINE <Machine> | SETTINGS
MACHINES indicates you want list all the machine nicknames that have created monitor data.
MACHINE indicates you want to list the monitor data for the specified machine nickname. This option will resolve variables.
SETTINGS returns the Monitor settings.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
The result buffer will contain data based on the LIST command:
Table 53. Definition of map class STAF/Service/Monitor/HandleInfo
| Description: This map class represents the handle that generated the monitor message on the specified machine. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| size | Size | <String> |
|
| Notes: The "Date-Time" is the date/time at which the last monitor message was logged. The "Size" is the size of the last monitor message logged. | |||
Table 54. Definition of map class STAF/Service/Monitor/Settings
| Description: This map class represents the settings for the Monitor service. | |||
| Key Name | Display Name | Type | Value |
|---|---|---|---|
| maxRecordSize | Max Record Size | <String> |
|
| resolveMessage | Resolve Message | <String> | Enabled | Disabled |
| resolveMessageVar | Resolve Message Var | <String> | Enabled | Disabled |
Syntax: LIST MACHINES
Results: If the request is submitted from the command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
Syntax: LIST MACHINE automate.austin.ibm.com
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 34 20040910-16:29:03 30 36 20040910-16:29:13 148 37 20040910-16:29:19 97 68 20040911-16:00:32 43
Syntax: LIST MACHINE testmachine1
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 20 20041022-17:43:05 25
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Max Record Size : 512 Resolve Message : Enabled Resolve Message Var: Disabled
DELETE [BEFORE <Timestamp>] 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 DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a DELETE command.
SET [RESOLVEMESSAGE | NORESOLVEMESSAGE]
[MAXRECORDSIZE <Size>]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
RESOLVEMESSAGE causes the MONITOR service to call the STAF variable service to resolve any variables in Monitor Log messages before being written.
NORESOLVEMESSAGE causes the MONITOR service to not call the STAF variable service to resolve any variables in Monitor Log messages before being written. This is the default.
MAXRECORDSIZE <Size> sets the Maximum record size for Monitor data. The default is 1024 bytes.
ENABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to be queried for every Monitor Log command, to determine if variables in the Monitor Log command should be resolved.
DISABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to not be queried for every Monitor Log command. This is the default.
The highest priority in defining whether variables in a Monitor Log command are to be resolved will be the RESOLVEMESSAGE/NORESOLVEMESSAGE specified directly in the Log command. If the Monitor Log command contains neither option, then if ENABLERESOLVEMESSAGEVAR is set, the variable STAF/Service/<Name>/ResolveMessage will be examined to determine whether to resolve the message. If DISABLERESOLVEMESSAGEVAR is set, then the RESOLVEMESSAGE/NORESOLVEMESSAGE option (set via the PARMS options or by use of the SET RESOLVEMESSAGE/NORESOLVEMESSAGE Monitor command) will be honored.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successul SET command.
Syntax: SET RESOLVEMESSAGE
Syntax: SET MAXRECORDSIZE 512 ENABLERESOLVEMESSAGEVAR
No additional return codes are defined for the Monitor service. The Monitor service uses only the STAF return codes (see Appendix A, "API Return Codes" for additional information).
The PING service is an internal STAF service. PING provides a service similar to the TCP/IP PING service. This 'are you there' request can be used to determine if STAFProc is up and running and accessible.
PING [MACHINE <Machine>]
MACHINE specifies the endpoint for a machine to be pinged. This option allows you to check if the machine you are submitting the PING request to can communicate via STAF to another machine. It can be useful when trying to determine if there is a firewall issue or other network problem. This option will resolve variables.
This command requires trust level 1.
All return codes from PING are documented in Appendix A, "API Return Codes".
The result buffer will contain PONG on a successful return from a PING command.
The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.).
Syntax and Results:
C:\>STAF local PING PING Response -------- PONG
Syntax and Results:
C:\>STAF host1.company.com PING PING Response -------- PONG
If STAFProc is not running on on machine host1.company.com or you cannot communicate via STAF to that machine, you would get an RC 16 (No path to endpoint) and an error message. For example:
C:\>STAF host1.company.com PING PING Error submitting request, RC: 16 Additional info --------------- STAFConnectionProviderConnect: Timed out connecting to endpoint: select() timeou t: 22, Endpoint: tcp://host1.company.com
Note that you can get more information on return code 16 (and other STAF return codes) by using the Help service. For example:
C:\>STAF local HELP ERROR 16 Response -------- Description: No path to endpoint Details : This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. machine). This error usually indicates that STAF i s not running on the target machine, or that the requested endpoint is not valid , or that the network interface or port for the requested endpoint is not suppor ted. Alternatively, you may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg fi le.
Syntax and Results:
C:\>STAF host1.company.com PING PING MACHINE host2.company.com Response -------- PONG
Syntax and Results:
C:\>STAF host1.company.com PING PING MACHINE host2.company.com@6501 Response -------- PONG
The PROCESS service is one of the internal STAF services. It provides the following commands
START allows you to start a process. Processes may be started synchronously or asynchronously. You may also specify to which workload they belong, parameters to pass to them, their working directory, any process specific STAF variables to set for them, as well as any environment variables they may need.
START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>]
[VAR <Variable=Value>] [ENV <Variable=Value>] [USEPROCESSVARS]
[WORKLOAD <Name>] [TITLE <Title>] [WAIT [<Timeout>] | ASYNC]
[STOPUSING <Method>] [STATICHANDLENAME <Name>]
[NEWCONSOLE | SAMECONSOLE] [FOCUS <Background | Foreground | Minimized>]
[USERNAME <User name> [PASSWORD <Password>]]
[DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH]
[STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
[STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
[RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
[NOTIFY ONEND [HANDLE <Handle> | NAME <Name>] [MACHINE <Machine>]
[PRIORITY <Priority>] [KEY <Key>]]
WORKLOAD allows you to specify the name of the workload for which this process is a member. This may be useful in conjunction with other PROCESS commands. The default is no workload name. This option will resolve variables.
TITLE allows you to specify the program title of the process. Unless overridden by the process, the TITLE will be the text that is displayed on the title bar of the application. This option will resolve variables.
COMMAND specifies the actual command that you want to start. If the path to the command is not specified, the system PATH will be searched for the command. Only actual executable files, such as .EXEs, can be STARTed. Rexx files cannot be STARTed directly. On Windows systems, they need to be started through REXX.EXE. This option will resolve variables. This option will handle private data.
PARMS specifies any parameters that you wish to pass to the command. This option will resolve variables. This option will handle private data.
SHELL specifies that COMMAND should be started via a separate shell. Using a separate shell allows complex commands involving pipelines to be readily executed. 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/Vista, 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.7, "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, originating handle's pool, originator's shared pool, and originator's system pool should be searched if the request came from local, otherwise originating's handle's pool, originator's shared pool, remote shared pool and remote system pool should be searched.
STOPUSING allows you to specify the method by which this process will be STOPed, if not overridden on the STOP command. See 8.11.3, "STOP" for more information. This option will resolve variables.
NEWCONSOLE specifies that the process should get get a new console window. This option only has effect on Windows systems. This is the default for Windows systems.
SAMECONSOLE specifies that the process should share the STAFProc console. This option only has effect on Windows systems. This is the default for Unix systems.
FOCUS specifies the focus that is to be given to new windows opened when starting a process on a Windows system. The window(s) it effects depends on whether you are using the default command mode or the shell command mode. If the process is started using the default command mode (no SHELL option), then the specified focus specified is given to any new windows opened by the specified command. Otherwise, if the process is started using the shell command mode, then the specified focus is given only to the new shell command window opened, not to any windows opened by the specified command. This option only has effect on Windows systems. This option will resolve variables. This option was added in STAF V3.1.4. Recognized values are the following:
USERNAME specifies the username under which the process should be started.
Note: The PROCESSAUTHMODE operational parameter must be enabled in the STAF configuration file on the system where the process is run under a different username. See 4.7, "Operational parameters" for more information on how to enable the PROCESSAUTHMODE operational parameter. There are additional requirements that must be met to run a process under a different username on a Windows system. See "Starting a Process Under a Different User on Windows" for more information.
PASSWORD specifies the password with which to authenticate the user specified with USERNAME. This option will handle private data.
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. This option will resolve variables.
STDOUT specifies the name of the file to which standard output will be redirected. If the file already exists, it will be replaced. This option will resolve variables.
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. This option will resolve variables.
STDERR specifies the name of the file to which standard error will be redirected. If the file already exists, it will be replaced. This option will resolve variables.
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. This option will resolve variables.
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.7, "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.
This command requires trust level 5.
All return codes from START are documented in Appendix A, "API Return Codes".
The maps are defined as follows:
Table 55. Definition of map class STAF/Service/Process/CompletionInfo
| Description: This map class represents completion information for a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | Return Code | <String> |
|
| key | Key | <String> | <None> |
|
| fileList | Files | <List> of <Map:STAF/Service/Process/ReturnFileInfo> |
|
| Notes: The "Files" value will contain a list of information about the files requested to be returned, or an empty list if no files were requested to be returned. Files will be returned in the order of standard output, then standard error, then any files specified with the RETURNFILE option. | |||
Table 56. Definition of map class STAF/Service/Process/ReturnFileInfo
| Description: This map class represents a file returned by the process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | Return Code | <String> |
|
| data | Data | <String> |
|
| Notes: For each file, a standard STAF return code indicating the success or failure of retrieving the file's contents is provided. If the file's return code is 0, then the data contained in the file is also provided. | |||
For example, suppose a PROCESS START COMMAND "java TestA" WAIT request is submitted from the command line, and assume that the process completed successfully and returned 0. The result, in verbose format, could look like the following:
{
Return Code: 0
Key : <None>
Files : []
}
For example, suppose a PROCESS START COMMAND "java TestA" RETURNSTDOUT RETURNSTDERR WAIT request is submitted from the command line, and assume that the process completed successfully and returned 0, that the standard output of the process was simply "Success !!!", and that the standard error of the process was blank. The result, in verbose format, could look like the following:
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : Success !!!
}
{
Return Code: 0
Data :
}
]
}
The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.) or via a <process> element in a STAX job.
Syntax and Results:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" Response -------- 35The result buffer contains the handle number of the process that was started (which in this case is 35). This is not the return code of the process as the process was started asynchronously (no WAIT option was specified) so it doesn't wait for the process to complete.
If you invoke the same process again, you'll get a different handle number each time. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" Response -------- 37If you want the STAF command to wait for the process to complete before returning, specify the WAIT option. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT
Response
--------
{
Return Code: 0
Key : <None>
Files : []
}
The result buffer contains a map of the results from running the "java -version"
command, including the return code from the command which was 0 in this example.
A return code of 0 from a "java -version" command indicates that the
command ran successfully. Note that no files were returned, as indicated
by an empty list, [], since none of the return file options (RETURNSSTDOUT,
RETURNSTDERR, RETURNFILE) were specified.
The "java -version" command writes the Java version information to standard error (stderr). To obtain that information, plus any information written to standard output (stdout), you could use the STDERRTOSTDOUT option to redirect stderr to stdout and use the RETURNSTDOUT option to return the content of stdout. For example:
C:\>STAF local PROCESS START SHELL COMMAND "java -version" WAIT STDERRTOSTDOUT RETURNSTDOUT
Response
--------
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0-b64)
Java HotSpot(TM) Client VM (build 1.5.0-b64, mixed mode, sharing)
}
]
}
The result buffer contains a map of the results from running the "java -version"
command, including a return code of 0 and a list of the files returned by the
process, which in this case contains one file (the stdout file).
For each file returned, a standard STAF return code is provided which
indicates the success or failure of retrieving the file's contents, which
in this case was 0, indicating the file's contents were successfully retrieved.
In addition, if the file's return code is 0, then the data contained in the
file is also provided. In this case, it contains the java version information.
Note that instead of specifying local as the machine on which to start this process, you could have specified the name of a remote machine that is also running STAF and which has given trust level 5 to the requesting machine.
Syntax and Results:
C:\>STAF client1 PROCESS START COMMAND myTest.exe Response -------- 60The result buffer contains the handle number of the process that was started (which in this case is 60). This is not the return code of the process as the process was started asynchronously (without the WAIT option) so the STAF request completes as soon as the process is started and doesn't wait for the process to complete.
However, if the myTest.exe file was not found in the system path on machine client1, you would get an error starting the process. For example:
C:\>STAF client1 PROCESS START COMMAND myTest.exe Error submitting request, RC: 10 Additional info --------------- Error starting the process. CreateProcess failed with OS RC 2: The system cannot find the file specified.The return code from the STAF request is 10. STAF RC 10 indicates a base operating system error was encountered (e.g. STAF local HELP ERROR 10 gives more information about STAF RC 10) and an error message that includes the actual base operating system error code, 2, is provided in the result buffer. OS error code 2 indicates that a file was not found. In this case, the myTest.exe file was not found since it's not in the system path.
If myTest.exe is located in directory C:\tests on machine client1, you can fully qualify the path to myTest.exe so that the command can be located and successfully started. For example:
C:\>STAF client1 PROCESS START COMMAND C:/tests/myTest.exe Response -------- 62Or, if you wanted myTest.exe to run in an environment where the system path included the C:/tests directory, you can use the ENV option to update the system path environment variable. Note that if you specify the SHELL option in this situation, you don't need to specify the path to the command because the updated system path will be used to find the command. For example:
C:\>STAF client1 PROCESS START SHELL COMMAND myTest.exe ENV PATH=C:/tests{STAF/Config/Sep/Path}{STAF/Env/Path}
Response
--------
64
Syntax and Results:
C:\>STAF client1 PROCESS START COMMAND "java -cp C:/tests TestA" WAIT RETURNSTDOUT RETURNSTDERR
Response
--------
{
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : SUCCESS. Yippee!!!
}
{
Return Code: 0
Data :
}
]
}
The result buffer contains a map of the results from running the java testcase,
including a return code of 0 and a list of the files returned. The first file
returned is stdout and it contains "SUCCESS. Yippee!!!". The second file
returned is stderr and it contains nothing.
@echo off EXIT /B 99
Syntax and Results:
C:\>STAF client2 PROCESS START SHELL COMMAND "C:/test.bat & set PROCESSRC=%ERRORLEVEL% & exit %PROCESSRC%" WAIT
Response
--------
{
Return Code: 99
Key : <None>
Files : []
}
The following examples show the goal and the syntax of the request to submit to the PROCESS service but not the results.
Syntax: START COMMAND tc1.exe TITLE "Testcase 1" WORKDIR d:/testcase ENV RUNMODE=Type1
Syntax: START COMMAND tc2 WORKDIR d:/webtests VAR WebServer=testsrv1.test.austin.ibm.com WORKLOAD "Web Tests" WAIT
Syntax: START COMMAND {WWWTestDir}/www1.exe WORKDIR {WWWTestDir} WAIT 120000
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND PRIORITY 1 MACHINE EventController NAME ProcessHandler KEY 9bt1az54fq
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase STOPUSING SIGINT
Syntax: START COMMAND tc2.exe WORKDIR c:/testcase SAMECONSOLE
Syntax: START COMMAND tc2 WORKDIR /testcases USERNAME testuser PASSWORD !!@tupass@!!
Syntax: START COMMAND tc2 WORKDIR /testcase STDOUT /testcases/tc2/stdout.txt
Syntax: START COMMAND tc3.sh STATICHANDLENAME "Test case 3"
Syntax: START SHELL COMMAND "ps | grep test | wc >testcount.txt"
Syntax: START SHELL COMMAND "grep 'Count = ' /tests/out | awk '^{print $5}'" STDOUT=/tests/awk.out STDERRTOSTDOUT
Syntax: START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT
Syntax: START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT WAIT RETURNSTDOUT RETURNFILE /tmp/tc3.results
Syntax: START COMMAND tc3.sh STDERRTOSTDOUT WAIT RETURNSTDOUT
Syntax: START SHELL "D:/Cygwin/bin/bash.exe -c %C" COMMAND "D:/tests/test1.sh machA" WORKDIR D:/tests
Syntax: START SHELL "xterm -title %T -e /bin/sh -c %X" COMMAND "/tests/test1.sh machA" TITLE "Test 1" STDOUT /tests/test1.out
Syntax: START SHELL "/bin/csh -c %C" COMMAND "/tests/test1.sh machA" WORKDIR /tests
Syntax: START SHELL 'su - %u -c %C' COMMAND 'echo $HOME' USERNAME test WAIT STDOUT /temp/test.out STDERRTOSTDOUT RETURNSTDOUT
To start a process under a different user name on a Windows system, the following requirements must be met:
There are operating system limitations on how many processes can run concurrently under a different user in the same desktop. If you get RC 10 with OS RC 1816, and the user name that the process is being run under is not a member of the Administrator group, then you may want to give it the "Increase quotas" user right so that more processes can run concurrently. See "Changing User Rights Assignments" for more information on how to change user rights assignments.
If you are having problems starting a process under a different user name, use the Trace service to enable error and warning trace points to see if you get more information.
This information is provided to help you change user rights assignments as needed to start a process under a different user name.
On Windows Vista systems, to view or modify user rights assignments in the local security policy, perform the following:
On Windows XP systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:
STOP allows you to stop a process that was started via 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. This option will resolve variables.
USING specifies the method used to stop the process. This option will resolve variables. The following methods are supported:
This command requires trust level 4.
All return codes from STOP are documented in Appendix A, "API Return Codes".
Table 57. Definition of map class STAF/Service/Process/StopInfo
| Description: This map class represents statistics for stopped processes. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| stoppedProcesses | Stopped Processes | <String> |
|
| totalProcesses | Total Processes | <String> |
|
| Notes: This map contains the number of processes actually stopped and the total number of processes. These two numbers will be different if some of the processes have already been stopped or have already completed execution on their own. | |||
Syntax: STOP HANDLE 42
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 1 Total Processes: 3
Syntax: STOP WORKLOAD "Web Tests"
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 5 Total Processes: 18
Syntax: STOP ALL CONFIRM
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 16 Total Processes: 16
Syntax: STOP HANDLE 113 USING SIGTERM
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 1 Total Processes: 10
Syntax: STOP HANDLE 17 USING SIGKILL
Results: If the request is submitted from the command line, the result, in default format, could look like:
Stopped Processes: 1 Total Processes: 5
LIST allows you to obtain information about all of the processes started via STAF, or only those processes started via STAF that are currently running, or only those processes started via STAF that have completed. You may get information about any process started in WAIT mode that is still running and/or about any process started in ASYNC mode that has not yet been freed.
You can also list the operational settings for the Process service.
LIST [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG]or
LIST SETTINGS
HANDLES specifies that you want information for process handles.
RUNNING specifies that you only want information for processes that are currently running.
COMPLETED specifies that you only want information for processes started in ASYNC mode that have completed, but have not yet been freed.
WORKLOAD specifies that you want information for processes that are part of a given workload. This option will resolve variables.
LONG specifies that you want to list more detailed information for the processes.
SETTINGS specifies that you want to list the current operational settings for the Process service.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return:
Table 58. Definition of map class STAF/Service/Process/ProcessListInfo
| Description: This map class represents a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| command | Command | <String> | Private data will be masked. |
| startTimestamp | Start Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| endTimestamp | End Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| rc | Return Code
(RC) | <String> | <None> |
|
| Notes: The value for "End Date-Time" and "Return Code" will be <None> if the process is still running. | |||
Table 59. Definition of map class STAF/Service/Process/ProcessListLong
| Description: This map class represents detailed information for a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle
(H#) | <String> |
|
| workload | Workload | <String> | <None> |
|
| command | Command | <String> | Private data will be masked. |
| pid | PID | <String> |
|
| startTimestamp | Start Date-Time
(Start D-T) | <String> | <YYYYMMDD-HH:MM:SS> |
| endTimestamp | End Date-Time
(End D-T) | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| rc | Return Code
(RC) | <String> | <None> |
|
Notes:
| |||
Table 60. Definition of map class STAF/Service/Process/Settings
| Description: This map class represents the operational settings for the Process service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| defaultStopUsing | Default Stop Using Method | <String> |
|
| defaultConsoleMode | Default Console Mode | <String> | 'New' | 'Same' |
| defaultFocus | Default Focus | <String> | 'Background' | 'Foreground' | 'Minimized' |
| processAuthMode | Process Auth Mode | <String> |
|
| defaultAuthUsername | Default Auth Username | <String> | <None> |
|
| defaultAuthPassword | Default Auth Password | <String> | <None> | Private data will be masked. |
| defaultAuthDisabledAction | Default Auth Disabled Action | <String> | 'Ignore' | 'Error' |
| defaultShell | Default Shell | <String> | <None> |
|
| defaultNewConsoleShell | Default New Console Shell | <String> | <None> |
|
| defaultSameConsoleShell | Default Same Console Shell | <String> | <None> |
|
Notes:
| |||
Syntax: LIST (or LIST HANDLES)
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- ------ 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None> 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
Syntax: LIST COMPLETED HANDLES
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- -- 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
Syntax: LIST RUNNING HANDLES
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
Syntax: LIST LONG
Results: If the request is submitted from the command line, the result, in table format, could look like:
H# Workload Command PID Start Date-Time End Date-Time RC
-- -------- ---------------- ---- ----------------- ----------------- ---------
17 <None> notepad.exe 1444 20051205-11:33:14 20040912-11:37:55 0
25 <None> java TestProcess 2836 20051205-11:53:18 20040912-11:53:18 1
5 5 0
29 My Test java TestA 3376 20051205-12:01:05 20040912-12:05:23 0
43 My Test java TestB 2776 20051205-12:32:38 <None> <None>
47 My Test C:/tests/MyTest. 2448 20051205-12:32:56 <None> <None>
exe
56 TC1 C:/tests/tc1.exe 2840 20040912-12:33:24 20040912-12:35:32 3
Syntax: LIST WORKLOAD "My Test"
Results: If the request is submitted from the command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result, in default format, could look like:
Default Stop Using Method : SigKill Default Console Mode : New Default Focus : Background Process Auth Mode : Disabled Default Auth Username : <None> Default Auth Password : <None> Default Auth Disabled Action: Ignore Default Shell : <None> Default New Console Shell : <None> Default Same Console Shell : <None>
QUERY allows you to obtain detailed information about a process with a specified handle that was started via STAF.
QUERY HANDLE <Handle>
HANDLE specifies the handle number of the process you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
The result buffer will contain a marshalled
Map:STAF/Service/Process/ProcessInfo>, representing
information about the process specified to be queried.
The map is defined as follows:
Table 61. Definition of map class STAF/Service/Process/ProcessInfo
| Description: This map class represents a process. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| handle | Handle | <String> |
|
| handleName | Handle Name | <String> | <None> |
|
| title | Title | <String> | <None> |
|
| workload | Workload | <String> | <None> |
|
| shell | Shell | <String> | <None> | <Default Shell> if no value is specified |
| command | Command | <String> | Private data will be masked. |
| parms | Parms | <String> | <None> | Private data will be masked. |
| workdir | Workdir | <String> | <None> |
|
| focus | Focus | <String> | 'Background' | 'Foreground' | 'Minimized' |
| userName | User Name | <String> | <None> |
|
| key | Key | <String> | <None> |
|
| pid | PID | <String> |
|
| startMode | Start Mode | <String> | 'Async' | 'Wait' |
| startTimestamp | Start Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| endTimestamp | End Date-Time | <String> | <None> | <YYYYMMDD-HH:MM:SS> |
| rc | Return Code | <String> | <None> |
|
Notes:
| |||
Syntax: QUERY HANDLE 17
Results: If the request is issued from the command line, the result, in default format, could look like:
Handle : 17 Handle Name : <None> Title : Notepad Workload : MyWorkload Shell : <None> Command : notepad.exe Parms : <None> Workdir : <None> Focus : Background User Name : <None> Key : <None> PID : 3280 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : <None> Return Code : <None>
Syntax: QUERY HANDLE 42
Results: If the request was issued from the command line, the result in default format, could look like:
Handle : 42 Handle Name : Web Tests Title : TestA Workload : <None> Shell : <None> Command : D:/Tests/TestA.exe Parms : <None> Workdir : D:/Tests Focus : Background User Name : <None> Key : <None> PID : 3285 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : 20051205-11:37:55 Return Code : 0
When processes are STARTed asynchronously, the termination timestamp and return code are stored by STAF for later retrieval. In order to free these values, you use the PROCESS FREE command. You may only free information for processes that are already stopped. You may free the termination information for a single process, all the stopped processes of a given workload, or all stopped processes that have been started by STAF.
FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>>
ALL specifies that you want to free the termination information for all stopped processes.
WORKLOAD specifies that you want to free the termination information for all processes that are part of a given workload. This option will resolve variables.
HANDLE specifies that only the termination information for the specified handle should be freed. This option will resolve variables.
This command requires trust level 4.
All return codes from FREE are documented in Appendix A, "API Return Codes".
Table 62. Definition of map class STAF/Service/Process/FreeInfo
| Description: This map class represents statistics for freed processes. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| freedProcesses | Freed Processes | <String> |
|
| totalProcesses | Total Processes | <String> |
|
| Notes: This map contains the number of processes for which termination information was actually freed and the total number of processes. These two numbers will be different if some of the processes have not yet been stopped or have not completed execution. | |||
Syntax: FREE HANDLE 42
Results: If the request is issued from the command line, the result, in default format, could look like:
Freed Processes: 1 Total Processes: 10
Syntax: FREE WORKLOAD "Web Tests"
Results: If the request is issued from the command line, the result, in default format, could look like:
Freed Processes: 2 Total Processes: 17
Syntax: FREE ALL
Results: If the request is issued from the command line, the result, in table format, could look like:
Freed Processes: 15 Total Processes: 16
NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when a given process ends.
NOTIFY <REGISTER | UNREGISTER> ONENDOFHANDLE <Handle> [MACHINE <Machine>]
[PRIORITY <Priority>] [HANDLE <Handle> | NAME <Name>]
REGISTER indicates you want to register for a notification when a process ends. The queued message will have type "STAF/Process/End" and its message will contain a marshalled <Map> which represents the completion information for the process. See tables Table 63 and Table 64 for the map definitions of a process completion message.
UNREGISTER indicates you want to unregister a process end notification.
ONENDOFHANDLE indicates the handle of the process for which you wish to receive the notification. This option will resolve variables.
MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.
PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.
HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.
NAME specifies the registered name of the process(es) to which
the notification should be sent. This option will resolve variables.
Table 63. Definition of map for "STAF/Process/End" type message
| Description: This map represents process completion information. | ||
| Key Name | Type | Format / Value |
|---|---|---|
| handle | <String> |
|
| endTimestamp | <String> | <YYYYMMDD-HH:MM:SS> |
| rc | <String> |
|
| key | <String> |
|
| fileList | <List> of <Map>. See Table 64 for the map definition. |
|
| Notes: The value for "fileList" will contain a list of information about the files requested to be returned. Files will be returned in the order of standard output, then standard error, then any files specified with the RETURNFILE option. The value for "fileList" will be empty if none of the options RETURNSTDOUT, RETURNSTDERR, or RETURNFILE were specified when the process was started. | ||
Table 64. Definition of map for returned files for a process
| Description: This map class represents a file returned by the process. | ||
| Key Name | Type | Format / Value |
|---|---|---|
| rc | <String> |
|
| data | <String> |
|
| Notes: For each file, a standard STAF return code indicating the success or failure of retrieving the file's contents is provided. If the file's return code is 0, then the data contained in the file is also provided. | ||
For example, suppose a PROCESS START COMMAND "java TestA" request was submitted by handle 43, and assume that the process completed successfully at 20041019-17:03:48 and returned a process return code of 0. The queued STAF/PROCESS/END message will be a map that could look like the following:
{
handle : 43
endTimestamp: 20041019-17:03:48
rc : 0
key : <None>
fileList : []
}
For example, suppose a PROCESS START COMMAND "java TestA" KEY 10 RETURNSTDOUT RETURNSTDERR request is submitted by handle 26 with key 10, and assume that the process completed successfully at 20041029-09:30:16 and returned a process return code of 3 and that the standard output of the process was simply "Success !!!", and that the standard error of the process was blank. The queued STAF/PROCESS/END message will be a map that could look like the following:
{
handle : 26
endTimestamp: 20041029-09:30:16
rc : 3
key : 10
fileList : [
{
rc : 0
data: Success !!!
}
{
rc : 0
data:
}
]
}
These commands require trust level 3.
All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.
Syntax: NOTIFY REGISTER ONENDOFHANDLE 14 PRIORITY 1
Syntax: NOTIFY REGISTER ONENDOFHANDLE 43 MACHINE EventController NAME ProcessHandler
Syntax: NOTIFY UNREGISTER ONENDOFHANDLE 12 HANDLE 43
NOTIFY LIST allows you to view the process end notification list for a given process.
NOTIFY LIST ONENDOFHANDLE <Handle>
ONENDOFHANDLE indicates the handle of the process for which you wish to view the notification list. This option will resolve variables.
This command requires trust level 2.
All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".
The result buffer will contain a marshalled
<List> of <Map:STAF/Service/Process/Notifiee>,
representing the registered notifiees.
The map is defined as follows:
Table 65. Definition of map class STAF/Service/Process/Notifiee
| Description: This map class represents a registered notifiee. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| priority | Priority
(P) | <String> |
|
| machine | Machine | <String> |
|
| notifyBy | Notify By | <String> | 'Name' | 'Handle' |
| notifiee | Notifiee | <String> |
|
| Notes: If the "Notify By" value is 'Name', the "Notifiee" value will be the handle name. Otherwise, if the "Notify By" value is 'Handle', the "Notifiee" value will be the handle number. | |||
Syntax: NOTIFY LIST ONENDOFHANDLE 57
Results: If the request is issued from the command line, the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- -------------------- --------- --------- 5 automate.austin.ibm.com Handle 48 1 dyno.austin.ibm.com Handle 51 3 automate.austin.ibm.com Name Web Tests
Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.
SET [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>]
[DEFAULTFOCUS <Background | Foreground | Minimized>]
[PROCESSAUTHMODE <Auth Mode>]
[DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>]
[DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>]
[DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
See section 4.7, "Operational parameters" for a description of these options. All of these options will resolve variables.
Note that the DEFAULTAUTPASSWORD option will handle private data.
Note that setting DEFAULTCONSOLE New is equivalent to setting the DEFAULTNEWCONSOLE operational parameter in the STAF configuration file. Similarly, setting DEFAULTCONSOLE Same is equivalent to setting the DEFAULTSAMECONSOLE operational parameter in the STAF configuration file.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a successful SET command.
Syntax: SET DEFAULTSTOPUSING WM_Close
Syntax: SET PROCESSAUTHMODE Windows DEFAULTAUTHUSERNAME user1 DEFAULTAUTHPASSWORD !!@secret@!!
The QUEUE service is one of the internal STAF services. It provides the following commands
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>] [TYPE <Type>]
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.
TYPE specifies the type for the message to be queued. The default is no type. 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.
Syntax: QUEUE PRIORITY 3 MESSAGE "Hello World"
Syntax: QUEUE NAME EventController PRIORITY 1 MESSAGE CONTROL/STAGE2
Syntax: QUEUE HANDLE 17 MESSAGE Ok
Syntax: QUEUE NAME MyProduct/Test TYPE Build/Complete MESSAGE "Build=V1.2.0" TYPE
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 <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[CONTAINS <String>]... [ICONTAINS <String>]... [WAIT [Timeout] ]
PEEK [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[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's endpoint. The default is any machine. You may specify this option multiple times. This option will resolve variables. The format for a machine's endpoint is:
<Interface>://<System Identifier>[@<Port>]where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".
NAME specifies that you want to retrieve/remove 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.
USER specifies that you want to retrieve/remove a message originating from a process with a handle that has been authenticated with the specified user. The format for <User> is:
<Authenticator>://<User Identifier>where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the User Identifier. The default is any user. You may specify this option multiple times. This option will resolve variables.
TYPE specifies that you want to retrieve/remove a message with the given type. The match is case insensitive. You may specify this option multiple times. This option will resolve variables.
CONTAINS specifies that you want to retrieve/remove 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".
Table 66. Definition of map class STAF/Service/Queue/Entry
| Description: This map class represents am entry from the queue. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| priority | Priority
(P) | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| machine | Machine | <String> |
|
| handleName | Handle Name
(Name) | <String> | <None> |
|
| handle | Handle
(H#) | <String> |
|
| type | Type | <String> | <None> |
|
| message | Message | <Any> |
|
For example, if a GET or PEEK request is submitted from the command line, the result, in default format, could look like the following:
Priority : 3 Date-Time : 20040912-16:49:11 Machine : tcp://client2.austin.ibm.com@6500 Handle Name: STAF_Process Handle : 17 User : none://anonymous Type : STAF/Start Message :
Syntax: GET WAIT
Syntax: PEEK WAIT MACHINE "tcp://server1.company.com@6500"
Syntax: GET WAIT 30000 TYPE STAF/Start
Syntax: PEEK PRIORITY 3 MACHINE "*://client3.company.com*" NAME JavaTest1 CONTAINS {TestString}
Syntax: GET WAIT TYPE STAF/Start TYPE STAF/Shutdown MACHINE tcp://client1.company.com@6500 MACHINE tcp://client2.company.com@6500
Syntax: GET WAIT CONTAINS CONTROL CONTAINS "Hi there"
Syntax: GET WAIT 60000 TYPE "MyProduct/Build/Complete" CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"
DELETE allows you to delete a set of messages from the queue.
DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[CONTAINS <String>]... [ICONTAINS <String>]...
PRIORITY specifies that you want to delete messages with the given priority. The default is any priority. You may specify this option multiple times. This option will resolve variables.
MACHINE specifies that you want to delete messages originating from the given machine's endpoint. The default is any machine. You may specify this option multiple times. This option will resolve variables. The format for a machine's endpoint is:
<Interface>://<System Identifier>[@<Port>]where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".
NAME specifies that you want to delete messages originating from a process with the given registered name. The default is any name. You may specify this option multiple times. This option will resolve variables.
HANDLE specifies that you want to delete messages originating from a process with the given handle. The default is any handle. You may specify this option multiple times. This option will resolve variables.
USER specifies that you want to delete messages originating from a process with a handle that has been authenticated with the specified user. The format for <User> is:
<Authenticator>://<User Identifier>where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the <User Identifier> value. The default is any user. You may specify this option multiple times. This option will resolve variables.
TYPE specifies that you want to delete messages with the given type. The match is case insensitive. You may specify this option multiple times. This option will resolve variables.
CONTAINS specifies that you want to delete messages containing the given string. The search is case sensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.
ICONTAINS specifies that you want to delete messages containing the given string. The search is case insensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.
This command is only valid with respect to the submitting process' queue and if submitted to the local machine.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain the number of messages deleted.
Syntax: DELETE MACHINE "local://local"
Syntax: DELETE PRIORITY 3 NAME JavaTest1
Syntax: DELETE PRIORITY 3 PRIORITY 4 MACHINE {Mach1} MACHINE {Mach2} CONTAINS Stage2 CONTAINS {StringTest1}
Syntax: DELETE TYPE "MyProduct/Build/Complete" CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"
Syntax: DELETE
LIST allows you to retrieve the contents of the queue of a given 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 marshalled
<List> of <Map:STAF/Service/Queue/Entry>, representing
the queued messages, sorted in ascending order by priority.
The map is defined as follows:
Table 67. Definition of map class STAF/Service/Queue/Entry
| Description: This map class represents a queued message. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| priority | Priority | <String> |
|
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| machine | Machine | <String> |
|
| handleName | Handle Name | <String> | <None> |
|
| handle | Handle | <String> |
|
| type | Type | <String> | <None> |
|
| message | Message | <Any> | Private data will be masked. |
Syntax: LIST
Result: If the request is submitted from the command line, the result, in table format, could look like the following:
P Date-Time Machine Name H# User Type Message
- --------- -------------- ------ -- -------- ---------- ------------------------
1 20040912- tcp://client1. STAF_P 1 none://a STAF/Start
13:56:10 austin.ibm.com rocess nonymous
@6500
3 20040912- tcp://client3. JavaTe 36 none://a FVTTest CONTROL/STAGE2
14:01:52 austin.ibm.com st1 nonymous
3 20040912- tcp://client2. STAF_P 1 none://a STAF/Start
14:02:17 austin.ibm.com rocess nonymous
@6500
5 20040912- tcp://client3. JavaTe 36 none://a <None> This is a test message f
13:57:36 austin.ibm.com st1 nonymous rom Test1. Phase 2 has
@6500 completed.
Syntax: LIST HANDLE 37
Result: If the request is issued from the command line, the result, in verbose format, could look like:
[
{
Priority : 5
Date-Time : 20050222-16:50:12
Machine : tcp://client1.austin.ibm.com@6500
Handle Name: STAF_Process
Handle : 1
User : none://anonymous
Type : STAF/Process/End
Message : {
endTimestamp: 20050222-16:50:12
fileList : []
handle : 30
key :
rc : 0
}
}
]
SERVICE <Name> LIBRARY STAFPool [PARMS <Parameters>]
<Name> is the name by which the Resource Pool service will be known on this machine.
<Parameters> are valid Resource Pool parameters described below.
service respool library STAFPool
service respool library STAFPool parms "Directory {STAF/Config/BootDrive}/STAF/ResPool"
The Resource Pool service accepts a parameter string in the following format:
[DIRECTORY <Resource Pool Directory Root>]
DIRECTORY specifies the root directory under which resource pool files are stored. The default is {STAF/DataDir}/service/<Service Name (lower-case)>.
Note: Previously, in STAF 2.x, the default root directory was {STAF/Config/STAFRoot}/data/<Service Name (lower-case)>. So, if you want to continue to use the STAF 2.x resource pools with the current version of STAF, move the resource pool files to the new default root directory or specify the old root directory for the DIRECTORY parameter.
LIST displays a list of resource pools and their descriptions.
LIST [POOLS | SETTINGS]
POOLS indicates to list the resource pools. This is the default.
SETTINGS indicates to list the operational settings for the Resource Pool service.
This command requires trust level 2.
In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".
Table 68. Definition of map class STAF/Service/ResPool/Pool
| Description: This map class represents a resource pool. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| poolName | Pool Name | <String> |
|
| description | Description | <String> |
|
Table 69. Definition of map class STAF/Service/ResPool/Service
| Description: This map class represents the settings for the service. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| directory | Directory | <String> |
|
Syntax: LIST or LIST POOLS
Results: If the request is submitted from the command line, the result, in table format, could look like:
Pool Name Description ------------------- ------------------------------------------ AUSVMR UserIDs and Passwords for VM System AUSVMR AutoTester_Licenses License numbers for AutoTester
Syntax: LIST SETTINGS
Results: If the request is submitted from the command line, the result could look like:
Directory: C:\STAF\data\STAF\service\respool
Creates a resource pool.
CREATE POOL <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.
Syntax: 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.
Syntax: DELETE POOL AUSVMR CONFIRM
Syntax: DELETE POOL AUSVM1 CONFIRM FORCE
ADD allows you to add a resource entry to an existing resource pool. You may add multiple entries to a resource pool with a single request. Note, a resource pool may not contain duplicate entries. If one or more duplicate entries are specified with a single request, none of the entries specified are added.
ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
POOL specifies the name of the resource pool to which you want to add a resource entry.
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.
Syntax: ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2"
Syntax: ADD POOL AutoTester_Licenses ENTRY 1047923
REMOVE removes a resource entry from an existing resource pool. The resource entry may only be removed if the resource is not in use or if the FORCE option is specified. Note, you may remove multiple entries from a resource pool with a single request. If one or more invalid entries are specified with a single request, none of the entries specified are removed.
REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
POOL specifies the name of the resource pool from which you want to remove an entry.
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.
Syntax: REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM
Syntax: REMOVE POOL AutoTester_Licenses ENTRY 1137849 ENTRY 107523 CONFIRM FORCE
Allows you to get information on a resource pool, including a list of entries in the pool and the status of each entry, as well as a list of the pending requests for entries in the resource pool.
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 a QUERY request will contain a marshalled <Map:STAF/Service/ResPool/PoolInfo>, representing information about the specified resource pool.
The maps used in representing a resource pool are defined as follows:
Table 70. Definition of map class STAF/Service/ResPool/PoolInfo
| Description: This map class represents a resource pool. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| description | Description | <String> |
|
| requestList | Pending Requests | <List> of <Map:STAF/Service/ResPool/Request> |
|
| resourceList | Resources | <List> of <Map:STAF/Service/ResPool/Resource> |
|
| Notes: For each pending request in the request list for the pool, information about the originator of the pending request is provided. For each entry in the resource list for the pool, the resource entry and owner information is provided. | |||
Table 71. Definition of map class STAF/Service/ResPool/Request
| Description: This map class represents a pending request for a resource in a resource pool | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | Handle Name | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestedTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
Table 72. Definition of map class STAF/Service/ResPool/Resource
| Description: This map class represents a resource in the pool | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| entry | Entry | <String> |
|
| owner | Owner | <None> |
<Map:STAF/Service/ResPool/ResourceOwner> |
|
| Notes: If the resource entry is not owned, the owner will be <None>. | |||
Table 73. Definition of map class STAF/Service/ResPool/ResourceOwner
| Description: This map class represents a owner of a resource | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | Handle Name | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestedTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
| acquiredTimestamp | Date-Time Acquired | <String> | <YYYYMMDD-HH:MM:SS> |
Syntax: QUERY POOL AUSVMR
Results: If the request is submitted from the command line, the result, in verbose format, could look like the following if the resource pool contained three entries (where each entry consisted of a user id and a password) and two of the entries were currently owned.
{
Description : UserIDs and Passwords for VM System AUSVMR
Pending Requests: []
Resources : [
{
Entry: USER1 PASSWORD1
Owner: {
Machine : client3.austin.ibm.com
Handle Name : CM2_Test
Handle : 19
User : none://anonymous
Endpoint : tcp://client3.austin.ibm.com@6500
Date-Time Requested: 20041030-15:58:30
Date-Time Acquired : 20041030-15:58:30
}
}
{
Entry: USER2 PASSWORD2
Owner: {
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Date-Time Requested: 20041030-15:58:19
Date-Time Acquired : 20041030-15:58:19
}
}
{
Entry: USER3 PASSWORD3
Owner: <None>
}
]
}
Syntax: QUERY POOL AUSVMR
Results: If the request is submitted from the command line, the result, in verbose format, could look like the following if the resource pool contained three entries (where each entry consisted of a user id and a password) and all of the entries were currently owned, with two pending requests.
{
Description : UserIDs and Passwords for VM System AUSVMR
Pending Requests: [
{
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Date-Time Requested: 20041030-16:54:55
}
{
Machine : client2.austin.ibm.com
Handle Name : User Access Test
Handle : 28
User : none://anonymous
Endpoint : tcp://client2.austin.ibm.com@6500
Date-Time Requested: 20041030-16:54:58
}
]
Resources : [
{
Entry: USER1 PASSWORD1
Owner: {
Machine : client3.austin.ibm.com
Handle Name : CM2_Test
Handle : 19
User : none://anonymous
Endpoint : tcp://lucas.austin.ibm.com@6500
Date-Time Requested: 20041030-15:58:30
Date-Time Acquired : 20041030-15:58:30
}
}
{
Entry: USER2 PASSWORD2
Owner: {
Machine : client1.austin.ibm.com
Handle Name : My Test
Handle : 23
User : none://anonymous
Endpoint : tcp://client1.austin.ibm.com@6500
Date-Time Requested: 20041030-15:58:19
Date-Time Acquired : 20041030-15:58:19
}
}
{
Entry: USER3 PASSWORD3
Owner: <None>
}
]
}
Obtains exclusive access to an entry from the resource pool.
The STAF handle on the machine that submitted the REQUEST POOL request to the RESPOOL service will be the "owner" of the resource pool entry. Note that when a STAF handle is deleted, STAF performs garbage collection for the handle. In regards to the RESPOOL service, this means that the RESPOOL service will be notified when a handle is deleted and it will release any resource pool entries the handle owns and will remove any pending requests for resource pools submitted by the handle.
If you submit a REQUEST POOL request to the RESPOOL service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:
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.
Syntax: REQUEST POOL AUSVMR FIRST
Syntax: REQUEST POOL AutoTester_Licenses TIMEOUT 300000
Say you had a resource pool named MachinePool that contained two entries and you submit a REQUEST POOL request to the RESPOOL service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't use a static handle, the resource entry obtained by the REQUEST POOL request would show up as available (Unowned) when submitting a QUERY POOL request to the RESPOOL service because the STAF commmand deleted the handle it created to submit the REQUEST POOL request and it was garbage collected.
C:\>STAF local RESPOOL REQUEST POOL MachinePool
Response
--------
machine1
C:\>STAF local RESPOOL QUERY POOL MachinePool
Response
--------
{
Description : Test Machine Pool
Pending Requests: []
Resources : [
{
Entry: machine1
Owner: <None>
}
{
Entry: machine2
Owner: <None>
}
]
}
Instead, you need to first create a static handle and set environment variable STAF_STATIC_HANDLE to the static handle's number before submitting a REQUEST POOL request to the RESPOOL service using the STAF command so that the static handle can retain ownnership of the resource entry until it releases the entry (or until you delete the static handle). See "Using the STAF command from shell-scripts" for more information on special environment variable STAF_STATIC_HANDLE. Here's an example shown using the STAF command from a Windows command prompt:
C:\>STAF local HANDLE CREATE HANDLE NAME ResourcePoolHandle
Response
--------
51
C:\>set STAF_STATIC_HANDLE=51
C:\>STAF local RESPOOL REQUEST POOL MachinePool
Response
--------
machine1
C:\>STAF local RESPOOL QUERY POOL MachinePool
Response
--------
{
Description : Test Machine Pool
Pending Requests: []
Resources : [
{
Entry: machine1
Owner: {
Machine : client1.company.com
Handle Name : ResourcePoolHandle
Handle : 51
User : none://anonymous
Endpoint : local://local
Date-Time Requested: 20060302-14:11:18
Date-Time Acquired : 20060302-14:11:18
}
}
{
Entry: machine2
Owner: <None>
}
]
}
RELEASE allows you to release exclusive access of a resource entry in a resource pool.
RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
POOL specifies the name of the resource pool to which you are releasing exclusive access of an entry.
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 owner of the resource entry (e.g. the handle on the machine that submitted the REQUEST POOL request) may RELEASE the entry.
Command RELEASE requires trust level 3.
Command RELEASE FORCE requires trust level 4.
In addition to the return codes documented in Appendix A, "API Return Codes", RELEASE also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".
The result buffer will contain no data upon return from the RELEASE command.
Syntax: RELEASE POOL AUSVMR ENTRY "User2 Password2"
Sytnax: 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:
Table 74. Resource Pool Service Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 4005 | Not entry owner | You are not the owner of the entry you are trying to RELEASE. Use the FORCE option if you are sure that the correct entry is specified. |
| 4006 | Pool has pending requests | The resource pool you are trying to DELETE has pending requests. If necessary, use the FORCE option. |
| 4007 | No entries available | The resource pool has no entries. |
| 4008 | Create pool path error | The directory specified by the DIRECTORY parameter when registering the service or the default directory could not be created. |
| 4009 | Invalid pool file format | An error occurred reading the resource pool file due to an error in the file format. If you are using the latest version of the Resource Pool service, contact the STAF authors. |
| 4010 | Entry is owned | A resource pool entry you specified to REMOVE is owned. Use the FORCE option if you are sure that the correct entry is specified. |
The SEM service is one of the internal STAF services that allows you to manipulate and manage two kinds of semaphores:
The SEM service provides the following commands:
REQUEST allows you to request exclusive access of a semaphore. Your request is blocked until all prior pending REQUESTs have been RELEASEd. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait to gain access to the semaphore. If no timeout is specified, the request will block indefinitely. The semaphore is created if it does not exist.
The STAF handle on the machine that submitted the REQUEST MUTEX request to the SEM service will be the "owner" of the mutex semaphore. Note that when a STAF handle is deleted, STAF performs garbage collection for the handle. In regards to the SEM service, this means that the SEM service will be notified when a handle is deleted and it will release any mutex semaphores the handle owns and will remove any pending requests for mutex semaphores submitted by the handle.
If you submit a REQUEST MUTEX request to the SEM service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:
REQUEST MUTEX <Name> [TIMEOUT <Timeout>]
MUTEX specifies the name of the mutex semaphore which you want to request. The semaphore is created if it does not exist. This option will resolve variables.
TIMEOUT specifies a timeout, 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. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a REQUEST command.
Syntax: REQUEST MUTEX Printers/Printer1
Syntax: REQUEST MUTEX DataSource1 TIMEOUT 30000
Say you submitted a REQUEST MUTEX request to the SEM service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't use a static handle, the mutex semaphore would show up as available (Unowned) when submitting a QUERY MUTEX request to the SEM service because the STAF commmand deleted the handle it created to submit the REQUEST MUTEX request when that request completed and the handle was garbage collected.
C:\>STAF local SEM REQUEST MUTEX Mutex1
Response
--------
C:\>STAF local SEM QUERY MUTEX Mutex1
Response
--------
{
State : Unowned
Owner : <None>
Pending Requests: []
}
Instead, you need to first create a static handle and set environment variable STAF_STATIC_HANDLE to the static handle's number before submitting a REQUEST MUTEX request to the SEM service using the STAF command so that the static handle can retain ownnership of the mutex semaphore until it releases the mutex semaphore (or until you delete the static handle). See "Using the STAF command from shell-scripts" for more information on special environment variable STAF_STATIC_HANDLE. Here's an example shown using the STAF command from a Windows command prompt:
C:\>STAF local HANDLE CREATE HANDLE NAME MyHandle
Response
--------
82
C:\>set STAF_STATIC_HANDLE=82
C:\>STAF local SEM REQUEST MUTEX Mutex1
Response
--------
C:\>STAF local SEM QUERY MUTEX Mutex1
Response
--------
{
State : Owned
Owner : {
Machine : client1.company.com
Handle Name : MyHandle
Handle : 82
User : none://anonymous
Endpoint : local://local
Date-Time Requested: 20060302-15:32:34
Date-Time Acquired : 20060302-15:32:34
}
Pending Requests: []
}
RELEASE allows you to release exclusive access to a semaphore. Normally, only the owning handle may release the semaphore. Specifying FORCE allows you to force the release of the semaphore.
Note: Any thread in the owning handle's process may RELEASE the semaphore. This is in contrast to other semaphore systems, where only the REQUESTing thread may release the semaphore.
RELEASE MUTEX <Name> [FORCE]
MUTEX specifies the name of the mutex semaphore which you want to release. This option will resolve variables.
FORCE allows you to force the release of the semaphore even if you are not the owner.
This command requires trust level 3.
Note: If the FORCE option is specified, trust level 4 is required.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RELEASE command.
Syntax: RELEASE MUTEX Printers/Printer1
Syntax: RELEASE MUTEX TestABC FORCE
POST allows you to post an event semaphore to signal that an event has happened. It is valid to post an event semaphore that is already posted.
POST EVENT <Name>
EVENT specifies the name of the event semaphore which you want to post. The semaphore is created if it does not exist. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a POST command.
Syntax: POST EVENT Server1/LAN_Started
RESET allows you to reset an event semaphore in preparation for the next event. It is valid to reset an event semaphore that is already reset.
RESET EVENT <Name>
EVENT specifies the name of the event semaphore which you want to post. The semaphore is created if it does not exist. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a RESET command.
Syntax: RESET EVENT Coffee/Ready
PULSE allows you to post and then reset an event semaphore as a single atomic action. It is valid to pulse a semaphore regardless of whether it is currently posted or reset. The semaphore will be in the reset state after the pulse.
PULSE EVENT <Name>
EVENT specifies the name of the event semaphore which you want to pulse. The semaphore is created if it does not exist. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a PULSE command.
Syntax: PULSE EVENT Race/StartLap
WAIT allows you to wait for an event semaphore. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait for an event semaphore. If no timeout is specified, the request will block indefinitely.
WAIT EVENT <Name> [TIMEOUT <Timeout>]
EVENT specifies the name of the event semaphore which you want to pulse. The semaphore is created if it does not exist. This option will resolve variables.
TIMEOUT specifies a timeout, in milliseconds, indicating the longest you are willing to wait for the semaphore. If no timeout is specified, the request will block indefinitely. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a WAIT command.
Syntax: WAIT EVENT Server1/LAN_Started
Syntax: WAIT EVENT Coffee/Ready TIMEOUT 20000
DELETE allows you to delete a mutex or event semaphore.
DELETE MUTEX <Name> | EVENT <Name>
MUTEX specifies the name of the mutex semaphore which you want to delete. A mutex semaphore may only be deleted if there are no pending REQUESTs. This option will resolve variables.
EVENT specifies the name of the event semaphore which you want to delete. An event semaphore may only be deleted if there are no processes WAITing for it. This option will resolve variables.
This command requires trust level 4.
All return codes are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on a successful return from a DELETE command.
Syntax: DELETE MUTEX Printers/Printer1
Syntax: DELETE EVENT Shutdown_The_Lab
QUERY allows you to get information on a mutex or event semaphore, such as the current owner and pending REQUESTSs. if it is a mutex semaphore or whether the semaphore is posted or reset if it is an event semaphore.
QUERY MUTEX <Name> | EVENT <Name>
MUTEX specifies the name of the mutex semaphore which you want to query. This option will resolve variables.
EVENT specifies the name of the event semaphore which you want to query. This option will resolve variables.
This command requires trust level 2.
All return codes are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain information about the specified mutex or event semaphore:
Table 75. Definition of map class STAF/Service/Sem/QueryMutex
| Description: This map class represents a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| state | State | <String> | 'Unowned' | 'Owned' |
| owner | Owner | <None> | <Map:STAF/Service/Sem/MutexOwner> |
|
| requestList | Pending Requests | <List> of <Map:STAF/Service/Sem/PendingRequest> |
|
Notes:
| |||
Table 76. Definition of map class STAF/Service/Sem/MutexOwner
| Description: This map class represents the owner of a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
| acquireTimestamp | Date-Time Acquired | <String> | <YYYYMMDD-HH:MM:SS> |
Table 77. Definition of map class STAF/Service/Sem/PendingRequest
| Description: This map class represents a pending request which is waiting to acquire a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| requestTimestamp | Date-Time Requested | <String> | <YYYYMMDD-HH:MM:SS> |
Table 78. Definition of map class STAF/Service/Sem/QueryEvent
| Description: This map class represents an event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| state | State | <String> | 'Posted' | 'Reset' |
| lastPosted | Last Posted | <Map:STAF/Service/Sem/EventRequester> |
|
| lastReset | Last Reset | <Map:STAF/Service/Sem/EventRequester> |
|
| waiterList | Waiters | <List> of <Map:STAF/Service/Sem/EventRequester> |
|
| Notes: If the event semaphore is currently in a reset state, "Waiters" will contain a list of requests waiting for the semaphore, if any. | |||
Table 79. Definition of map class STAF/Service/Sem/EventRequester
| Description: This map class represents a request for a event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| machine | Machine | <String> |
|
| handleName | handle | <String> |
|
| handle | Handle | <String> |
|
| user | User | <String> | <Authenticator>://<User ID> |
| endpoint | Endpoint | <String> | <Interface>://<System Identifier>[@<Port>] |
| timestamp | Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in default format, could look like:
State : Unowned Owner : <None> Pending Requests: []
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Owned
Owner : {
Machine : machine1.austin.ibm.com
Handle Name : STAX/Job/1
Handle : 17
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time Requested: 20041026-23:54:41
Date-Time Acquired : 20041026-23:54:41
}
Pending Requests: []
}
Syntax: QUERY MUTEX DataSource1
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Owned
Owner : {
Machine : machine1.austin.ibm.com
Handle Name : STAX/Job/1
Handle : 17
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time Requested: 20041026-23:54:41
Date-Time Acquired : 20041026-23:54:41
}
Pending Requests: [
{
Machine : machine2.austin.ibm.com
Handle Name : STAF/Client
Handle : 32
User : none://anonymous
Endpoint : tcp://machine2.austin.ibm.com@6500
Date-Time Requested: 20041026-23:56:16
}
{
Machine : server1.austin.ibm.com
Handle Name : semTest
Handle : 49
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server1.austin.ibm.com@6500
Date-Time Requested: 20041026-23:56:31
}
]
}
Syntax: QUERY EVENT Server1/LAN_Started
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Posted
Last Posted: {
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 20
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041026-23:59:51
}
Last Reset : {
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041026-23:59:15
}
Waiters : []
}
Syntax: QUERY EVENT Server1/LAN_Started
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
State : Reset
Last Posted: {
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 20
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041026-23:59:51
}
Last Reset : {
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Test1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041027-00:02:12
}
Waiters : [
{
Machine : server2.austin.ibm.com
Handle Name: myHandle
Handle : 17
User : IBM://Tester1@us.ibm.com
Endpoint : tcp://server2.austin.ibm.com@6500
Date-Time : 20041027-00:02:18
}
{
Machine : machine1.austin.ibm.com
Handle Name: STAF/Client
Handle : 22
User : none://anonymous
Endpoint : tcp://machine1.austin.ibm.com@6500
Date-Time : 20041027-00:02:15
}
]
}
LIST allows you to obtain a list of the mutex or event semaphores.
LIST <MUTEX | EVENT>
MUTEX specifies that you want a list of the mutex semaphores.
EVENT specifies that you want a list of the event semaphores.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain a list of the desired mutex or event semaphores:
Table 80. Definition of map class STAF/Service/Sem/MutexInfo
| Description: This map class represents a mutex semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| state | State | <String> | 'Unowned' | 'Owned' |
| pendingRequests | Pending Requests | <String> |
|
| Notes: "Pending Requests" is the number of requests waiting to acquire the mutex. | |||
Table 81. Definition of map class STAF/Service/Sem/EventInfo
| Description: This map class represents an event semaphore. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| state | State | <String> | 'Posted' | 'Reset' |
| waiters | Waiters | <String> |
|
| Notes: "Waiters" is the number of waiters waiting on the event semaphore. | |||
Syntax: LIST MUTEX
Results: If the request is issued from the command line, the result, in table format, could look like:
Name State Pending Requests ----------------- ------- ---------------- DataSource1 Unowned 0 Printers/Printer1 Owned 2
Syntax: LIST EVENT
Results: If the request is issued from the command line, the result, in table format, could look like:
Name State Waiters ------------------- ------ ------- Coffee/Ready Posted 0 Server1/LAN_Started Reset 5 Shutdown_The_Lab Reset 0
The SERVICE service is one of the internal STAF services. It provides the following commands.
LIST will display information about the services, service loaders, or authenticators available on the machine or requests that have been submitted on the machine.
LIST [SERVICES | SERVICELOADERS | AUTHENTICATORS |
REQUESTS [PENDING] [COMPLETE]] [LONG]
SERVICES specifies that you want a list of services that are registered.
SERVICELOADERS specifies that you want a list of the service loaders that are registered.
AUTHENTICATORS specifies that you want a list of the authenticators that are registered.
REQUESTS specifies that you want a list of requests.
PENDING specifies that the request list should include pending requests, i.e. requests which are still being processed.
COMPLETE specifies that the request list should include completed requests which have not yet been FREEd.
LONG specifies that the request list should include more detailed information about each request.
If neither PENDING nor COMPLETE is specified the default is PENDING.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain information about the request based on the options specified:
Table 82. Definition of map class STAF/Service/Service/ServiceInfo
| Description: This map class represents a service, serviceloader, or authenticator. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| library | Library | <String> | '<Internal>', '<Delegated>' or library name if external service |
| executable | Executable | <String> | <None> |
|
Notes:
| |||
Table 83. Definition of map class STAF/Service/Service/RequestInfo
| Description: This map class represents information about a request that has been submitted. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| requestNumber | Request#
(Req#) | <String> |
|
| state3 | Status | <String> | 'Pending' | 'Complete' |
| sourceMachine1 | Source Machine
(Source) | <String> |
|
| sourceHandleName1 | Source Handle Name
(Handle Name) | <String> |
|
| sourceHandle1 | Source Handle
(H#) | <String> |
|
| startTimestamp | Start Date-Time
(Date-Time) | <String> | <YYYYMMDD-HH:MM:SS> |
| targetMachine1 | Target Machine
(Target) | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> | Private data will be masked. |
| rc2 | Return Code
(RC) | <String> | <None> |
|
| result2 | Result | <String> | <None> |
|
Notes:
| |||
Syntax: LIST SERVICES
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable -------- ---------- ------------------------------------- CRON JSTAF C:\STAF\services\STAFCron.jar DELAY <Internal> <None> DIAG <Internal> <None> ECHO <Internal> <None> EM JSTAF C:\STAF\services\STAFEventManager.jar EMAIL JSTAF C:\STAF\services\STAFEmail.jar EVENT JSTAF C:\STAF\services\STAFEvent.jar FS <Internal> <None> HANDLE <Internal> <None> HELP <Internal> <None> LOG STAFLog <None> MISC <Internal> <None> MONITOR STAFMon <None> NC JSTAF C:\STAF\services\STAFNamedCounter.jar PING <Internal> <None> PROCESS <Internal> <None> QUEUE <Internal> <None> RESPOOL STAFPool <None> SEM <Internal> <None> SERVICE <Internal> <None> SHUTDOWN <Internal> <None> STAX JSTAF C:\STAF\services\STAX.jar TIMER JSTAF C:\STAF\services\STAFTimer.jar TRACE <Internal> <None> TRUST <Internal> <None> VAR <Internal> <None>
Syntax: LIST SERVICELOADERS
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable ------------------ -------- ---------------------------------------- STAFSERVICELOADER1 STAFDSLS <None> STAFSERVICELOADER2 JSTAF C:\STAF\services\CustomServiceLoader.jar
Syntax: LIST AUTHENTICATORS
Results: If the request is issued from the command line, the result, in table format, could look like:
Name Library Executable ---------- ------- -------------------------------------------------------- AUTHSAMPLE JSTAF C:\STAF\services\AuthSample.jar IBM JSTAF C:\STAF\services\STAFIBMIntraAuth.jar
Syntax: LIST REQUESTS
Results: If the request is issued from the command line, the result, in table format, could look like:
Request# Start Date-Time Service Request -------- ----------------- ------- ------------------------------------------ 39 20050321-16:33:03 QUEUE GET WAIT 63 20050321-16:33:03 QUEUE GET WAIT 10000 102 20050321-16:34:42 QUEUE GET WAIT 120000 TYPE ProductA/Test2/Status 165 20050321-16:34:52 DELAY DELAY 60000 106 20050321-16:34:58 SERVICE LIST REQUESTS
Syntax: LIST REQUESTS LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request
---- ------- ------------ -- --------- ---------- ------- ---------------------
39 local:/ STAF/SERVICE 11 20050321- client1.co QUEUE GET WAIT
/local /eM 14:25:04 mpany.com
63 local:/ STAF/Service 16 20050321- client1.co QUEUE GET WAIT 10000
/local /TimeR/Watch 14:25:04 mpany.com
102 local:/ ProductA/Tes 21 20050321- client1.co QUEUE GET WAIT 120000 TYPE
/local t2 16:34:42 mpany.com ProductA/Test2/Status
165 local:/ STAF/Client 27 20050321- client2 DELAY DELAY 60000
/local 16:34:52
180 local:/ STAF/Client 34 20050321- client1.co SERVICE LIST REQUESTS LONG
/local 14:39:04 mpany.com
Syntax: LIST REQUESTS PENDING COMPLETE LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# State Source Handle Name H# Date-Time Target Service Request RC Result
---- ------- ------- ----------- -- --------- ------ ------- -------- -- ------
39 Pending local:/ STAF/SERVIC 11 20050321- client QUEUE GET WAIT <N <None>
/local E/eM 14:25:04 1.comp on
any.co e>
m
63 Pending local:/ STAF/Servic 16 20050321- client QUEUE GET WAIT <N <None>
/local e/TimeR/Wat 14:25:04 1.comp 10000 on
ch any.co e>
m
102 Pending local:/ ProductA/Te 21 20050321- client QUEUE GET WAIT <N <None>
/local st2 16:34:42 1.comp 120000 T on
any.co YPE Prod e>
m uctA/Tes
t2/Statu
s
165 Pending local:/ STAF/Client 27 20050321- client DELAY DELAY 60 <N <None>
/local 16:34:52 2 000 on
e>
176 Complet local:/ TestA 36 20050321- client MISC VERSION 0 3.0.0
e /local 13:30:14 1.comp
any.co
m
180 Pending local:/ STAF/Client 38 20050321- client SERVICE LIST REQ <N <None>
/local 13:30:16 1.comp UESTS PE on
any.co NDING CO e>
m MPLETE L
ONG
Syntax: LIST REQUESTS COMPLETE LONG
Results: If the request is issued from the command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request RC Result
---- ------- ----------- -- --------- ---------- ------- -------- -- ------
176 local:/ TestA 36 20050321- client1.co MISC VERSION 0 3.0.0
/local 13:30:14 mpany.com
QUERY will display information about a service, authenticator, or service loader available on the machine, or about a request that has been submitted on the machine.
QUERY SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> |
AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number>
SERVICE specifies the name of the service to be queried.
SERVICELOADER specifies the name of the service loader to be queried.
AUTHENTICATOR specifies the name of the authenticator service to be queried.
REQUEST specifies the number of the request to be queried.
This command requires trust level 2.
All return codes from QUERY are documented in Appendix A, "API Return Codes".
If successful, the result buffer will contain the following based on the request:
Table 84. Definition of map class STAF/Service/Service/QueryService
| Description: This map class represents a service, service loader, or authenticator. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| name | Name | <String> |
|
| library | Library | <String> | '<Internal>', '<Delegated>' or library name if external service |
| executable | Executable | <String> | <None> |
|
| options | Options | List of <String> |
|
| parameters | Parameters | <String> | <None> |
|
Notes:
| |||
Table 85. Definition of map class STAF/Service/Service/QueryRequest
| Description: This map class represents a request that has been submitted. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| requestNumber | Request# | <String> |
|
| state | Request Status | <String> | 'Pending' | 'Complete' |
| sourceMachine | Source Machine | <String> |
|
| sourceHandleName | Source Handle Name | <String> |
|
| sourceHandle | Source Handle | <String> |
|
| startTimestamp | Start Date-Time | <String> | <YYYYMMDD-HH:MM:SS> |
| targetMachine | Target Machine | <String> |
|
| service | Service | <String> |
|
| request | Request | <String> |
|
| rc | Return Code | <String> | <None> |
|
| result | Result | <String> | <None> |
|
Notes:
| |||
Syntax: QUERY SERVICE LOG
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : LOG
Library : STAFLog
Executable: <None>
Options : []
Parameters: DEFAULTMAXQUERYRECORDS 50
}
Syntax: QUERY SERVICE STAX
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : STAX
Library : JSTAF
Executable: C:\STAF\services\stax\STAX.jar
Options : [
JVMName=STAX
J2=-Xmx512m
]
Parameters: EXTENSIONXMLFILE C:/STAF/services/stax/extensions.xml
}
Syntax: QUERY AUTHENTICATOR AuthSample
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : AUTHSAMPLE
Library : JSTAF
Executable: C:\STAF\authenticators\AuthSample.jar
Options : [
JVMName=Auth
]
Parameters: USERPROPERTIESFILE C:/STAF/authenticators/authsample.properties
}
Syntax: QUERY SERVICELOADER STAFServiceLoader1
Results: If the request is issued from the command line, the result, in default format, could look like:
{
Name : STAFSERVICELOADER1
Library : STAFDSLS
Executable: <None>
Options : []
Parameters: <None>
}
Syntax: QUERY REQUEST 34
Results: If the request is issued from the command line, the result, in default format, could look like:
Request Number : 34 Request Status : Pending Source Machine : local://local Source Handle Name: STAF/SERVICE/EM Source Handle : 10 Start Date-Time : 20050321-19:02:28 Target Machine : server1.company.com Service : QUEUE Request : GET WAIT Return Code : <None> Result : <None>
ADD will add (register and initialize) the specified external service and make it available on the machine.
ADD SERVICE <Service Name> LIBRARY <Library Name> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
SERVICE specifies the name by which this service will be known on this machine.
LIBRARY specifies the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See section 4.4.2, "JSTAF service proxy library" for information regarding the JSTAF service proxy library. Otherwise, see the documentation provided by the service proxy library.
OPTION specifies a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See section 4.4.2, "JSTAF service proxy library" for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the service during initialization.
This command requires trust level 5.
All return codes from ADD are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain nothing.
Syntax: ADD SERVICE Monitor LIBRARY STAFMon
Syntax: ADD SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar PARMS "NUMTHREADS 8"
REMOVE will remove (unregister and terminate) the specified external service, making it no longer available on the machine.
REMOVE SERVICE <Service Name>
SERVICE specifies the name of the service to remove.
This command requires trust level 5.
All return codes from REMOVE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain nothing.
Syntax: REMOVE SERVICE Event
FREE returns the results of a completed request that was submitted using the kSTAFReqQueue or kSTAFReqQueueRetain options (see 6.2.5, "STAFSubmit2" for more information). This command also removes the request from the request list.
FREE REQUEST <Request Number> [FORCE]
REQUEST specifies which request should be freed.
FORCE must be specified if any process other than the originating process tries to FREE the request's results.
This command requires trust level 5.
All return codes from FREE are documented in Appendix A, "API Return Codes".
If successful, the result buffer for a FREE request will contain
a marshalled <Map:STAF/Service/Service/FreeRequestInfo>
representing the results of the completed request.
The map is defined as follows:
Table 86. Definition of map class STAF/Service/Service/QueryRequest
| Description: This map class represents the results of a completed request. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | Return Code | <String> |
|
| result | Result | <String> |
|
Notes:
| |||
Syntax: FREE REQUEST 16
Results: If the request is issued from the command line, the result, in default format, could look like:
Return Code: 0 Result : 3.0.0
The SHUTDOWN service is an internal STAF service. It provides the following commands.
SHUTDOWN, as the name implies, 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 type of the notification message will be STAF/Shutdown with a blank message.
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".
On successful return, the result buffer for a NOTIFY LIST
request will contain a marshalled
<List> of <Map:STAF/Service/Shutdown/Notifiee>
representing a list of all the registered notifiees.
The map is defined as follows:
Table 87. Definition of map class STAF/Service/Shutdown/Notifiee
| Description: This map class represents a registered shutdown notifiee. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| priority | Priority | <String> | 'Stdout' | 'Stderr' or a file name |
| machine | Machine | <String> | 'Enabled' | 'Disabled' |
| notifyBy | Notify By | <String> | 'Name' | 'Handle' |
| notifiee | Notifiee | <String> | |
| Notes: If the "Notify By" value is 'Name', the notifiee will be notified by handle name and the "Notifiee" value will be the handle name. Otherwise, if the "Notify By" value is 'Handle', the notifiee will be notified by handle and the "Notifiee" value will be the handle number. | |||
Request: NOTIFY LIST
Results: If the request is issued from the command line, the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- ---------------------- --------- --------------- 5 server1.austin.ibm.com Name ShutdownCatcher 3 client2.austin.ibm.com Handle 18
The TRACE service is one of the internal STAF services. It provides the following trace commands.
The purpose of the Trace service is to allow you to control the trace messages recorded for STAF services. For example, if you are experiencing a problem with a STAF service or a request to a STAF service, you can specify various STAF trace points and/or STAF service(s) to be enabled for tracing to record additional trace messages which can help you resolve the problem.
Note: If you enable one or more of the "service" tracepoints (e.g. ServiceRequest, ServiceResult, ServiceError, ServiceAccessDenied, or RemoteRequests), these trace messages will only be reported for the services you have enabled for tracing.
The format of each trace message is the following
<Timestamp>;<Thread>;<Trace Point>;<Message>
where:
<Timestamp> is the date/time of the message.
<Thread> is the thread on which the message originated.
<Trace Point> is the hexadecimal representation of the message's trace point. See table 8.17.2, "Trace Points Reference" for a list of trace points.
<Message> is the actual trace message. Private data will be masked.
Here's an example of a ServiceManagement trace message:
20050811-16:20:50;1;00000010;Service HELP: Initializing
Here's an example of a Warning trace message:
20050811-10:10:50;4836;00000400;STAFConnectionManager::makeConnection - Attempt #1 of 2 (Delay 41 milliseconds), RC: 16, Result: STAFConnectionProviderConnect: Timed out connecting to endpoint: select() timeout: 22, Endpoint: client1
Here's an example of ServiceRequest and ServiceResult trace messages:
20050811-10:33:54;4836;00000001;PROCESS Service Request - Client: local://local,
Handle: 30, Process: STAF/Client, Request: start command date returnstdout wait
20050811-10:33:54;4836;00000002;PROCESS Service Result (0) - Client: local://loc
al, Handle: 30, Process: STAF/Client, Request: start command date returnstdout w
ait, Result: {
Return Code: 0
Key : <None>
Files : [
{
Return Code: 0
Data : Thu Aug 11 10:33:54 CDT 2005
}
]
}
The following are the valid trace points along with their hexadecimal representation
and their descriptions.
The hexadecimal representation of a trace point is logged in each trace message.
Trace points are not case sensitive.
Table 88. Trace point hexadecimal representation
| Hex | Trace point | Description |
|---|---|---|
| 00000001 | ServiceRequest | The trace point which causes a trace message to be generated for every incoming service request before it is processed by the service. |
| 00000002 | ServiceResult | The trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. This tracepoint overrides the ServiceError and ServiceAccessDenied tracepoints. |
| 00000004 | ServiceError | The trace point which causes a trace message to be generated for every incoming service request which results in a non-zero error code. This tracepoint overrides the ServiceAccessDenied tracepoint. |
| 00000008 | ServiceAccessDenied | The trace point which causes a trace message to be generated for every incoming service request which results in an "Insufficient Trust Level" (aka "Access Denied") error code. |
| 00000010 | ServiceManagement | The trace point which causes a trace message to be generated for service management operations such as service initialization and termination. |
| 00000020 | RemoteRequests | The trace point which enables trace message to be generated for requests destined for other machines. |
| 00000100 | Error | The trace point which causes a trace message to be generated for error conditions that STAF detects, such as broken communication connections and fatal STAF Service errors. The Error trace point is turned on by default. |
| 00000200 | Registration | The trace point which causes a trace message to be generated for every registration or unregistration done by a process. |
| 00000400 | Warning | The trace point which causes a trace message to be generated for warning conditions that STAF detects. |
| 00000800 | Info | The trace point which causes a trace message to be generated for information conditions that STAF detects. |
| 00001000 | Deprecated | The trace point which causes a trace message to be generated for deprecated options that STAF detects. A deprecated option is not recommended for use, generally due to improvements, and a replacement option is usually given. Deprecated options may be removed in future implementations. The Deprecated trace point is turned on by default. |
| 00002000 | Debug | The trace point which causes a trace message to be generated for debug conditions that STAF detects. |
| 00004000 | ServiceComplete | The trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. Note that the trace message will include the return code for the service request, but will not include the service request result. |
ENABLE allows you to enable trace points and STAF services for tracing. See table 8.17.2, "Trace Points Reference" for a list of valid trace points.
Note: You can enable services that aren't currently registered and they will begin tracing when they are registered with STAF.
ENABLE ALL [ TRACEPOINTS | SERVICES ] ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> ENABLE TRACEPOINT <Trace point> [ TRACEPOINT <Trace point> ]... ENABLE SERVICE <Service> [ SERVICE <Service> ]...
ALL indicates to enable tracing for all trace points and/or services
TRACEPOINTS indicates a list of trace points to be enabled for tracing. The trace points in the list should be separated by spaces. This option will resolve variables.
SERVICES indicates a list of services to be enabled for tracing. The services in the list should be separated by spaces. This option will resolve variables.
TRACEPOINT indicates which trace point should be enabled for tracing. This option will resolve variables.
SERVICE indicates which service should be enabled for tracing. This option will resolve variables.
This command requires trust level 5.
All return codes from ENABLE are documented in Appendix A, "API Return Codes".
For ENABLE the result buffer will be empty if there are no errors
Syntax: ENABLE TRACEPOINTS "ServiceRequest ServiceResult ServiceManagement"
Syntax: ENABLE TRACEPOINTS "Error Warning"
Syntax: ENABLE ALL TRACEPOINTS
Syntax: ENABLE TRACEPOINT RemoteRequests
Syntax: ENABLE SERVICES "PROCESS QUEUE"
Syntax: ENABLE ALL SERVICES
Syntax: ENABLE ALL
Syntax: ENABLE SERVICE VAR
Syntax: ENABLE SERVICE :7:SERVICE
DISABLE allows you to disable trace points and STAF services for tracing. See table 8.17.2, "Trace Points Reference" for a list of valid trace points.
DISABLE ALL [ TRACEPOINTS | SERVICES ] DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> DISABLE TRACEPOINT <Trace point> [ TRACEPOINT <Trace point> ]... DISABLE SERVICE <Service> [ SERVICE <Service> ]...
ALL indicates to disable tracing for all trace points and/or services
TRACEPOINTS indicates a list of trace points to be disabled for tracing. The trace points in the list should be separated by spaces. This option will resolve variables.
SERVICES indicates a list of services to be disabled for tracing. The services in the list should be separated by spaces. This option will resolve variables.
TRACEPOINT indicates which trace point should be disabled for tracing. This option will resolve variables.
SERVICE indicates which service should be disabled for tracing. This option will resolve variables.
This command requires trust level 5.
All return codes from DISABLE are documented in Appendix A, "API Return Codes".
For DISABLE the result buffer will be empty if there are no errors
Syntax: DISABLE TRACEPOINTS "ServiceAccessDenied Error"
Syntax: DISABLE TRACEPOINTS "ServiceResult Error"
Syntax: DISABLE ALL TRACEPOINTS
Syntax: DISABLE TRACEPOINT RemoteRequests
Syntax: DISABLE SERVICES "PROCESS QUEUE"
Syntax: DISABLE ALL SERVICES
Syntax: DISABLE ALL
Syntax: DISABLE SERVICE VAR
Syntax: DISABLE SERVICE :7:SERVICE
PURGE removes all unregistered services from the service list
PURGE
This command requires trust level 5.
All return codes from PURGE are documented in Appendix A, "API Return Codes".
For PURGE the result buffer will be empty if there are no errors.
Syntax: PURGE
LIST Returns a list of current settings including trace destination and default service state, and a list of the current tracing statuses for all tracepoints and services
LIST [SETTINGS]
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
On successful return, the result buffer for a LIST
request will contain a marshalled
<Map:STAF/Service/Trace/TraceInfo>
representing the current trace settings.
The maps are defined as follows:
Table 89. Definition of map class STAF/Service/Trace/TraceInfo
| Description: This map class represents the current trace settings. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| tracingTo | Tracing To | <String> | 'Stdout' | 'Stderr' or a file name |
| defaultServiceState | Default Service State | <String> | 'Enabled' | 'Disabled' |
| tracePoints | Trace Points | <Map:STAF/Service/Trace/Tracepoint> |
|
| services | Services | <Map:STAF/Service/Trace/Service> |
|
| Notes: "Tracing" indicates the current trace output destination. | |||
Table 90. Definition of map class STAF/Service/Trace/Tracepoint
| Description: This map class represents the tracepoints and their trace states. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| INFO | Info | <String> | 'Enabled' | 'Disabled' |
| WARNING | Warning | <String> | 'Enabled' | 'Disabled' |
| ERROR | Error | <String> | 'Enabled' | 'Disabled' |
| SERVICEREQUEST | ServiceRequest | <String> | 'Enabled' | 'Disabled' |
| SERVICERESULT | ServiceResult | <String> | 'Enabled' | 'Disabled' |
| SERVICEERROR | ServiceError | <String> | 'Enabled' | 'Disabled' |
| SERVICEACCESSDENIED | ServiceAccessDenied | <String> | 'Enabled' | 'Disabled' |
| REMOTEREQUESTS | RemoteRequests | <String> | 'Enabled' | 'Disabled' |
| REGISTRATION | Registration | <String> | 'Enabled' | 'Disabled' |
| DEPRECATED | Deprecated | <String> | 'Enabled' | 'Disabled' |
| DEBUG | Debug | <String> | 'Enabled' | 'Disabled' |
Table 91. Definition of map class STAF/Service/Trace/Service
| Description: This map class represents the services and their trace states. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| <ServiceName> | <ServiceName> | <String> | 'Enabled' | 'Disabled' |
| Notes: This map is dynamically generated at the time of the LIST request based on the services in the trace status list at that time. It's keys will be the names of the internal services plus any external services that have been registered and any other services for which tracing has been explicitly set. | |||
Syntax: LIST or LIST SETTINGS
Results: If the request is issued from the command line, the result, in verbose format, could look like:
{
Tracing To : Stdout
Default Service State: Enabled
Trace Points : {
Info : Disabled
Warning : Enabled
Error : Enabled
ServiceRequest : Disabled
ServiceResult : Disabled
ServiceError : Disabled
ServiceAccessDenied: Disabled
RemoteRequests : Disabled
Registration : Disabled
Deprecated : Enabled
Debug : Disabled
}
Services : {
DELAY : Enabled
DIAG : Disabled
ECHO : Enabled
EMAIL : Enabled
EVENT : Enabled
FS : Enabled
HANDLE : Enabled
HELP : Disabled
LOG : Enabled
MONITOR : Enabled
MISC : Enabled
PING : Enabled
PROCESS : Enabled
QUEUE : Enabled
SEM : Enabled
SERVICE : Enabled
SHUTDOWN: Enabled
STAX : Enabled
TRACE : Enabled
TRUST : Enabled
VAR : Enabled
}
}
Allows you to set the destination for the tracing information, or the default tracing state for new services.
SET DESTINATION TO <STDOUT | STDERR | FILE <File name> > SET DEFAULTSERVICESTATE < Enabled | Disabled >
DESTINATION TO indicates to set the destination for the tracing information
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.
DEFAULTSERVICESTATE sets the default tracing state for services that have not yet registered with STAF. The default tracing state for services is enabled. This option will resolve variables.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
For SET the result buffer will be empty
Syntax: SET DESTINATION TO STDERR
Syntax: SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc
Syntax: SET DEFAULTSERVICESTATE Enabled
The TRUST Service is one of the internal STAF services. It allows you to query and set the trust entries. It provides the following commands.
SET will set the default trust level or the trust level for a specific machine or user.
SET <MACHINE <Machine> | USER <User> | DEFAULT> LEVEL <Level>
MACHINE indicates a machine for which to set a trust level. The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).
Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.
Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)
USER indicates a user for which to set a trust level. The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
DEFAULT specifies that you want to set the default trust level.
LEVEL specifies the level of trust you wish to set.
This command requires trust level 5.
All return codes from SET are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a SET command.
Syntax: SET MACHINE local://local LEVEL 5
Syntax: SET DEFAULT LEVEL 1
Syntax: SET MACHINE client1.austin.ibm.com LEVEL 5
Syntax: SET MACHINE 9.3.224.16 LEVEL 5
Syntax: SET MACHINE tcp://mysystem.site.com LEVEL 4
Syntax: SET MACHINE badguy.austin.ibm.com LEVEL 0
Syntax: SET MACHINE tcp2://9.3.224.* LEVEL 3
Syntax: SET MACHINE *.austin.ibm.com LEVEL 2
Syntax: SET MACHINE tcp*://*.site.com LEVEL 2
Syntax: SET USER John@company.com LEVEL 5
Syntax: SET USER badguy@company.com LEVEL 0
Syntax: SET USER *@company.com LEVEL 3
Syntax: SET USER SampleAuth://*@company.com LEVEL 4
Syntax: SET USER *://* LEVEL 1
GET will return the effective trust level of a specific machine and, optionally, for a specific user.
GET MACHINE <Machine> [USER <User>]
MACHINE specifies the machine for which to return the effective trust level. The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Wildcard patterns, '*' and '?', should not be specified. If a port is included (e.g. @6500) at the end of the machine value, it will be removed.
If the machine has a matching MACHINE trust entry, the effective trust level is the level specified in the MACHINE trust entry. Otherwise, the effective trust level is the default trust level.
USER specifies the user for which to return the effective trust level. The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Wildcard patterns, '*' and '?', cannot be specified.
If the user has a matching USER trust entry, the effective trust level is the level specified in the USER trust entry. Otherwise, if the machine has a matching MACHINE trust entry, the effective trust level is the level specified in the MACHINE trust entry. Otherwise, the effective trust level is the default trust level.
This command requires trust level 2.
All return codes from GET are documented in Appendix A, "API Return Codes".
The result buffer will contain the effective trust level of the given machine.
For the following examples, assume the trust entries for machines and users are as follows with tcp as the default network interface and SampleAuth as the default authenticator:
Type Entry Trust Level ------- ----------------------------- ----------- Default <None> 1 Machine *://*.austin.ibm.com 2 Machine *://client1.austin.ibm.com 5 Machine *://client3.austin.ibm.com 3 Machine local://local 5 Machine tcp://client2.austin.ibm.com 0 User SampleAuth://*@company.com 3 User SampleAuth://Jane@company.com 4 User SampleAuth://John@company.com 5
Here are some GET requests and their results:
Request: GET MACHINE client1.austin.ibm.com Result : 5
Request: GET MACHINE tcp://client2.austin.ibm.com Result : 0
Request: GET MACHINE client3.austin.ibm.com Result : 3
Request: GET MACHINE client4.austin.ibm.com Result 2
Request: GET MACHINE server1.raleigh.ibm.com Result: 1
Request: GET USER John@company.com MACHINE client3.austin.ibm.com Result : 5
Request: GET USER SampleAuth://Jane@company.com MACHINE client1.austin.ibm.com Result : 4
Request: GET USER Henry@company.com MACHINE client1.austin.ibm.com Result : 3
Request: GET USER Sally@mybusiness.com MACHINE client1.austin.ibm.com Result : 5
Request: GET USER Sally@mybusiness.com MACHINE server1.raleigh.ibm.com Result : 1
LIST will return the default trust level and a list of the trust entries for machines and users.
LIST
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
The result buffer will contain a marshalled
<List> of <Map:STAF/Service/Trust/Entry>, representing
all the trust entries. The first trust entry in the list will be for
the default trust entry, followed by trust entries for machines,
and then followed by trust entries for users.
The map is defined as follows:
Table 92. Definition of map class STAF/Service/Trust/Entry
| Description: This map class represents a trust entry. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| type | Type | <String> | 'Default' | 'Machine' | 'User' |
| entry | Entry | <String> | <None> | <Machine Spec> | <User Spec) |
| trustLevel | Trust Level | <String> | '0' - '5' |
Notes:
| |||
Syntax: LIST
Result: If the request is submitted from the command line, the result, in table format, could look like:
Type Entry Trust Level ------- ----------------------------- ----------- Default <None> 1 Machine *://*.austin.ibm.com 2 Machine *://9.31.73.14* 3 Machine *://9.31.73.147 5 Machine *://client1.austin.ibm.com 5 Machine *://client3.austin.ibm.com 3 Machine local://local 5 Machine tcp://client2.austin.ibm.com 0 User SampleAuth://*@company.com 3 User SampleAuth://Jane@company.com 4 User SampleAuth://John@company.com 5
DELETE will remove the explicit trust entry for the specified machine or user.
DELETE MACHINE <Machine> | USER <User>
MACHINE specifies the machine for which you wish to delete the specific trust entry. The format for <Machine> is:
[<Interface>://]<System Identifier>where:
If a port is included (e.g. @6500) at the end of the machine value, it will be removed.
USER specifies the user for which you wish to delete the specific trust entry. The format for <User> is:
[<Authenticator>://]<User Identifier>where:
This command requires trust level 5.
All return codes from DELETE are documented in Appendix A, "API Return Codes".
The result buffer will contain no data on return from a DELETE command.
Syntax: DELETE MACHINE client1.austin.ibm.com
Syntax: DELETE MACHINE tcp://mysystem.site.com
Syntax: DELETE MACHINE 9.3.224.82
Syntax: DELETE MACHINE *.austin.ibm.com
Syntax: DELETE USER John@company.com
Syntax: DELETE USER *@company.com
Syntax: DELETE USER Auth2://Mary
Syntax: DELETE USER *://*
The Variable Service, called VAR, is one of the internal STAF services. It allows you to manage the system, shared, and per-process variable pools. It provides the following commands.
SET will set a variable to a certain value. The variable is created if it does not exist.
Note that you may SET multiple variables with a single request.
SET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name=Value> [VAR <Name=Value>]...
SYSTEM specifies that you want to set the value of the variable in the system variable pool.
SHARED specifies that you want to set the value of the variable in the shared variable pool.
HANDLE indicates that you want to set the value of the variable in the variable pool associated with the specified handle.
If options SYSTEM, SHARED, and HANDLE are not specified, the variable will be set in the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be set in the system variable pool.
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.
GET will retrieve the value of a variable.
Note: You almost never want to use the GET command. Instead, you should use RESOLVE to retrieve the value of a variable.
GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name>
SYSTEM specifies that you want to get the value of the variable from the system variable pool.
SHARED specifies that you want to get the value of the variable from the shared variable pool.
HANDLE indicates that you want to get the value of the variable from the variable pool associated with the specified handle.
If options SYSTEM, SHARED, and HANDLE are not specified, the value of the variable will be retrieved from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be retrieved from the system variable pool.
This command requires trust level 2.
All return codes from GET are documented in Appendix A, "API Return Codes".
The result buffer will contain the value of the variable.
LIST will return a list of all variables and their values.
LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]]
SYSTEM specifies that you want the list of variables from the system variable pool only.
SHARED specifies that you want the list of variables from the shared variable pool only.
HANDLE specifies that you want the list of variables from the handle variable pool only.
ASHANDLE indicates that you want the list of a merged set of variables from the specified handle's variable pool, its system's shared variable pool, and its system's system variable pool. Variables in a pool earlier in the list override variables in a pool later in the list.
REQUEST with a request number indicates that you want a list of a merged set of variables which will use variables from the originating handle's pool associated with the request number, the originating system's shared pool, the local system's shared pool, and the local system's system pool if the request came from remote; otherwise, will use the originating handle's pool associated with the request number, the local system's shared pool, and the local system's system pool if the request came from local. Variables in a pool earlier in the list override variables in a pool later in the list.
If a LIST REQUEST request is made without specifying a request number, the list is constructed in the context of the LIST REQUEST request, itself.
If a LIST request is made without specifying SYSTEM, SHARED, HANDLE, ASHANDLE, and REQUEST, the behavior will be identical to a LIST REQUEST request being made with no request number specified.
This command requires trust level 2.
All return codes from LIST are documented in Appendix A, "API Return Codes".
The result buffer will contain a marshalled
<Map:STAF/Service/Var/VarInfo> with an entry for each variable.
The map is defined as follows:
Table 93. Definition of map class STAF/Service/Var/VarInfo
| Description: This map class represents the variables. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| <Variable Name> | <Variable Name> | <String> |
|
| Notes: This map is dynamically generated with the key being a variable name and the value being the value for the variable. | |||
If the request is submitted from the command line, the result, in default format, could look like:
Bad String : SYS3175
Good String : Command completed successfully
STAF/Config/BootDrive : C:
STAF/Config/Machine : automate.austin.ibm.com
STAF/Config/MachineNickname : automate
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
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).
RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]]
STRING <String> [STRING <String>]...
SYSTEM specifies that only variables from the system variable pool should be used to resolve a variable reference.
SHARED specifies that only variables from the shared variable pool should be used to resolve a variable reference.
HANDLE specifies that only variables from the handle variable pool should be used to resolve a variable reference.
ASHANDLE indicates the variable reference should try to be resolved from the specified handle's variable pool, its system's shared variable pool, and its system's system variable pool. Variables in a pool earlier in the list override variables in a pool later in the list.
REQUEST with a request number indicates the variable reference should try to be resolved from the originating handle's pool associated with the specified request number, the originating system's shared pool, the local system's shared pool, and the local system's system pool if the request came from remote; otherwise, will use the originating handle's pool associated with the specified request number, the local system's shared pool, and the local system's system pool if the request came from local. Variables in a pool earlier in the list override variables in a pool later in the list.
If a RESOLVE REQUEST request is made without specifying a request number, variable resolution is done in the context of the RESOLVE REQUEST request, itself.
If a RESOLVE request is made without specifying SYSTEM, SHARED, HANDLE, ASHANDLE, and REQUEST, the behavior will be identical to a RESOLVE REQUEST request being made with no request number specified.
This command requires trust level 2.
All return codes from RESOLVE are documented in Appendix A, "API Return Codes".
On successful return, the result buffer will contain results based on whether the STRING option was specified once or multiple times:
Table 94. Definition of map class STAF/Service/Var/ResolveString
| Description: This map class represents a string with all variable references resolved. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| rc | RC | <String> |
|
| result | Result | <String> |
|
| Notes:
If all variables in the string are resolved successfully, the "RC" value will be '0' and the "Result" will contain the string with all variable references resolved. Otherwise, if an error occurred resolving a variable, the "RC" value will contain the error return code and the result will contain additional information on the error, such as the name of a variable that could not be resolved. | |||
For the following examples, assume the following variables are in System1's system variable pool
a=Partridge b=Doves c=Hens d=Birds e=Ringsthe following variables are in System1's shared variable pool
a=Happy b=Sleepythe following variables are in System1's originating handle variable pool
a=Onethe following variables are in System2's system variable pool
a=Geese b=Swans c=Maids d=Ladies e=Lordsthe following variables are in System2's shared variable pool
d=Grumpy e=Dopeyand the following variables are in the System1's variable pool associated with handle 71
a=Dogs b=CatsLet's assume the following requests are done from System1:
The following examples show the use of a caret (^) as an escape character for "{" and "^". Assume the following variables are in the system variable pool for these examples:
h=Hi Hi=HI ^Hi=Hello
Note that {^{h}} shows that a caret cannot be used as an escape character within a variable reference.
Here's an example of resolving multiple strings in a single RESOLVE request.
RC Result -- ------ 0 3.0.0 13 aaa 0 C:
DELETE will remove the given variable from the appropriate variable pool.
Note that you may DELETE multiple variables with a single request.
DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]...
SYSTEM specifies that you want to delete the variable from the system variable pool.
SHARED specifies that you want to delete the variable from the shared variable pool.
HANDLE indicates that you want to delete the variable from the variable pool associated with the specified handle.
If options SYSTEM, SHARED, and HANDLE are not specified, the variable will be deleted from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be deleted from the system variable pool.
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.
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.
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
ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
[RELATIVETO <Directory>]
or
ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
[RELATIVETO <Directory>]
An ADD request is equivalent to a ZIP ADD request. An ADD request is preferred. A ZIP ADD request is deprecated and will generate a trace message with a Deprecated tracepoint.
ZIPFILE contains the fully qualified ZIP archive name.
FILE contains the fully qualified file name you want to add into the ZIP archive.
DIRECTORY contains the fully qualified directory name you want to add info the ZIP archive.
RELATIVETO contains the prefix to be excluded from the fully qualified file name or directory name that is to be added into the ZIP archive.
RECURSE indicates that the all the files and subdirectories in the given directory will be added recursively.
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.
Syntax: ADD ZIPFILE D:/myzip.zip FILE C:/file.txt
Syntax: ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RELATIVETO /opt
Syntax: ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RECURSE RELATIVETO /opt
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.
Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY D:/mydata/
Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY /usr/lpp/mydata/FILE myjava/Hello.java RESTOREPERMISSION REPLACE
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 marshalled
<List> of <Map:STAF/Service/Zip/ZipInfo> representing
content of the Zip archive. The map is defined as follows:
Table 95. Definition of map class STAF/Service/Zip/ZipInfo
| Description: This map class represents an entry in Zip archive. | |||
| Key Name | Display Name | Type | Format / Value |
|---|---|---|---|
| length | Length | <String> |
|
| method | Method | <String> |
|
| size | Size | <String> |
|
| ratio | Ratio | <String> |
|
| date | Date | <String> |
|
| time | Time | <String> |
|
| crc-32 | CRC-32 | <String> |
|
| name | Name | <String> |
|
Notes:
| |||
Syntax: LIST ZIPFILE /usr/local/staf/services/STAXV300.zip
Results: If the request is submitted from the command line, the result, in table format, could look like:
Length Method Size Ratio Date Time CRC-32 Name
------- ------ ------- ----- -------- ----- -------- ------------------------
30745 Defl:N 9575 31% 04-02-04 11:16 cfd0aacb History
27227 Defl:N 24653 90% 04-02-04 11:16 c03ffb2c STAFEvent.jar
2566524 Defl:N 2501266 97% 04-02-04 11:16 e1f6f392 STAX.jar
185037 Defl:N 172931 93% 04-02-04 11:16 51b7700d STAXMon.jar
0 Stored 0 0% 04-02-04 11:16 00000000 libraries/
58695 Defl:N 11009 18% 04-02-04 11:16 0142b502 libraries/STAXUtil.html
82953 Defl:N 15887 19% 04-02-04 11:16 349eee04 libraries/STAXUtil.xml
2453 Defl:N 1082 44% 04-02-04 11:16 a98db290 readme.1st
0 Stored 0 0% 04-02-04 11:16 00000000 samples/
5274 Defl:N 826 15% 04-02-04 11:16 277d4fb7 samples/FunctionList.xsl
11140 Defl:N 2959 26% 04-02-04 11:16 8584d238 samples/sample1.xml
764931 Defl:N 512404 66% 04-02-04 11:16 8165dd0c staxug.pdf
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.
Syntax: DELETE ZIPFILE D:/myzip.zip FILE myjava/Hello.java CONFIRM
Syntax: DELETE ZIPFILE /opt/myzip.zip FILE myjava/Hello.java FILE bin/run CONFIRM
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 96. 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. |
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 "|".
C:\STAF\data\STAF\service\log\ <-Global Top C:\STAF\data\STAF\service\log\GLOBAL\ <--Global Dir STRESSTST.LOG <---Global Log SUITE100.LOG <---Global Log C:\STAF\data\STAF\service\log\MACHINE\ <-Machine Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\ <--clieot1 Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\GLOBAL\ <---client1 Global Top TESTLOG1.LOG <----client1 Global Logs C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\ <--client1 Handle Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\100\ <---Handle 100 Top TESTLOG2.LOG <---Handle 100 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\ <--AUTOMATE Top C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\GLOBAL\ <---AUTOMATE Global Top AUTOGLOB.LOG <----AUTOMATE Global Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\ <---AUTOMATE Handle Top C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\42\ <----Handle 42 Top HANDLOG1.log <-----Handle 42 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\43\ <----Handle 43 Top HANDLOG2.log <-----Handle 43 Log HANDLOG3.log <-----Handle 43 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\44\ <----Handle 44 Top HANDLOG4.log <-----Handle 44 Log C:\STAF\data\STAF\service\log\MACHINE\automate\HANDLE\45\ <----Handle 45 Top HANDLOG5.log <-----Handle 45 Log
Date-Time|Machine|Handle|Handle Name|User|Endpoint|Level|Message
C:\>FmtLog FORMAT LOGFILE C:/STAF/data/STAF/service/LOG/MACHINE/sharon/GLOBAL/STAX_Job_4_User.log NEWFILE C:/myLog.txt Formatted 10 record(s) to C:/myLog.txt
The contents of C:/myLog.txt could look like the following:
20041029-15:42:03|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|TestMachines=['client1.austin.ibm.com'] 20041029-15:42:04|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|JobHandle=78 20041029-15:42:04|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|STAXMachineNickname=sharon 20041029-15:42:04|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|STAXMachine=lucas.austin.ibm.com 20041029-15:42:08|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|Test machine: client1.austin.ibm.com OS type: Win2000 STAFRoot: C:\STAF 20041029-15:42:08|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|STAF Testing started on machine client1.austin.ibm.com 20041029-15:44:28|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|STAF Testing completed on machine client1.austin.ibm.com 20041029-15:44:28|lucas.austin.ibm.com|78|STAX/Job/4|none://anonymous|tcp://lucas.austin.ibm.com|Info|STAF Testing completed in 146 seconds 20041104-18:27:07|lucas.austin.ibm.com|50|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT 20041105-11:22:51|lucas.austin.ibm.com|89|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT
Some known problems in STAF V3.0.0 that we plan on fixing in later releases are:
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 97. STAF API Return Codes
| Error Code | Meaning | Comment |
|---|---|---|
| 0 | No error |
|
| 1 | Invalid API | This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors. |
| 2 | Unknown Service | You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service. |
| 3 | Invalid Handle | You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF. |
| 4 | Handle already exists | This indicates that you are trying to register a process with one name when
that process has already been registered with a different name. If you
register the same process multiple times, ensure that you use the same name
on each registration call.
Note: If you receive this error code when trying to perform an operation other than registering a service, report it to the authors. |
| 5 | Handle does not exist | You are trying to perform an operation on a handle that does not exist. For example, you may be trying to stop a process, but you are specifying the wrong handle. |
| 6 | Unknown Error | An unknown error has occurred. This error is usually an indication of an internal STAF error. If this error occurs, report it the authors. |
| 7 | Invalid Request String | You have submitted an improperly formatted request to a service. See the
appropriate section in this document for the syntax of the service's requests,
or contact the provider of the service.
Note: Additional information regarding the exact syntax error may be provided in the result passed back from the submit call. |
| 8 | Invalid Service Result | This indicates an internal error with the service to which a request was submitted. If this error occurs, report it to the authors and the service provider. |
| 9 | Rexx Error | This indicates an internal error in an external Rexx service. If this error
occurs, report it to the authors and the service provider.
Note: The actual Rexx error code will be returned in the result passed back from the submit call. |
| 10 | Base OS Error | This indicates that a base operating system error was encountered.
Note: The actual base operating system error code, and possibly additional information about the error, will be returned in the result passed back from the submit call. |
| 11 | Process Already Complete | You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification. |
| 12 | Process Not Complete | You are trying to free process information for a process that is still executing. |
| 13 | Variable Does Not Exist | You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call. |
| 14 | UnResolvable String | You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions. |
| 15 | Invalid Resolve String | The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces. |
| 16 | No Path To Endpoint | This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. machine). This error usually indicates that STAF is not running on the target machine, or that the requested endpoint is not valid, or that the network interface or port for the requested endpoint is not supported. Alternatively, you may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg file. |
| 17 | File Open Error | This indicates that there was an error opening the requested file.
Some possible explanations are that the file/path does not exist, contains
invalid characters, or is locked.
Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call. |
| 18 | File Read Error | This indicates that there was an error while trying to read data from a file.
Note: Additional information regarding which file could not be read from may be provided in the result passed back from the submit call. |
| 19 | File Write Error | This indicates that there was an error while trying to write data to a file.
Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call. |
| 20 | File Delete Error | This indicates that there was an error while trying to delete a file or
directory.
Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call. |
| 21 | STAF Not Running | This indicates that STAF is not running on the local machine. Verify that
STAFProc.exe is running.
If STAFProc is running, make sure you are using the correct name for the STAFProc instance you are trying to communicate with. There is a special environment variable, STAF_INSTANCE_NAME, that can be used to specify a name for each STAFProc instance to differentiate between multiple instances of STAF. If this environment variable is not set, the default value, "STAF", is used for the instance name. |
| 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 for which you do not have the required
trust level to perform the request.
Note: Additional information regarding the required trust level may be provided in the result passed back from the submit call. |
| 26 | STAF Registration Error | This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured. |
| 27 | Service Configuration Error | This indicates an error with the configuration of an external service. 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. |
| 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. |
| 53 | Handle Authentication Failed | This indicates that the user, credentials, and/or authenticator you specified
could not be authenticated. The user/credentials may not be valid or the
authenticator may not be registered.
Note: Additional information specifying why authentication was denied may be provided in the result passed back from the submit call. |
| 54 | Handle Already Authenticated | This indicates that the handle is already authenticated. The handle must be unauthenticated in order to be authenticated. |
| 55 | Invalid STAF Version | This indicates that the version of STAF (or the version of a STAF service) is lower than the minimum required version. |
| 56 | Request cancelled | This indicates that the request has been cancelled.
Note: Additional information specifying why the request was cancelled may be provided in the result passed back from the submit call. |
| 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 98. STAF Service Command Reference
| Command | Syntax |
|---|---|
| DELAY | Delay (or sleep) a number of milliseconds.
DELAY <Milliseconds> HELP |
| DIAG | Allows diagnostics to be recorded, listed, enabled, disabled, and reset.
RECORD TRIGGER <Trigger> SOURCE <Source>
LIST < [TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES]
[SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE] > |
SETTINGS
RESET FORCE
ENABLE
DISABLE
HELP
|
| ECHO | Echo a return string from other STAF clients.
ECHO <Message> HELP |
| FS | Allows you to manipulate files and directories.
COPY FILE <Name> [TOFILE <Name> | TODIRECTORY <Name>] [TOMACHINE <Machine>]
[TEXT [FORMAT <Format>]] [FAILIFEXISTS | FAILIFNEW]
COPY DIRECTORY <Name> [TODIRECTORY <Name>] [TOMACHINE <Machine>]
[NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
[TEXTEXT <Pattern>... [FORMAT <Format>]]
[RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]]
[IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
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 [DETAILS]] [RECURSE]
LIST COPYREQUESTS [LONG] [INBOUND] [OUTBOUND]
[FILE [[BINARY] [TEXT]]] [DIRECTORY]
LIST SETTINGS
DELETE ENTRY <Name> [CHILDREN [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
[CASESENSITIVE | CASEINSENSITIVE]] [RECURSE] [IGNOREERRORS] CONFIRM
SET STRICTFSCOPYTRUST <Enabled | Disabled>
HELP
|
| HANDLE | Allows you to query information on various process handles and to manage static handles.
CREATE HANDLE NAME <Handle Name>
DELETE HANDLE <Number>
QUERY HANDLE <Handle>
LIST [HANDLES [NAME <Handle Name>] [PENDING] [REGISTERED] [INPROCESS] [STATIC]]
LIST NOTIFICATIONS [HANDLE <Handle> | MACHINE <Machine>]
AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials>
[AUTHENTICATOR <Authenticator Name>]
UNAUTHENTICATE
HELP
|
| HELP | List and query STAF return codes. Allows services to register their own
return codes.
REGISTER SERVICE <Name> ERROR <Number> INFO <String> DESCRIPTION <String> UNREGISTER SERVICE <Name> ERROR <Number> [SERVICE <Name>] ERROR <Number> LIST SERVICES | [SERVICE <Name>] ERRORS HELP |
| LOG | Allows for robust data-logging and log file querying and manipulation.
LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level>
MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
QUERY <GLOBAL | MACHINE <Machine> [HANDLE <Handle>] LOGNAME <Logname>
[LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
[NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
[CONTAINS <String>]... [CSCONTAINS <String>]...
[STARTSWITH <String>]... [CSSTARTSWITH <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
[FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG]
[LEVELBITSTRING]
LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLE <Handle> | HANDLES] |
SETTINGS
DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]>
LOGNAME <Logname> CONFIRM
PURGE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> CONFIRM
[LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]...
[NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]...
[CONTAINS <String>]... [CSCONTAINS <String>]...
[STARTSWITH <String>]... [CSSTARTSWITH <String>]...
[FROM <Timestamp> | AFTER <Timestamp>]
[BEFORE <Timestamp> | TO <Timestamp>]
[FIRST <Num> | LAST <Num>]
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
[ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
[RESOLVEMESSAGE | NORESOLVEMESSAGE]
VERSION
HELP
|
| MISC | Provides miscellaneous services such as VERSION, WHOAMI, and WHOAREYOU
information, allows for listing and querying enabled interfaces, allows
you to set operational parameters for STAF and show their settings,
and allows you to list and purge the endpoint cache used by automatic
interface cycling.
VERSION
WHOAMI
WHOAREYOU
LIST INTERFACES | SETTINGS | ENDPOINTCACHE
QUERY INTERFACE <Name>
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
[MAXQUEUESIZE <Number>] [INTERFACECYCLING <Enabled | Disabled>]
[DEFAULTINTERFACE <Name>] [DEFAULTAUTHENTICATOR <Name>]
[RESULTCOMPATIBILITYMODE <Verbose | None>]
PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM>
HELP
|
| MONITOR | Allows test cases the ability to log and query status messages.
LOG MESSAGE <Message> [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 [MACHINE <Machine>] HELP |
| PROCESS | Allows you to start, stop, and manage processes.
START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>]
[VAR <Variable>=<Value>] [ENV <Variable>=<Value>] [USEPROCESSVARS]
[WORKLOAD <Name>] [TITLE <Title>] [WAIT [Timeout] | ASYNC]
[STOPUSING <Method>] [STATICHANDLENAME <Name>]
[NEWCONSOLE | SAMECONSOLE] [FOCUS <Background | Foreground | Minimized>]
[USERNAME <User name> [PASSWORD <Password>]]
[DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH]
[STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
[STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
[RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
[NOTIFY ONEND [HANDLE <Handle> | NAME <Name>]
[MACHINE <Machine>] [PRIORITY <Priority>] [KEY <Key>]]
STOP <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
LIST [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG]
LIST SETTINGS
QUERY HANDLE <Handle>>
FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>>
NOTIFY REGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
[MACHINE <Machine>] [PRIORITY <Priority>]
NOTIFY UNREGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
[MACHINE <Machine>] [PRIORITY <Priority>]
NOTIFY LIST ONENDOFHANDLE <Handle>
SET [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>]
[DEFAULTFOCUS <Background | Foreground | Minimized>]
[PROCESSAUTHMODE <Auth Mode>]
[DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>]
[DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>]
[DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
HELP
|
| QUEUE | Allows you to manipulate and manage queues.
QUEUE [HANDLE <Handle>] | [NAME <Name>] [PRIORITY <Priority>] [TYPE <Type>]
MESSAGE <Message>
GET [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[CONTAINS <String>]... [ICONTAINS <String>]...
[WAIT [Timeout]]
PEEK [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[CONTAINS <String>]... [ICONTAINS <String>]...
[WAIT [Timeout]]
DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]...
[HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]...
[CONTAINS <String>]... [ICONTAINS <String>]...
LIST [HANDLE <Handle>]
HELP
|
| RESPOOL | Allows you to manage exclusive access to entries within resource pools.
CREATE POOL <PoolName> DESCRIPTION <Pooltext> DELETE POOL <PoolName> CONFIRM [FORCE] QUERY POOL <PoolName> REQUEST POOL <PoolName> [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 [POOLS | SETTINGS] VERSION HELP |
| SEM | Allows you to manipulate and manage mutex and event semephores.
REQUEST MUTEX <Name> [TIMEOUT <Timeout>] RELEASE MUTEX <Name> [FORCE] POST EVENT <Name> RESET EVENT <Name> PULSE EVENT <Name> WAIT EVENT <Name> DELETE MUTEX <Name> | EVENT <Name> QUERY MUTEX <Name> | EVENT <Name> LIST MUTEX <Name> | EVENT <Name> HELP |
| SERVICE | Allows you to manage STAF services and requests.
LIST [SERVICES | SERVICELOADERS | AUTHENTICATORS |
REQUESTS [PENDING] [COMPLETE] [LONG]]
QUERY SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> |
AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number>
ADD SERVICE <Service Name> LIBRARY <Library Name>
[EXECUTE <Executable>] [OPTION <Name=[=Value]>]...
[PARMS <Parameters>]
REMOVE SERVICE <Service Name>
FREE REQUEST <Request Number> [FORCE]
HELP
|
| SHUTDOWN | Allows you to manage the STAFProc daemon process.
SHUTDOWN
NOTIFY REGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
[PRIORITY <Priority>]
NOTIFY UNREGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
[PRIORITY <Priority>]
NOTIFY LIST
HELP
|
| TRACE | Allows you to turn tracing on and off at the service and tracepoint level.
ENABLE ALL [ TRACEPOINTS | SERVICES ] ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... ENABLE SERVICE <Service> [SERVICE <Service>]... DISABLE ALL [ TRACEPOINTS | SERVICES ] DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... DISABLE SERVICE <Service> [SERVICE <Service>]... SET DESTINATION TO < STDOUT | STDERR | FILE <File name> > SET DEFAULTSERVICESTATE < Enabled | Disabled > LIST [SETTINGS] PURGE HELP |
| TRUST | Allows you to manipulate and manage trust levels (security).
SET < MACHINE <Machine> | USER <User> | DEFAULT > LEVEL <Level> GET MACHINE <Machine> [USER <User>] DELETE MACHINE <Machine> | USER <User> LIST HELP |
| VAR | Allows you to manipulate and manage system, shared and process specific variable pools.
SET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name=Value> [VAR <Name=Value>]... GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]... LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] STRING <String> [STRING <String>]... HELP |
| ZIP | Allows for unzipping, listing, and adding/deleting entries in Zip archives which are
PKZip, WinZip and Jar compatible.
UNZIP ZIPFILE <Name> TODIRECTORY <Name>
[FILE <Name>]... [RESTOREPERMISSION] [REPLACE]
ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
[RELATIVETO <Directory>]
DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
LIST ZIPFILE <Name>
VERSION
HELP
|
| Name | Description | Comments |
|---|---|---|
| D.1.1, "Java Sample 1" | Java Ping Sample | This sample uses the STAF Ping command to ping a STAF client and measure the throughput. |
| D.2.1, "Rexx Sample 1" | Rexx Synchronous Process Sample | This sample loads the STAF Functions, registers to STAF, queries a system variable from STAF, 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 system variable, inititates an asynchronous PMSEEK process, list variables, queries process status, stops PMSEEK, queries process status again, frees the process, queries the system variable previously set, then unregisters. |
| D.2.3, "Rexx Sample 3" | Rexx Monitor Sample | This sample loads STAF Functions, registers to STAF, writes a monitor message and then queries it, this is done 10 times, then it unregisters. The size of the monitor messages written is based on a random number generated. |
| D.2.4, "Rexx Sample 4" | Rexx Log Sample | This sample loads STAF Functions, registers to STAF, writes and queries 10 log messages to a global log called LOGTEST, then unregisters. The size of the log messages written is based on a random number generated. |
| D.2.5, "Rexx Sample 5" | Rexx Ping Sample | This sample uses the STAF Ping command to ping a STAF client and measure the throughput. |
| D.3.1, "C Sample 1" | C Log Sample | This sample logs a message via the STAF LOG service. |
| D.4.1, "C++ Sample 1" | C++ Log Sample | This sample logs a message via the STAF LOG service. |
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the 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/MachineNickname}")
if STAFRC = 0 then machine = STAFResult
else
do
say "Unable to determine machine nickname!"
call STAFUnRegister
RETURN STAFRC
end
service = "monitor"
times = 10
wait = 0
string = "Software Testing Automation Framework (STAF) (C) Copyright IBM Corp.",
"1998 All Rights Reserved"
do times
message = substr(string,1,1 + random(99))
msglen = length(message)
data = "LOG MESSAGE :"msglen":"message
STAFRC = STAFSubmit("local", service, data)
if STAFRC \= 0 then
say "Monitor Log Error: " STAFRC STAFResult
data = "query machine" machine "handle" STAFHandle
STAFRC = STAFSubmit("local", service, data)
if STAFRC = 0 then
say STAFResult
else
say "Monitor Query Error: " STAFRC STAFResult
end
/* Unregister */
call STAFUnRegister
RETURN 0
/*********************************************************************/
/* STAFAbort - If user aborts, make sure STAF unregister occurs. */
/*********************************************************************/
STAFAbort:
call STAFUnRegister
EXIT 1
/*****************************************************************************/
/* Software Testing Automation Framework (STAF) */
/* (C) Copyright IBM Corp. 2001 */
/* */
/* This software is licensed under the 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);
}