markdown:
**Software Testing Automation Framework (STAF) User's Guide**
**Version 3.4.22**
25 Jun 2015
[Appendix B. Service Command Reference](#HDRCMDREF)
[Appendix C. Samples Descriptions](#HDRSAMPREF)
[Appendix D. Code Samples and Snipets](#HDRCODE)
As its name indicates, STAF is a framework. It was designed to promote reuse and extensibility. It is intended to make software testing easier, and specifically to make it easier to automate software testing. This includes creating automated testcases, managing and automating the test environment, creating execution harnesses (i.e., applications which schedule and/or execute work on test systems), etc.
STAF externalizes its capabilities through services. A service provides a focused set of functionality, such as, Logging, Process Invocation, etc. STAFProc is the process that runs on a machine, called a STAF Client, which accepts requests and routes them to the appropriate service. These requests may come from the local machine or from another STAF Client. Thus, STAF works in a peer environment, where machines may make requests of services on other machines.
STAF was designed with the following points in mind.
STAF is supported on the following operating systems
A handle is a unique identifier, representing a given process. This handle is used when submitting requests to STAF. This handle, combined with the machine name, uniquely identifies a particular process in the STAF Environment. It is this combination of machine/handle that allows services to track requests from multiple processes on different machines.
In order to submit service requests to STAF, a process must have a handle. Thus, the first thing a process should do is register with STAF to obtain a handle. Other data tied to this handle is the following:
Before a process exits it should unregister with STAF to free up any resources used by that handle.
**Note: **Handle 1 is always allocated to the STAF Process itself. The name
associated with this handle is STAF_Process.
If STAFProc is shutdown on a machine (or the machine is rebooted), STAF handles for that machine are deleted.
The SEM and RESPOOL services perform garbage collection for handles that have
been deleted by default, unless you specified no garbage collection when
requesting a mutex semaphore or resource pool entry. Performing garbage
collection means that when a handle is deleted, any mutex semaphores or
resource pool entries owned by the handle will be released and any pending
requests submitted by the handle will be removed.
Services are what provide all the capability in STAF. Services may be internal services, in which case, the executable code for the service resides within STAFProc. Services may also be external services, in which case, the executable code for the service resides outside of STAFProc, for example, in a Java routine.
Services are known by their name, such as PROCESS or LOG. Internal services are always available and have a fixed name. External services must be registered, and the name by which they are known is specified when they are registered. If an external service is not registered with STAF, then the service is not available on that STAF Client.
Services may also be delegated to another STAF Client. In this case, when a request is made for the service on the local STAF Client, it is automatically forwarded to the machine to which this service has been delegated. For example, a testcase may request the local machine to log some information via the LOG service. If the LOG service has been delegated to another machine, the LOG request will actually be handled by the machine to which logging has been delegated. In this way, all logs could be conveniently stored on one system, without the testcases needing to explicitly send their LOG requests to the common system. In a similar manner, if a service were only available on a specific operating system, then all testcases could assume that the service was available locally, when, in fact, the service was being delegated to the machine running the required operating system.
**Note: **Internal services may not be delegated.
External services and delegated services are both registered in the STAF
Configuration File. External services also may be dynamically added (registered)
or removed (unregistered and terminated)
via the SERVICE service (see
[8.17, "Service Service"](#HDRSRVSERVICE)).
Service loaders are external services whose purpose is to load services on-demand. They allow services to be loaded only when they have been requested, so they don't take up memory until needed. They also allow dynamic service registration when a request is made so that you don't have to change the STAF configuration file to register a service.
When a request is encountered for a service that doesn't exist, STAF will call each service loader, in the order they were configured, until the service exists or we run out of service loaders. If we run out of service loaders, then the standard RC 2 (DoesNotExist) will be returned indicating that the service is not registered. Otherwise, the request will be sent to the newly added service. If a service is currently being attempted to be loaded by a service loader, any requests submitted to the service while it's being loaded will wait until the attempt to load the service has completed. If the service was loaded, the request will be sent to the newly added service. If the service wasn't loaded, RC 2 (DoesNotExist) will be returned indicating that the service is not registered.
STAF ships two service loader services:
Authenticators are special external services whose purpose is to authenticate users in order to provide user level trust, which can be used in addition (or instead of) machine level trust. An Authenticator is a special service that accepts an authenticate request. As a user, you cannot directly submit a request to an authenticator service. Authenticators are accessed indirectly via the Handle service.
Authenticators can only be registered in the STAF configuration file --
they cannot be dynamically registered. One or more Authenticators can be
registered. The first Authenticator registered is the default, unless
overridden by using the DEFAULTAUTHENTICATOR operational parameter.
If you want to authenticate across systems, you must register the
Authenticator on each system using the same name (case-insensitive).
A workload is a set of processes running on a set of machines. A workload
may be as simple as a single process running on a single machine, or it may be
as complex as multiple processes on multiple machines coordinating together to
perform a larger complex task. STAF was designed to help the creation and
automation of workloads of all sizes.
STAF provides a means to store and retrieve variables. These variables may be used for any purpose the tester desires, such as storing testcase configuration parameters. These variables provide two main capabilities to testcase writers. One, they provide a standard means by which to store configuration data, i.e., each tester doesn't have to figure out how to store and retrieve said configuration data. Two, these variables may be changed dynamically. For example, if a testcase queries the WebServer variable before sending a request off to the web server, and that web server goes down, the WebServer variable can be dynamically changed by the tester to refer to a different web server, and the testcase can continue execution. Note how STAF allows the variable's value to be changed outside of the scope of the running testcase, thus allowing the testcase to continue execution without needing to be stopped and restarted.
STAF maintains a "system" variable pool that is common to all
the processes on a given STAF Client.
STAF also maintains a "shared" variable pool which is also system-wide,
but which will be sent across the network and used in variable resolution
on remote systems.
In addition, each process/handle has its own variable pool.
By default, the values of variables in a process' variable pool override the
values of variables in the system and shared variable pools. However, the
process may override this behavior when asking for the value of a variable.
Basically, as part of every remote request, the originating handle and system
shared variable pools are sent across the wire. These pools are stored only for
the duration of the request for use in variable resolution.
The following system variables are predefined:
To substitute a variable's value, write the name of the variable in curly braces: "{STAF/Config/OS/Name}" is a valid reference to the variable STAF/Config/OS/Name. Assuming STAF/Config/OS/Name=Win2000, string "Operating system is {STAF/Config/OS/Name}" resolves to "Operating system is Win2000".
Variable references can be used in many places when submitting a STAF request. For example:
See section
[8.21, "Variable (VAR) Service"](#HDRVARSERVICE) for more information on setting and resolving
variables.
Security in STAF can be defined at the machine level and/or the user level.
In other words, you grant access to machines and/or to userids.
Access in STAF is granted by specifying a certain trust level for a machine or
user, where trust level 0 indicates no access and trust level 5 indicates all access.
Each service in STAF defines what trust level is required in order to use the various
functions the service provides.
A basic description of each level follows
In order to use user trust security in STAF, you must have at least one authenticator registered.
**Note: **The local machine can be granted a trust level by specifying
interface "local" and a system identifier of "local".
User authentication overrides machine authentication. For example,
if the machine trust level is 3 and the authenticated user has a trust
level of 4, then the handle will have a trust level of 4.
If the user has been authenticated, but there are no user authentication
trust matches, the machine trust level is used. If there is no machine
trust level specified, then the default trust level is used.
Each handle in STAF has a priority queue associated with it. This queue is used to accept/retrieve messages from other processes/machines. Each message in the queue has the following data associated with it.
STAF allows you to register to receive notifications for certain events,
such as STAF starting and shutting down. These events will appear in the
queue of the requesting process. They will reveal the originating handle as
handle 1 of the originating machine, which is the reserved STAF Process handle.
The requests submitted to STAF and the results received from STAF are all strings. These strings may contain any arbitrary set of characters, including the NULL (i.e., 0) character. When working in an environment with a heterogeneous set of codepages, STAF will translate the request and result strings from and to the necessary codepages. This ensures that the request and result strings are not misinterpreted by the receiver.
In general, when using STAF services, there shouldn't be any round trip problems. "Round trip" in this context means when all requests are originating from the same system, even if the requests are sent to, and the data is stored on, a system with a different codepage. However, if you send, for example, a request to log data containing Japanese codepage specific characters to any system and then query the log from a system using a US English codepage, you won't get the "correct" data, as that is not a valid "round trip".
**Note: **All STAF generated strings are composed of only ASCII-7 characters and
will safely survive the translation from/to different codepages.
If you need to specify non-ASCII characters in a request, then you need to be aware of some anomalies if your target system is a Windows system that isn't using an English codepage and whose ANSI codepage (ACP) identifier is different from the OEM codepage (OEMCP) identifier. The system locale determines which codepages are defaults for the Windows system. However, some European locales such as French and German set different values for the ACP and OEMCP. By default, STAF uses the OEM codepage when doing codepage translation. But, depending on where the data is input, it may be necessary to tell STAF to use the ANSI codepage. The ANSI codepage is used in the window manager and graphics device interface and by many applications. However, the Windows command line and bat files use the OEM codepage as they are interpreted by cmd.exe. You can use CHCP to display or change the codepage used by the command line. Note that these anomalies occur only on Windows systems.
To avoid these Windows codepage anomalies, you may need to change the codepage used by STAF using one of these methods:
**Caution: **You should NOT change the ACP value to the OEMCP value.
**Note: **To see the codepage that STAF is using, check the value of
STAF variable STAF/Config/CodePage. For example:
STAF testmach1 VAR RESOLVE STRING {STAF/Config/CodePage}
On a GET FILE request to the FS service (or on another service request that submits a GET FILE request to the FS service like the STAX service does on an EXECUTE FILE request), RC 39 (Converter Error) is returned if the file contains data that is not valid in the codepage that STAF is using. To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage as discussed in the previous section.
To resolve an RC 39 (Converter Error) on a GET FILE request to the FS service, either:
The STAF Installation Guide (http://staf.sourceforge.net/current/STAFInstall.pdf) has detailed information on how to install STAF.
STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF Configuration File is read and processed line by line. Whitespace at the front of the line is removed before processing. Blank lines, or lines containing only whitespace are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line. The maximum length for a line in the STAF Configuration File is 2048 characters. The various configuration statements are described in the following sections.
You may use variables for all the values of configuration statement options,
with the exception of the
`SET VAR` configuration statement itself.
However, these variables must be either predefined STAF variables (see
[2.4, "Variables"](#HDRVARCON)) or be previously defined in the STAF Configuration File
via the `SET VAR` configuration statement (see below).
You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.
# This is a comment line
You may specify a nickname for your machine using the MACHINENICKNAME configuration statement.
This allows you to override the machine nickname which is set to the value of the STAF/Config/Machine system variable by default. This primarily affects the data stored by services such as the Log and Monitor services, which store data based on the machine from which it came by using the STAF/Config/MachineNickname system variable as part of the directory path when creating logs and monitor data. By allowing the STAF/Config/MachineNickname system variable to be overridden, it allows you to better manage your data.
The machine nickname is not used to communicate with other systems and does not have any effect on trust.
This option is used in both connected and disconnected modes (e.g. disconnected mode is when you are not using a network interface).
MACHINENICKNAME <Nickname>
`<Nickname>` is the nickname you wish to use for your machine. It is
case sensitive.
MACHINENICKNAME testmachine1 MACHINENICKNAME JohnDoe
You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement. The INTERFACE configuration statement registers connection providers (also called network interfaces, or interfaces for short).
INTERFACE <Name> LIBRARY <Implementation Library> [OPTION <Name[=value]>]...
`<Name>` is the name by which this network interface
(aka Connection Provider) will be known on this machine.
`LIBRARY` is the name of the shared library / DLL
which implements the network interface (aka Connection Provider).
STAF provides one implementation library called STAFTCP which
provides support for both secure and non-secure TCP/IP communcation.
`OPTION` specifies a configuration option that will be passed on
to the shared library / DLL which implements the connection provider.
You may specify multiple `OPTION`s for a given connection provider.
See [4.3.2, "STAFTCP Connection Provider"](#HDRSTAFTCP) for acceptable options for the STAFTCP shared
library / DLL.
INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550 INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500 INTERFACE tcp2 LIBRARY STAFTCP INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6600 INTERFACE serial LIBRARY STAFSER
The STAFTCP connection provider shared library / DLL supports TCP/IP communication. STAF supports both secure and non-secure TCP/IP communication on most platforms. STAF supports both IPv4 and IPv6. IPv6 is supported in the IPv6 enabled version of STAF.
Each STAFTCP connection provider configured on a single machine must use a unique port number. To communicate to a remote machine running STAF, your machine and the remote machine must both have a STAFTCP connection provider configured with the same SECURE option value and the same PORT option value. A non-secure STAFTCP connection provider cannot communicate to a secure STAFTCP connection provider. Also, a secure TCP connection provider can only communicate to another secure TCP connection provider if the same certificate is used.
The STAFTCP connection provider supports the following
`OPTIONs`:
`CONNECTTIMEOUT=<Number>` specifies the maximum time in milliseconds to wait
for a connection attempt to a remote system to succeed. The default is 5000
(5 seconds). You may need to increase this value if you are consistently
receiving return code 16 when trying to communicate with distant STAF systems.
Note that the total time to wait for a connection to a remote system to succeed
is `(CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1))`.
If using the defaults, the maximum total time to wait for a connection to a remote
system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds.
The `CONNECTATTEMPTS` and `CONNECTRETRYDELAY` values are operational
parameters that can be set in the STAF configuration file.
`PORT=<Number>` specifies the TCP/IP port on which this
connection provider listens for connections.
The default port is 6550 if option `SECURE=Yes`.
The default port is 6500 if option `SECURE=No`.
Each STAFTCP connection provider configured on a single machine
must use a unique port number.
`PROTOCOL=<IPv4 | IPv6 | IPv4_IPv6>` specifies the communication protocol that this
connection provider uses. The possible values are `IPv4`, `IPv6`,
or `IPv4_IPv6`. When this option is absent, the default is `IPv4_IPv6`
which indicates to use both IPv4 and IPv6 protocols.
This option is only valid for IPv6 enabled versions of STAF.
`SECURE=<Yes | No>` specifies whether to use secure or
non-secure TCP/IP. Secure TCP/IP uses OpenSSL. This option is
not available on z/OS where only non-secure TCP/IP is currently supported.
The default is No.
`SSL/CACertificate` specifies the fully qualified path to the
file containing the STAF CA certificate list used for secure connections.
This option is only valid if option `SECURE=Yes` is specified.
The default is {STAF/Config/STAFRoot}/bin/CAList.crt which is a list
of the default server certificate provided with STAF.
`SSL/ServerCertificate` specifies the fully qualified path to
the file containing the STAF server certificate used for secure connections.
This option is only valid if option `SECURE=Yes` is specified.
The default is {STAF/Config/STAFRoot}/bin/STAFDefault.crt which is a
self-signed x509 default certificate provided with STAF.
`SSL/ServerKey` specifies the fully qualifed path to the file
containing the STAF server key used for secure connections.
This option is only valid if option `SECURE=Yes` is specified.
The default is {STAF/Config/STAFRoot}/bin/STAFDefault.key which is a
default server key provided with STAF.
INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550 INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500 INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6501 INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6700 OPTION PROTOCOL=IPv6 INTERFACE tcp4 LIBRARY STAFTCP OPTION CONNECTTIMEOUT=15000 INTERFACE ssl2 LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6551 \ OPTION SSL/CACertificate={STAF/Config/STAFRoot}/bin/MyCAList.crt \ OPTION SSL/ServerCertificate={STAF/Config/STAFRoot}/bin/MySTAF.crt \ OPTION SSL/ServerKey={STAF/Config/STAFRoot}/bin/MySTAF.key
External services are registered with the SERVICE configuration statement.
SERVICE <Name> LIBRARY <Implementation library> [EXECUTE <Executable>] [OPTION <Name[=Value]>]... [PARMS <Parameters>]
or
SERVICE <Name> DELEGATE <Machine> [TONAME <Remote Service Name>]
`<Name>` is the name by which this service will be known on this
machine.
`LIBRARY` is the name of the shared library / DLL
which implements the service or acts as a proxy for the service. See the
information for each external service to determine the appropriate value
for this option.
`EXECUTE` is used by service proxy libraries / DLLs to specify what
the proxy library should execute. For example, for a Java service, this might
be the name of the Java jar file which actually implements the service. This
option has no significance for non-proxy service libraries. See below for
information regarding the JSTAF service proxy library.
Otherwise, see the documentation provided by the service proxy library.
`OPTION` specifies a configuration option that will be passed on
to the service library / DLL. This is typically used by service proxy
libraries to further control the interface to the actual service
implementation. You may specify multiple `OPTION`s for a given
service. See below for acceptable options for the JSTAF
service proxy library. Otherwise, see the documentation provided with the
service (proxy) library.
`PARMS` specifies optional parameters that will be passed to the
service during initialization.
`DELEGATE` specifies the machine to which to delegate this service.
This machine must be running STAF V3.0.0 or later.
**Note: **From a trust perspective, the tcp interface names on the "delegated to"
service machine and on the machine delegating service requests to it must match
or the trust statement for the machine that is delegating service requests
must use a wildcard to match any interface.
`TONAME` is the name of the service on `<Machine>` to
which the delegated requests will be sent. The default is the same name as
specified with `<Name>`.
SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096" SERVICE LOG LIBRARY STAFLog SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\service\STAX.jar \ OPTION J2=-Xmx128m SERVICE SAMPLEJ LIBRARY JSTAF EXECUTE C:\STAF\services\Sample.jar \ PARMS {STAF/Config/STAFRoot}\bin\sample.dft SERVICE MYLOG DELEGATE TestSrv1 SERVICE PAGER DELEGATE pagesrv.austin.ibm.com SERVICE EVENT DELEGATE EventSrv TONAME DB2EVENT SERVICE NOTIFY LIBRARY Notify PARMS "24 Hours 7 Days" SERVICE ZIP LIBRARY STAFEXECPROXY EXECUTE STAFZip
The library JSTAF acts as a proxy for STAF services implemented in the Java language. The minimum version of Java that JSTAF requires depends on the operating system for which STAF was built:
**Note: **JSTAF in a 32-bit version of STAF requires a 32-bit version of Java.
Similarly, JSTAF in a 64-bit version of STAF requires a 64-bit version of Java.
The
`EXECUTE` option for a Java service should specify the
fully-qualified name of the jar file that implements the service. The
jar file will be automatically added to the class path by JSTAF.
**Note: **In versions of STAF prior to 2.4.0, the name of the Java class that
implements the service was specified for the `EXECUTE` option and
you had to make sure that the service's class files were in the class path.
This is still supported, but this method is deprecated and will be removed
in a future version of STAF.
JSTAF supports the following
`OPTION`s:
`JVMName=<Name>` specifies the name for the JVM you want the Java
service to run in. If the JVM does not already exist, it will be created.
If no JVMName is specified, then the Java service will run in the default JVM,
named STAFJVM1, which is created the first time a Java service is registered
with no JVMName specified.
This option allows JSTAF to run Java services in different JVMs.
`JVM=<Executable>` specifies the name of the desired Java
executable. The default is "java". Note, this option is only valid for the
first service created with a given `JVMName`.
`J2=<Java option>` specifies one or more arbitrary Java option(s)
that should be passed to the JVM. You can find more information on these
options by using the command "java" (for standard options) and "java -X"
(for non-standard options), or by consulting your Java documentation.
Note that -X options can vary depending on which Java implementation
(e.g. Oracle Java 7 vs IBM Java 6) you installed. Note, this option
is only valid for the first service created with a given `JVMName`.
**Note: **If you are using the HP-UX IA64 64-bit version of STAF, you must specify
the -d64 option to the JVM. This can be done by specifying `J2=-d64`
`MAXLOGS=<Number>` specifies the maximum number of log files
for the JVM that should be saved. The default is 5.
The JVM log files are stored in the `{STAF/DataDir}/lang/java/jvm/<JVMName>`
directory and contain JVM start information such as the date/time when the JVM
was started, the JVM executable, and the J2 options used to start the JVM.
In addition, it contains any other information logged by the JVM, including any
errors that may have occurred while the JVM was running.
The current JVM log file is named `JVMLog.1` and saved JVM log files, if any,
are named `JVMLog.2` to `JVMLog.<MAXLOGS>`.
Note, this option is only valid for the first service created with a
given `JVMName`.
`MAXLOGSIZE=<Number>` specifies the maximum size, in bytes, for
the JVM log file(s). The default is 1048576 (1M).
This option determines when to create a new JVM log file. When the JVM is
started, if the size of a JVM log file exceeds the maximum size specified
by this option, a new JVM log file will be created.
Note, this option is only valid for the first service created with a
given `JVMName`.
**Note: **You can view the JVM log for a Java service that is currently
registered using the STAFJVMLogViewer utility.
Section [9.2, "JVM Log Viewer Class"](#HDRSTAFJVMLOGVIEWER) provides more information on this utility.
OPTION J2=-verbose:gc OPTION "J2=-cp {STAF/Config/BootDrive}/MyJava/Extra.jar{STAF/Config/Sep/Path}{STAF/Env/Classpath}" OPTION J2=-Xms128m OPTION J2=-Xmx512m OPTION J2=-d64 OPTION "J2=-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=256m" OPTION JVMName=MyJVM1 OPTION JVM=/opt/sunjdk1.4.0/jre/bin/java OPTION MAXLOGS=2 OPTION MAXLOGSIZE=2048
If you wanted to run the STAX Java service in a JVM, called MyJVM1, with a maximum heap size of 1024M, and wanted the Event and EventManager Java services to run in a different JVM, called MyJVM2, with a maximum heap size of 512M, you could specify the following service registration lines in the STAF.cfg file (or dynamically register the services in this order using the specified options).
SERVICE STAX LIBRARY JSTAF EXECUTE C:/STAF/service/STAX.jar \ OPTION JVMName=MyJVM1 OPTION J2=-Xmx1024m SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/service/STAFEvent.jar \ OPTION JVMName=MyJVM2 OPTION J2=-Xmx512m SERVICE EventManager LIBRARY JSTAF EXECUTE C:/STAF/services/EventManager.jar \ OPTION JVMName=MyJVM2
The library PLSTAF acts as a proxy for STAF services implemented in the Perl language. PLSTAF is currently supported on Windows (IA32), Linux (IA32), and Mac OS X. On Linux IA32, PLSTAF is currently only supported with Perl 5.8.0.
The
`EXECUTE` option for a Perl service should specify the name of
the .pm file (without the .pm extension) that implements the service.
PLSTAF supports the following
`OPTION`s:
`USELIB=<Directory>` specifies the directory containing the .pm file
that implements the service. You must use the USELIB option unless you have
set (prior to starting STAFProc) environment variable PERLLIB to include the
directory containing the .pm file that implements the service.
`MAXLOGS=<Number>` specifies the maximum number of log files
for the Perl interpreter that should be saved. The default is 5.
The Perl interpreter log files are stored in the
`{STAF/DataDir}/lang/perl/<serviceName>`
directory and contain the Perl interpreter start information such as the
date/time when the Perl interpreter was started and the Perl service
executable. In addition, it contains any other information logged by the Perl
service and interpreter, including any errors that may have occurred while the
Perl interpreter was running.
The current Perl interpreter log file is named `PerlInterpreter.1`
and saved Perl interpreter log files, if any,
are named `PerlInterpreter.2` to `PerlInterpreter.<MAXLOGS>`.
`MAXLOGSIZE=<Number>` specifies the maximum size, in bytes, for
the Perl interpreter log file(s). The default is 1048576 (1M).
This option determines when to create a new Perl interpreter log file. When the
Perl interpreter is started, if the size of a Perl interpreter log file exceeds
the maximum size specified by this option, a new Perl interpreter log file will
be created.
**Note: **The PLSTAF service proxy library uses embedded Perl directly within the
STAFProc executable. This means that if a Perl service has a fatal error which
terminates the Perl interpreter, the STAFProc executable will also be terminated.
To prevent this, you can use the STAFEXECPROXY service proxy library when
registering a Perl service.
**Note: **To configure Perl services, prior to starting STAFProc, environment
variable PERLLIB must be set to include the directory containing the PLSTAF.pm
and PLSTAFService.pm files (located in the "bin" directory in the STAF
installation root directory).
**Note: **To configure Perl services, the directory containing the PLSTAF library
(PLSTAF.dll on Windows, libPLSTAF.so on Linux, libPLSTAF.dylib on Mac OS X)
must be in the operating system's library path (PATH on Windows, LD_LIBRARY_PATH
on Linux, DYLD_LIBRARY_PATH on Mac OS X) prior to starting STAFProc.
**Note: **When configuring Perl services on Linux with Perl 5.8.0, the directory
containing the Perl 5.8.0 libperl.so file must be included in environment
variable LD_LIBRARY_PATH prior to starting STAFProc.
**Note: **When removing a Perl service (or when shutting down STAF if Perl
services had been configured), you may see a message in the STAFProc output
similar to: "Perl exited with active threads". This message can be ignored.
SERVICE Device1 LIBRARY PLSTAF EXECUTE DeviceService SERVICE Device2 LIBRARY STAFEXECPROXY EXECUTE DeviceService \ OPTION PROXYLIBRARY=PLSTAF SERVICE testA LIBRARY STAFEXECPROXY EXECUTE myTestService \ OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=C:\MyServices
This library will allow you to execute an external STAF service within a new executable, rather than directly within the STAFProc executable. For example, this library could be used to run the Zip service in a separate executable, or run a Perl service where the Perl interpreter will run in a separate executable.
Running an external STAF service in a separate executable will ensure that if the service has a fatal error, the error will not kill STAFProc. In addition, this allows monitoring of the external service's system resource utilization, since you can view the utilization for the new executable (otherwise, if the service was running within the STAFProc executable, then the service's resource utilization would be part of the STAFProc resource utilization).
Note that using the STAFEXECPROXY library will introduce a level of IPC communication for all service requests to the service; rather than STAFProc sending the requests directly to the service, STAFProc will send the request to the STAFEXECPROXY library, which will then send the request to the new executable, which will then send the request to the service (processing the service result will have the same path in reverse). So, for external STAF services where performance is critical, such as the Log and Monitor services, using the STAFEXECPROXY library is not recommended.
Note that since the JSTAF proxy library already runs the Java STAF service in a new executable (the JVM), using the STAFEXECPROXY library for Java STAF services is not supported (if you attempt to register a Java STAF service using the STAFEXECPROXY library, you will get an RC 27, Service configuration error).
The
`EXECUTE` option is used to indicate the service library to
execute, or if the
service will be executed by a proxy library, it will be used to indicate
what service executable the proxy library should execute. For example,
for the Zip service, "STAFZip" would be used for the EXECUTE value. For a
Perl service, which uses the PLSTAF proxy library, the service .pm module
would be used for the EXECUTE value.
STAFEXECPROXY supports the following
`OPTION`s
[OPTION PROXYLIBRARY=<ProxyLibrary>] [OPTION PROXYENV=<Variable=Value>]...(note that all other
`OPTION PROXYLIBRARY=<ProxyLibrary>` is used to indicate the proxy
library to use for the
external service. For example, you would use OPTION PROXYLIBRARY=PLSTAF
for a Perl service. Note that this OPTION will not be passed on to the
service library / DLL.
`OPTION PROXYENV=<Variable=Value>` allows you to specify
environment variables that will be set for the STAFEXECPROXY executable (in
addition to or replacing the environment variables that were set when STAFProc
was started). This allows you to set environment variables for the
STAFEXECPROXY executable without requiring that these environment variables be
set for STAFProc.
This option is particularly useful for Perl STAF services, which on many
Unix platforms require LD_PRELOAD to be set to the libperl library file
location. However, setting LD_PRELOAD prior to starting STAFProc can
cause incompatibility issues for processes started via STAFProc.
So, you can use OPTION PROXYENV to specify the LD_PRELOAD environment
variable for the STAFEXECPROXY executable, without having it set for STAFProc's
environment. To "unset" an environment variable, you can set the <Value> to
be blank. You may specify any number of PROXYENV OPTIONs.
STAFExecProxy.exe (STAFExecProxy on Unix) is the separate executable for the external service that will be displayed in the operating system's process list. You can determine the PID for the STAFExecProxy executable by running "HANDLE LIST HANDLES LONG".
You may only run a single external service within a single STAFExecProxy executable (multiple services that use the STAFEXECPROXY library will each have a unique STAFExecProxy executable).
SERVICE Zip LIBRARY STAFEXECPROXY EXECUTE STAFZip
SERVICE Device LIBRARY STAFEXECPROXY EXECUTE DeviceService \ OPTION PROXYLIBRARY=PLSTAF
SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \ GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \ OPTION PROXYENV=LD_PRELOAD=/usr/lib/perl5/5.8.8/i386-linux-thread-multi/CORE/libperl.so \ OPTION PROXYENV=TESTVAR=abcdef
SERVICE getenvvar LIBRARY STAFEXECPROXY EXECUTE \ GetEnvVar OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=/usr/local/staf/services \ OPTION PROXYENV=LD_PRELOAD=/opt/ActivePerl-5.8/lib/CORE/libperl.so \ OPTION PROXYENV=ANT_HOME= \ OPTION "PROXYENV=MESSAGE=This is a test message"
Service loaders are registered with the SERVICELOADER configuration statement.
SERVICELOADER LIBRARY <Implementation library> [EXECUTE <Executable>] [OPTION <Name[=Value]>]... [PARMS <Parameters>]
`LIBRARY` is the name of the shared library / DLL
which implements the service loader or acts as a proxy for the service loader. See the
information for each service loader to determine the appropriate value
for this option.
`EXECUTE` is used by service proxy libraries / DLLs to specify what
the proxy library should execute. For example, this might be the name of
the Java jar file which actually implements the service loader. This
option has no significance for non-proxy service libraries. See the Service Registration
section for information regarding the JSTAF service proxy library.
`OPTION` specifes a configuration option that will be passed on
to the service loader library / DLL. This is typically used by service proxy
libraries to further control the interface to the actual service loader
implementation. You may specify multiple `OPTION`s for a given
service loader. See the Service Registration section
for acceptable options for the JSTAF
service proxy library. Otherwise, see the documentation provided with the
service (proxy) library.
`PARMS` specifies optional parameters that will be passed to the
service loader during initialization.
# Default Service Loader Service for LOG, MONITOR, RESPOOL, and ZIP services SERVICELOADER LIBRARY STAFDSLS # HTTP Service Loader Service for Java services (for Windows) SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/bin/STAFHTTPSLS.jar \ PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg" # HTTP Service Loader Service for Java services (for Unix) SERVICELOADER LIBRARY JSTAF EXECUTE /usr/local/staf/lib/STAFHTTPSLS.jar \ PARMS "CONFIGFILE http://server1.company.com/project/stafhttpsls.cfg" # Custom Service Loader Service written in Java SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/services/CustomServiceLoader.jar
The default service loader service is implemented by library STAFDSLS and is written in C++. It can dynamically load the Log, Zip, Monitor, and ResPool C++ services. This service loader is configured automatically in the default STAF.cfg file as follows:
# Add default service loader serviceloader library STAFDSLS
The HTTP service loader service is implemented by jar file STAFHTTPSLS.jar
and is written in Java and is installed as part of STAF Java support in a typical
installation of STAF. It can dynamically load any STAF service written in Java.
It can download the jar file for a STAF Java service (or a zip file that contains
the jar file) from a web server or from a file on the local machine. It uses a
configuration file to determine what services it can load. To use the HTTP
service loader service, a Java runtime must be installed and you must add a
`SERVICELOADER` configuration statement to the STAF configuration file
including a `CONFIGFILE` parameter specifying the location of the
HTTPSLS configuration file you created for it.
When STAF encounters a request for a service that isn't currently registered,
it checks each service loader that is registered in the STAF configuration file
to see if it handles this service. The HTTP service loader service reads its
HTTPSLS configuration file (first downloading it from a web server if needed)
to see if it can handle this service. If so, it downloads the service from the
specified location to a temporary directory on the local machine (and unzips it
if necessary to access the STAF service jar file) and submits an
`ADD`
request to the `SERVICE` service to register the service. This way,
STAF is able to load whatever Java services you want. Also, note that each
time the HTTP service loader service attempts to load a service, it reads its
HTTPSLS configuration file, so you can update the HTTPSLS configuration file
and it will read it the next time it attempts to load a service (without
restarting STAFProc). Note that whenever STAF is restarted, the `tmp`
directory in the STAF data directory is deleted which means the temporary jar
files that the HTTP service loader service downloaded will be deleted since
they are stored in the STAF `tmp` data directory's
`service/<Serviceloader Name>` sub-directory.
The HTTP service loader service can reduce the maintenance for obtaining and managing STAF Java services by:
SERVICELOADER LIBRARY JSTAF EXECUTE <Fully-qualified name of STAFHTTPSLS.jar> [OPTION <Name[=Value]>]... PARMS "CONFIGFILE <ConfigFileLocation> [DOWNLOADATTEMPTS <NumDownloadAttempts>] [DOWNLOADRETRYDELAY <DelayInSeconds>]"
`LIBRARY` must always be `JSTAF` which is the STAF Java
service proxy library (because the HTTP Service Loader is written in Java).
`EXECUTE` specifies the location of the jar file which implements
the HTTP service loader service. On Windows, specify
`{STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar`.
On Unix, specify `{STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar`.
`OPTION` specifies a configuration option that will be passed to JSTAF
to further control the interface to the JVM where this service loader will be run.
You may specify multiple `OPTION`s. See section [4.4.2, "JSTAF service proxy library"](#HDRJVMCFG)
for acceptable options to the JSTAF service proxy library.
For example, you can override the version of Java that you want the HTTP service
loader service to use via the `JVM=<Java Path>` option when you create
a new JVM by also using the `JVMName=<JVM Name>` option.
`PARMS` specifies the parameters that will be passed to the service
loader during initialization where:
# Add HTTP Service Loader Service on Windows using local HTTPSLS config file SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \ PARMS "CONFIGFILE {STAF/Config/STAFRoot}/bin/httpsls.cfg" # Add HTTP Service Loader Service on Unix using HTTPSLS config file on SourceForge website SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/lib/STAFHTTPSLS.jar \ PARMS "CONFIGFILE http://staf.sourceforge.net/current/STAFHTTPSLS.cfg" # Add HTTP Service Loader Service on Windows using HTTPSLS config file on a web server SERVICELOADER LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/bin/STAFHTTPSLS.jar \ OPTION JVMName=HTTPSLS OPTION JVM=C:/java1.5.0_12/bin/java \ PARMS "CONFIGFILE http://server.company.com/project/httpsls.cfg \ DOWNLOADATTEMPTS 3 DOWNLOADRETRYDELAY 7"
Note that you can register the HTTP service loader service multiple times
specifying unique values for the
`CONFIGFILE` parameter.
For example, you may have one HTTP service loader service that downloads STAF
Java services like STAX, Event, Cron, and Email from the SourceForge website
and you may have a second HTTP service loader service that downloads your
custom STAF Java services from your own web server.
The HTTP service loader service is configured through a text file called the HTTPSLS configuration file. This file may have any name you desire and can be located on a web server or on the local machine. The HTTPSLS configuration file is read and processed line by line. Whitespace at the front and end of each line is removed before processing. Blank lines, or lines containing only whitespace, are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line.
Each service that you want the HTTP service loader service to load must
have a
`SERVICE` entry in the HTTPSLS configuration file. The syntax
for each service is similar to the `SERVICE` syntax used when
registering a STAF service in the STAF configuration file.
You specify a comment by placing a pound sign, #, as the first non-blank character in the line. Comment lines are ignored. For example:
# This is a comment line
External Java services are registered with the
`SERVICE`
configuration statement. The syntax is:
SERVICE <Name> LIBRARY JSTAF EXECUTE <Location of Service Jar or Zip File> [ZIPPATH <Path to Service Jar File>] [OPTION <Name[=Value]>]... [PARMS "<Service Parameters>"]
`SERVICE` specifies the name of the STAF service to be
registered.
`LIBRARY` must always be JSTAF which is the STAF Java service
proxy library as the HTTP Service Loader only supports loading Java
services.
`EXECUTE` specifies the url for the Java jar file which
implements the service. Or, it can specify the url of a zip file that
contains the Java jar file if the `ZIPPATH` option is also
specified. Or, it can specify the fully-qualified name of the Java jar
file that resides on the local machine. This option will resolve STAF
variables. For example:
http://server1.company.com/staf/myservice.jar http://prdownloads.sourceforge.net/staf/STAXV333.zip C:/STAF/services/stax/STAX.jar {STAF/Config/STAFRoot}/services/email/STAFEmail.jar
`ZIPPATH` specifies the path to the service jar file in the
zip file specified by the `EXECUTE` option. Note that this
option should only be used if the `EXECUTE` option specifies
a url for a zip file that can be unzipped using the STAF ZIP service.
This option does not resolve STAF variables. For example:
stax/STAX.jar myService.jar
`OPTION` specifies a configuration option that will be passed
on to JSTAF to further control the interface to the JVM where this
service will be run. You may specify multiple `OPTION`s for
a given service. See section [4.4.2, "JSTAF service proxy library"](#HDRJVMCFG) for valid
options that can be specified for the JSTAF service proxy library.
`PARMS` specifies parameters that will be passed to the
service during initialization.
# Register the custom SERVICE1 service, downloading it from a web server SERVICE SERVICE1 LIBRARY JSTAF EXECUTE http://www.company.com/service1.jar # Register the custom SERVICE2 service, downloading it from a web server SERVICE SERVICE2 LIBRARY JSTAF EXECUTE http://www.company.com/service2.jar \ OPTION JVMName=SERVICE2 # Register the STAX V3.3.0 service, downloading it from the SourceForge website SERVICE STAX LIBRARY JSTAF \ EXECUTE http://prdownloads.sourceforge.net/staf/STAXV333.zip \ ZIPPATH stax/STAX.jar \ OPTION JVMName=STAX OPTION J2=-Xmx1024m \ PARMS "EXTENSIONXMLFILE C:/staf/services/extensions.xml" # Register the Cron V3.3.2 service, downloading it from the SourceForge website SERVICE CRON LIBRARY JSTAF \ EXECUTE http://server.company.com/staf/CronV332.zip \ ZIPPATH cron/STAFCron.jar OPTION JVMName=CRON # Register the Email service (which resides in a jar file on the local machine) SERVICE EMAIL LIBRARY JSTAF EXECUTE C:/STAF/services/email/STAFEmail.jar \ PARMS "MAILSERVER NA.relay.ibm.com \ BACKUPMAILSERVERS \"LA.relay.ibm.com EMEA.relay.ibm.com\""
A sample HTTP Service Loader Service Configuration File is available
on SourceForge that can be used to download the latest versions of
STAF Java services available on SourceForge such as STAX, Event,
Cron, EventManager, etc. It is located at
http://staf.sourceforge.net/current/STAFHTTPSLS.cfg.
Note that you may need to customize this HTTPSLS configuration file
for the services that you use by changing parameters for some services
(like the
`MAILSERVER` and `BACKUPMAILSERVERS` parameters
for the Email service) and/or you may need to run some services like STAX
in its own JVM with a larger maximum heap size for the JVM by adding some
`OPTION`s. Or, you may not use use some of the services so you
may want to remove them, or you may want to download the STAF Java service
zip files and put them on your own web server for faster download times, etc.
Authenticator services are registered with the AUTHENTICATOR configuration statement.
The first Authenticator registered is the default, unless overridden by using the
`DEFAULTAUTHENTICATOR` operational parameter.
AUTHENTICATOR <Name> LIBRARY <Implementation library> [EXECUTE <Executable>] [OPTION <Name[=Value]>]... [PARMS <Parameters>]
`<Name>` is the name by which this authenticator service will be
known on this machine. The name cannot be "none" as this is reserved for use by STAF.
If you want to authenticate across systems, you must register the authenticator on
each system using the same name (case-insensitive).
`LIBRARY` is the name of the shared library / DLL which implements
the authenticator service or acts as a proxy for the authenticator service.
See the information for each authenticator to determine the appropriate value
for this option.
`EXECUTE` is used by service proxy libraries to specify what
the proxy library should execute. For example, this might be the name of the
Java jar file which actually implements the authenticator service.
This option has no significance for non-proxy service libraries. See the
Service Registration section for information regarding the JSTAF
service proxy library.
`OPTION` specifies a configuration option that will be passed on
to the shared library / DLL. This is typically used by service proxy
libraries to further control the interface to the actual service
implementation. You may specify multiple `OPTION`s 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](http://staf.sourceforge.net/getcurrent.php) website.
It is called AuthSample and is available as a jar file called
AuthSampleV300.jar.
To try out user trust, you can register the sample authenticator as follows (assuming you downloaded it to a services directory created in the STAF root directory).
AUTHENTICATOR AuthSample LIBRARY JSTAF \ EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \ PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/authsample.properties"
`LIBRARY` must be JSTAF for this sample authenticator
as it is implemented in Java.
`EXECUTE` must be the fully-qualified name of the AuthSampleV300.jar
file.
This sample authenticator has the following required parameter:
To perform user authentication across systems, the authenticator must be registered as the same name (case-insensitive) on all machines where you want to use user trust authentication and with the same user properties file (e.g. one that supports the same user identifiers and passwords).
An example of a user properties file is:
# User Properties File for the Sample Authenticator User1=Password1 User2=Password2 User3=Password3 User4=Password4 User5=Password5
You can specify any user identifiers and passwords that you want
in a user properties file.
However, if you specify any confidential information (e.g. any real
passwords that you want to protect), you should only use the secure
TCP interface so that this information is protected when sent over
the network.
STAFProc allows you to set various parameters which affect the general operation of STAF. The SET configuration statement lets you set these general operational parameters.
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>[s|m|h|d|w]] [MAXQUEUESIZE <Number>] [MAXRETURNFILESIZE <Number>[k|m]] [HANDLEGCINTERVAL <Number>[s|m|h|d]] [INITIALTHREADS <Number>] [THREADGROWTHDELTA <Number>] [DATADIR <Directory Name>] [INTERFACECYCLING <Enabled | Disabled>] [DEFAULTINTERFACE <Name>] [DEFAULTAUTHENTICATOR <Name>] [ENABLEDIAGS] [STRICTFSCOPYTRUST] [RESULTCOMPATIBILITYMODE <Mode>] [DEFAULTSTOPUSING <Method>] [DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE] [DEFAULTFOCUS <Background | Foreground | Minimized>] [PROCESSAUTHMODE <Authentication Mode>] [DEFAULTAUTHUSERNAME] [DEFAULTAUTHPASSWORD] [DEFAULTAUTHDISABLEDACTION <Disabled Action>] [DEFAULTSHELL <Shell>] [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
`CONNECTATTEMPTS` specifies the maximum number of times to attempt
to connect to a remote system. The default is 2.
Note that a trace warning message is generated for each failed attempt if the
Warning trace point is enabled.
You may also change this setting dynamically using the MISC service's SET command.
`CONNECTRETRYDELAY` specifies the maximum time in milliseconds to
wait after a failed connection attempt to a remote system before trying to connect
again (if the maximum number of times to attempt to connect to a remote system has
not been reached yet). The default is 1000 (i.e., 1 second).
You may also change this setting dynamically using the MISC service's SET command.
The retry delay time may be expressed in milliseconds, seconds, minutes, hours,
days, or weeks. Its format is `<Number>[s|m|h|d|w]`, where `<Number>`
is an integer >= 0 and indicates milliseconds unless one of the
following case-insensitive suffixes is specified: s (for seconds),
m (for minutes), h (for hours), d (for days), or w (for weeks).
Examples of valid values include `2s` or `2000`.
`MAXQUEUESIZE` specifies the maximum size of the queue associated
with each process' handle. The default is 100.
You may also change this setting dynamically using the MISC service's SET command.
`MAXRETURNFILESIZE` specifies the maximum size of a file that
can be returned by a START request submitted to the PROCESS service running
on this machine or by a GET FILE request submitted to the FS service running
on this machine. The default is 0 which indicates not to limit the maximum
size of returned files. Limiting the maximum returned file size can
help prevent out of memory issues as these requests put the entire returned file
contents in a result string which can consume a lot of memory for large files.
This value may be expressed in bytes, kilobytes, or megabytes.
Its format is `<Number>[k|m]` where `<Number>` is an integer
>= 0 and indicates bytes unless one of the following case-insensitive suffixes
is specified: `k` (for kilobytes) or `m` (for megabytes).
The calculated value cannot exceed `4294967295` bytes.
Examples of valid values include `100000`, `500k`, or
`5m`.
Note that in addition to setting the
`MAXRETURNFILESIZE` operational
parameter, you can also set the STAF/MaxReturnFileSize variable in the request
variable pool of the handle that submitted the request. The lowest of these two
values is used as the maximum return file size (not including 0 which indicates
no limit). Or, if you're using STAX, it also provides a `MAXRETURNFILESIZE`
parameter that can be set when registering the STAX service or dynamically via the
STAX service's SET MAXRETURNFILESIZE request. See the
[STAX User's Guide](http://staf.sourceforge.net/current/STAX/staxug.html)
for more information.
`HANDLEGCINTERVAL` specifies the time interval that the
Handle Manager's garbage collection polling loop will wait between
loops before polling each remote handle specified in the notification
list to see if the remote machine is still running the same instance
of STAFProc and if the handle still exists. The default is 60000
(i.e. 1 minute). You may also change this setting dynamically using
the MISC service's SET command. The time interval may be expressed in
milliseconds, seconds, minutes, hours, or days. Its format is
`<Number>[s|m|h|d]`, where `<Number>` is an integer
>= 0 and indicates milliseconds unless one of the following
case-insensitive suffixes is specified: s (for seconds), m (for minutes),
h (for hours), or d (for days). Note that the calculated value
cannot be less than 5 seconds and cannot exceed 24 hours. Examples of
valid values include `2m`, `45s`, or `50000`.
`INITIALTHREADS` specifies the number of threads initially created
to handle service requests. The default is 5.
`THREADGROWTHDELTA` specifies the number of additional threads which
should be created when all existing threads are busy. The default is 1.
`DATADIR` specifies the directory that STAF and its services will
use to write data. The default is `{STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}`.
Note that this directory name must be unique per instance of
STAFProc running on a single machine. Also, make sure to include the
"SET DATADIR" line in the STAF configuration file at the beginning of the
file, before any services are registered, since the data directory can be
used during service registration.
See [4.14, "Data Directory Structure"](#HDRDATADIRCFG) for more information about the
STAF data directory and its contents.
`INTERFACECYCLING` specifies whether to enable or disable automatic
interface cycling. The default is to enable automatic interface cycling.
You may also change this setting dynamically using the MISC service's SET command.
Recognized values are the following:
Note that automatic interface cycling only has an effect if there are multiple interfaces configured in the STAF configuration file on the machine that is submitting a STAF request. Also, note that the MISC service provides a LIST ENDPOINTCACHE request to show the cached endpoints and a PURGE ENDPOINTCACHE request to purge one or more cached endpoints.
`DEFAULTINTERFACE` specifies the name of the network interface
(aka connection provider) to use, by default. If not specified, the first
interface registered is the default.
You may also change this setting dynamically using the MISC service's SET command.
`DEFAULTAUTHENTICATOR` specifies the name of the Authenticator to
use, by default. If not specified, the first Authenticator registered is the
default. If no authenticators are registered, the default authenticator is
`none`.
You may also change this setting dynamically using the MISC service's SET command.
`ENABLEDIAGS` specifies to enable diagnostics. The default is
to disable diagnostics.
You may also enable (or disable) recording diagnostics dynamically
using the DIAG service.
`STRICTFSCOPYTRUST` specifies to enable strict trust checking
when copying a file or directory using the FS service. The default is
to disable strict trust checking (e.g. do lenient trust checking) on a FS
COPY request when the machine submitting the request is the same as the
machine where which the file/directory is being copied.
That is, `STRICTFSCOPYTRUST` specifies that a trust check should be done to
verify that MachineA trusts MachineB when MachineA submits a COPY request to the
FS service on MachineB to copy a file or directory back to MachineA.
The default is to do lenient trust checking so that MachineA does not have
to trust MachineB since why would MachineA ask MachineB to copy the file/directory
if he didn't want the copy to work.
You may also change this setting dynamically using the FS service's SET command.
`RESULTCOMPATIBILITYMODE` specifies the compatibility mode used
when sending the result from a STAF service request back to a pre-STAF V3 system.
Recognized values are the following:
`DEFAULTSTOPUSING` allows you to specify the default method used
to STOP processes. See [8.13.3, "STOP"](#HDRPSSTOP) for more information on available
methods.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTNEWCONSOLE` specifies that processes should be STARTed in a
new console window. So, if a process's stdout/stderr is not redirected, it will be
unavailable. This is the default for Windows systems.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTSAMECONSOLE` specifies that processes should be STARTed in
the same console as STAFProc. So, if a process's stdout/stderr is not redirected,
it will be written to STAFProc's stdout/stderr. This is the default on Unix systems.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTFOCUS` specifies the focus that is to be given to new windows
opened when starting a process on a Windows system. The default focus mode is Background.
This option only has effect on Windows systems. This option will resolve variables.
See [8.13.2, "START"](#HDRPROCSTR) for more information on the `FOCUS` option.
You may also change this setting dynamically using the PROCESS service's SET command.
`PROCESSAUTHMODE` specifies the mode by which usernames/passwords
are authenticated when starting processes. The value of this option is platform
specific. Recognized values are the following:
**Note: **Previously, `PASSWD` and `SHADOW` were supported values
for the `PROCESSAUTHMODE` on Unix systems, but support for for these
modes has been removed.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTAUTHUSERNAME` specifies the username under which processes
will be started, by default. Note, this option IS valid even if process
authentication has been disabled.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTAUTHPASSWORD` specifies the password with which processes
will be authenticated, by default. Note, this option IS valid even if process
authentication has been disabled.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTAUTHDISABLEDACTION` specifies what default action should be
taken if the user specifies a username/password on a request to start a process
when process authentication has been disabled. The following values are
recognized:
`DEFAULTSHELL` specifies the default shell to use when starting a
process via a separate shell. The default shell used for Unix systems is /bin/sh.
The default shell used for Windows systems is "cmd.exe /c".
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTNEWCONSOLESHELL` specifies the default shell to use when
starting a process in a new console window (e.g. `NEWCONSOLE`) via a separate shell, overriding
the `DEFAULTSHELL` value if specified.
You may also change this setting dynamically using the PROCESS service's SET command.
`DEFAULTSAMECONSOLESHELL` specifies the default shell to use when
starting a process in the same console as STAFProc (e.g. `SAMECONSOLE`) via a separate shell,
overriding the `DEFAULTSHELL` value if specified.
You may also change this setting dynamically using the PROCESS service's SET command.
A shell value can contain substitution characters described in the following table.
[Table 1. Substitution Characters for Shells]
|Substitution character||Description||Supported systems|
|%c||Substitute the values specified by the |COMMAND and
PARMS options.
|Windows and Unix|
|%C||Same as %c, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%p||Substitute the value specified by the |PASSWORD option,
or an empty string if no PASSWORD is provided.
|Windows and Unix|
|%P||Same as %p, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%t||Substitute the value specified by the |TITLE option,
or <Unknown> if no TITLE is provided.
|Windows and Unix|
|%T||Same as %t, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%u||Substitute the value specified by the |USERNAME option,
or an empty string if no USERNAME is provided.
|Windows and Unix|
|%U||Same as %u, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%w||Substitute the value specified by the |WORKLOAD option,
or <Unknown> if no WORKLOAD is provided.
|Windows and Unix|
|%W||Same as %w, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%x||Substitute the values specified by the |COMMAND and
PARMS options followed by input/output redirection, if
I/O options are specified on the PROCESS START request
(e.g. STDIN, STDOUT). When using this option, do not
specify any redirection in the COMMAND/PARMS values.
|Windows and Unix|
|%X||Same as %x, except the substituted value will be quoted (with all nested quotes properly escaped).||Windows and Unix|
|%%||Substitute a %.||Windows and Unix|
**Notes: **
SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2s SET MAXQUEUESIZE 1000 SET MAXRETURNFILESIZE 25m SET HANDLEGCINTERVAL 50s SET INITIALTHREADS 10 THREADGROWTHDELTA 3 SET DATADIR /test/stafdata SET DEFAULTINTERFACE tcp SET DEFAULTAUTHENTICATOR SampleAuth SET ENABLEDIAGS SET RESULTCOMPATIBILITYMODE none SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE SET DEFAULTFOCUS minimized SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C" SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C" SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X" SET DEFAULTSHELL "su - %u -c %C"
You may set STAF variables in the system or shared variable pool at startup by using the SET VAR configuration statement. SET VAR will set a variable to a certain value. The variable is created if it does not exist.
Note that you may SET multiple variables with a single request.
SET [SYSTEM | SHARED] VAR <Name=Value> [VAR <Name=Value>] ...
`SYSTEM` means the variable is to be set in system variable pool.
This is the default.
`SHARED` means the variable is to be set in shared variable pool.
`VAR` means the variable to be set. Name is the name of the variable
and Value is the value of the variable.
SET VAR WebServer=testsrv1.test.austin.ibm.com SET SHARED VAR "Author1=Jane Tester" VAR "Author2=John Tester" SET SYSTEM VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
You may grant access to machines or users by using the TRUST configuration statement.
Trust configuration statements for machines are based on the network identification of the system. In particular, different trust levels can be given to the same system coming in through different networking interfaces. Both logical and physical identifiers may be used in trust configuration statements for machines.
Trust configuration statements for users require that you have an authenticator registered.
TRUST LEVEL <Level> < DEFAULT | MACHINE <Machine> [MACHINE <Machine>]... | USER <User> [USER <User>]... >
`LEVEL` is the level of trust that you wish to grant,
see [2.5, "Security"](#HDRTRSTCON) for a list of trust levels.
This option will resolve variables.
`DEFAULT` indicates that you wish to set the default trust level.
This is the trust level that will be used for machines which have no
explicit trust level set. If no default has been specified in the STAF
Configuration file, the default is set to 3.
`MACHINE` indicates a specific machine for which to set a trust
level.
This option will resolve variables.
The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).
Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.
Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)
`USER` indicates a user for which to set a trust level.
This option will resolve variables.
The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
If multiple trust specifications would match the same user, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
If multiple trust specifications would match the same system, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
**Note: **The user authentication overrides the machine authentication.
For example, if the machine trust level is 3 and the authenticated user
has a trust level of 4, then the handle will have a trust level of 4.
If the user has been authenticated, but there are no user authentication
trust matches, the machine trust level is used. If there is no
machine trust level specified, then the default trust level is used.
TRUST DEFAULT LEVEL 3 TRUST LEVEL 5 MACHINE local://local TRUST LEVEL 5 MACHINE client1.austin.ibm.com MACHINE client3.raleigh.ibm.com TRUST LEVEL 5 MACHINE 9.3.224.16 TRUST LEVEL 4 MACHINE tcp://mysystem.site.com TRUST LEVEL 0 MACHINE badguy.austin.ibm.com TRUST LEVEL 3 MACHINE tcp2://9.3.224.* TRUST LEVEL 2 MACHINE *.austin.ibm.com TRUST LEVEL 2 MACHINE tcp*://*.site.com TRUST LEVEL 5 USER John@company.com USER Jane@company.com TRUST LEVEL 0 USER badguy@company.com TRUST LEVEL 3 USER *@company.com TRUST LEVEL 4 USER SampleAuth://*@company.com TRUST LEVEL 1 USER *://*
You may specify that you want notifications sent to certain
machines/processes when STAF is either started or shutdown. You do this by
using the NOTIFY configuration statement. Notifications are handled by the
STAF Queue service, see
[8.14, "Queue Service"](#HDRQUEUESRV) for more information.
**Note: **You may also dynamically register for SHUTDOWN notifications via the
SHUTDOWN service, see [8.18, "Shutdown Service"](#HDRSHUTDS).
**Warning: **In order for the receiving machine to accept the
notifications, it must specify a default or explicit trust level of at least
3 for this machine. As of version 2.2.0 of STAF, the default trust level
is 3, so no explicit action is necessary on systems running this version of
STAF (or higher).
NOTIFY <ONSTART | ONSHUTDOWN> MACHINE <Machine> [PRIORITY <Priority>] <NAME <Name> | HANDLE <Handle>>
`ONSTART` indicates that a notification should be sent when
STAF is fully initialized. The type of the message will be the string `STAF/Start`
with a blank message.
`ONSHUTDOWN` indicates that a notification should be sent when
STAF is shutdown. The type of the message will be the string `STAF/Shutdown`
with a blank message.
`MACHINE` indicates the machine to receive the message.
`PRIORITY` indicates the priority of the message. The default is
5.
`NAME` specifies that all processes with the given registered
name on the given machine should be notified. This option is usually
preferred over `HANDLE`, as it is difficult to know the desired
handle in advance.
`HANDLE` specifies that the process with the given handle on the
given machine should be notified.
NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager
STAF provides various tracing facilities to help in auditing and debugging. STAF externalizes these facilities through trace points. Enabling a particular trace point causes trace messages to be generated whenever a particular event occurs, such as a service request resulting in an "Insufficient Trust Level" (aka "Access Denied") error code. Care should be taken when enabling trace points, as certain trace points, such as ServiceResult, can lead to large quantities of trace messages being generated. In these cases, it is best to limit tracing to only specific services.
You may enable or disable STAF trace points and STAF services for tracing
using the
`TRACE` configuration statement. In addition, you can set the
trace output destination and set the default tracing state for newly
registered services. By default, all STAF services are enabled for tracing.
Also, if you are using the default STAF configuration file provided,
only the `ERROR` and `DEPRECATED` trace points are enabled
by default.
**Note: **The ` TRACE ENABLE/DISABLE SERVICE(S) `statements affect the current
list of services. So, if you add line ` TRACE DISABLE ALL SERVICES `
to the configuration file and then register any external services later in the
configuration file, those services will not necessarily be disabled.
To ensure that all registered services are disabled, either set the default
service state to disabled, or add the `TRACE` statements after the
`SERVICE` configuration statements in the configuration file.
TRACE ENABLE ALL [ TRACEPOINTS | SERVICES ] TRACE ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> TRACE ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... TRACE ENABLE SERVICE <Service> [SERVICE <Service>]... TRACE DISABLE ALL [ TRACEPOINTS | SERVICES ] TRACE DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> TRACE DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... TRACE DISABLE SERVICE <Service> [SERVICE <Service>]... TRACE SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] > TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled> TRACE SET MAXSERVICERESULTSIZE <Number>[k|m]
See the TRACE service, section
[8.19, "Trace Service"](#HDRTRACESRV),
for information on the above options.
See table
[8.19.2, "Trace Points Reference"](#HDRTRACEPOINTREF) for a list of valid trace points.
TRACE SET DESTINATION TO STDERR TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc APPEND TRACE SET DESTINATION TO STDOUT FILE {STAF/Config/STAFRoot}/bin/STAF.trc TRACE SET DESTINATION TO STDERR FILE {STAF/Config/STAFRoot}/bin/STAF.trc TRACE ENABLE ALL TRACE DISABLE SERVICE "Sem" TRACE ENABLE TRACEPOINTS "Error ServiceAccessDenied" TRACE DISABLE SERVICES "Process Queue Var" TRACE SET DEFAULTSERVICESTATE Enabled TRACE SET MAXSERVICERESULTSIZE 10k
In order to ensure that you are only tracing service results on the var and sem services, and that tracing for all other services is disabled (including services registered in the future) do this :
TRACE SET DEFAULTSERVICESTATE Disabled TRACE DISABLE ALL SERVICES TRACE DISABLE ALL TRACEPOINTS TRACE ENABLE TRACEPOINTS "ServiceResult" TRACE ENABLE SERVICES "VAR SEM"
This is the default configuration file provided with STAF.
# Turn on tracing of internal errors and deprecated options trace enable tracepoints "error deprecated" # Enable TCP/IP connections interface ssl library STAFTCP option Secure=Yes option Port=6550 interface tcp library STAFTCP option Secure=No option Port=6500 # Set default local trust trust machine local://local level 5 # Add default service loader serviceloader library STAFDSLS
**Warning: **This configuration file contains references to fictional services,
machines, etc. and is provided for informational purposes only. Please do
not try to use this as your actual STAF.cfg file. It is unlikely to
work.
# --------------------------------------------------------------------- # STAF Configuration File # --------------------------------------------------------------------- # Set the writeable location where STAF can write data SET DATADIR E:\test\stafdata # Enable TCP/IP connections interface ssl library STAFTCP option Secure=Yes option Port=6550 interface tcp library STAFTCP option Secure=No option Port=6500 option ConnectTimeout=10000 # Set default local trust trust machine local://local level 5 # Add default service loader serviceloader library STAFDSLS # --------------------------------------------------------------------- # STAF Log Mask Variable # --------------------------------------------------------------------- SET SHARED VAR STAF/Service/Log/Mask="START STOP WARNING FATAL ERROR" # --------------------------------------------------------------------- # Setup Trust Levels # --------------------------------------------------------------------- TRUST DEFAULT LEVEL 2 TRUST LEVEL 3 MACHINE test1.austin.ibm.com MACHINE test2.test.austin.ibm.com TRUST LEVEL 5 MACHINE automate.austin.ibm.com TRUST LEVEL 4 MACHINE *.test.austin.ibm.com TRUST LEVEL 3 USER IBM://*@us.ibm.com TRUST LEVEL 4 USER JohnDoe@company.com TRUST LEVEL 0 USER BadGuy@company.com # --------------------------------------------------------------------- # Delegated Services # --------------------------------------------------------------------- SERVICE pager DELEGATE globpager.test.austin.ibm.com # --------------------------------------------------------------------- # Java Services # --------------------------------------------------------------------- # Operating system independent name for my STAF services directory SET SYSTEM VAR myServiceDir={STAF/Config/STAFRoot}{STAF/Config/Sep/File}services SERVICE STAX LIBRARY JSTAF \ EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAX.jar \ OPTION J2=-Xms64m OPTION J2=-Xmx128m SERVICE Event LIBRARY JSTAF \ EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAFEvent.jar # --------------------------------------------------------------------- # C++ Services # --------------------------------------------------------------------- SERVICE log LIBRARY STAFLog SERVICE monitor LIBRARY STAFMon SERVICE respool LIBRARY STAFPool # --------------------------------------------------------------------- # Notifications # --------------------------------------------------------------------- NOTIFY ONSTART MACHINE automate.austin.ibm.com PRIORITY 3 NAME EventManager NOTIFY ONSHUTDOWN MACHINE automate.austin.ibm.com NAME EventManager # --------------------------------------------------------------------- # Activate tracing # --------------------------------------------------------------------- TRACE SET DESTINATION TO FILE {STAF/DataDir}/user/STAF.trc TRACE ENABLE TRACEPOINTS "ServiceAccessDenied Error" TRACE ENABLE SERVICES "Process Trust"
STAF provides a way to tune its thread stack size. This is done via setting a "STAF_THREAD_STACK_SIZE" environment variable before STAFProc gets started. User can use this environment variable to set STAF's thread stack size in kilobytes.
On Unix: export STAF_THREAD_STACK_SIZE=128 On Windows: set STAF_THREAD_STACK_SIZE=128
By default, STAF and its services will write data to:
`{STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}`.
For example: `C:\STAF\data\STAF` on Windows systems or `/usr/local/staf/data/STAF`
on Unix systems or `/Library/staf/data/STAF` on Mac OS X systems.
The `STAF/DataDir` system variable is set to the fully-qualified name
of this directory.
You may use the DATADIR operational parameter to change the writeable data directory for STAF. This directory name must be unique per instance of STAF running on a single machine.
Note that the ability to change the data directory allows you to install STAF to a shared location (e.g. a read-only directory that is accessible via a mounted drive, etc.) and use a unique writeable data directory per instance of STAF.
The following table describes the structure of the STAF data directory:
[Table 2. Data Directory Structure]
|Directory Name||Description|
{STAF/DataDir}/tmp
|This is the location where temporary data can be stored.
This directory and all of its contents will be removed and an empty |tmp
directory is created whenever STAFProc is restarted.
{STAF/DataDir}/user
|Other user data (e.g. from testcases, applications, etc.) can be stored in this directory. You should create subdirectories within this directory to when storing your data.|
{STAF/DataDir}/service
|This directory exists if one or more external services are (or have been) registered.
If a service stores persistent data, it should create a subdirectory within this
directory using its registered service name (in lower-case) and store its data in this
subdirectory. For example:
|
{STAF/DataDir}/service/event {STAF/DataDir}/service/log {STAF/DataDir}/service/stax
{STAF/DataDir}/lang/java/jvm
|This directory exists if one or more external Java services are (or have been) registered.
For each JVM created for Java services, STAF will create a subdirectory within this
directory using the name of the JVM. The log files for the JVM (e.g. |JVMLog.1)
will be stored in this subdirectory. For example:
{STAF/DataDir}/lang/java/STAFJVM1/JVMLog.1 {STAF/DataDir}/lang/java/STAX/JVMLog.1
{STAF/DataDir}/lang/java/service
|This directory exists if one or more external Java services are (or have been) registered.
For each Java service registered, STAF will create a subdirectory within this
directory using the registered service name and a subdirectory with it named |jars.
This subdirectory will contain nested jar files for the service, if any are provided
by the service. For example:
{STAF/DataDir}/lang/java/service/Event/jars {STAF/DataDir}/lang/java/service/STAX/jars
{STAF/DataDir}/register
|For STAF's use only. This directory is used for storing registration data, if any, specified when this version of STAF was installed.|
On Unix systems, STAF also writes a few files to the /tmp directory by default for each instance of STAFProc that is running. You can override the location of the directory by setting the STAF_TEMP_DIR environment variable. However, you must use the same STAF_TEMP_DIR environment variable for all instances of STAFProc in order for STAF to make sure that each STAFProc instance has a unique STAF_INSTANCE_NAME and a unique {STAF/DataDir}. Note that you should not specify {STAF/DataDir}/tmp for the value of the STAF_TEMP_DIR environment variable because each time STAFProc starts, it deletes the {STAF/DataDir}/tmp directory and this occurs after STAF creates some of these files.
The following files are created in the Unix STAF Temporary Directory when starting STAFProc (and are deleted when STAFProc is shutdown).
**Note: ** `<STAF_INSTANCE_NAME>` will be replaced with the actual
STAF Instance Name which defaults to "STAF" unless it is overridden by setting
the STAF_INSTANCE_NAME environment variable.
**Note: ** `<DATADIR>` will be replaced with the resolved value of the
{STAF/DataDir}variable, with the slashes replaced with dashes.
For example: `DataDir_-usr-local-staf-data-STAF.tmp`
This is a socket file used by the Unix Local IPC connection provider. If this socket file is inadvertently deleted, local service requests will fail with RC 21 (STAF Not Running).
This is a socket file used by a STAF JVM that was created when registering a STAF Java service. There will be one socket file for each STAF JVM.
**Note: ** `<JVMName>` will be replaced by the actual STAF JVM name.
**Warning! Do not delete these files while the STAFProc instance
is running.**
When submitting a request to the "local" interface to communicate with a STAFProc instance, the STAF_INSTANCE_NAME environment variable must be set (if the STAFProc instance is not using the default name "STAF"). Also, on Unix only, the STAF_TEMP_DIR environment variable must be set (if the STAFProc instance is not using the default "/tmp" directory). Otherwise, the local service request will not be able to communicate with that STAFProc instance and RC 21 (STAF Not Running) will be returned.
STAFProc is what starts STAF running on a machine.
STAFProc [STAF Configuration File]
STAFProc d:\staf\bin\mystaf.cfg
If
`[STAF Configuration File]` is not specified, STAFProc
will try to use the file staf.cfg. It will search for this file in the current
directory, as well as the directory in which STAFProc resides.
**Warning: **In order to stop the STAFProc daemon process, you should
enter the command " `STAF local shutdown shutdown`" (or use the
associated program in your "Start" menu on Windows systems). Pressing CTRL-C (or
issuing a "kill" command) will terminate STAFProc, but will not allow it
to properly cleanup, which may cause problems and/or delays when trying
to restart STAFProc. See section [8.18, "Shutdown Service"](#HDRSHUTDS) for more information
on the SHUTDOWN service.
**Note: **Any changes made to the STAF Configuration File after STAFProc has been started
will not take effect until you shutdown and restart STAFProc.
Multiple instances of STAFProc can be run at the same time on the same system . This makes it possible to use STAF to install/upgrade STAF itself. To run multiple instances of STAF, system-specific resources need to be differentiated. There is a special environment variable, STAF_INSTANCE_NAME, that can be used to specify a name for each STAFProc instance to differentiate between multiple instances of STAF. If this environment variable is not set, the default value, "STAF", is used for the instance name. If the STAF_INSTANCE_NAME environment variable is not set to a unique value prior to starting a new instance of STAFProc, you will see a "STAFProc already started" error.
For each instance of STAFProc running on a system, the following settings must be unique:
The ports used by STAF TCP connection providers must be unique, otherwise, you'll get a "Error starting tcp interface" error when starting STAFProc. If one instance of STAF is running using a ssl interface with port 6550 and a tcp interface port 6500, then to start another instance of STAF that also uses a ssl and tcp interface, you must specify a different ports in its STAF configuration file. For example:
interface tcp library STAFTCP option SECURE=Yes option PORT=6551 interface tcp library STAFTCP option SECURE=No option PORT=6501
Each STAFProc instance must use a different data directory. However, since the default setting for the data directory is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}, the data directory names will be different if they are not overridden using the DATADIR operational setting (and as long as the STAF_INSTANCE_NAME environment variable is set to a unique value). If the data directory for a STAFProc instance is not unique, you'll get a "Data directory is already in use" error when starting STAFProc
The installer creates a STAFEnv script file in the root STAF install location that can be used to set the required environment variables for a version of STAF. On Windows, the script file is called STAFEnv.bat and on Unix, the script file is called STAFEnv.sh. The STAFEnv script files are especially useful if you are going to be running two versions of STAF on the same machine and need a convenient way to switch settings for each version of STAF. An optional argument specifying the STAF instance name can be passed to a STAFEnv script file. A similar STAFEnv script file will also be created for setting up the environment for STAF V2, if STAF V2 is installed on the same machine as STAF V3.
Here's a sample STAFEnv.bat file for Windows:
@echo off REM STAF environment variables for 3.0.2 set PATH=C:\STAF\bin;%PATH% set CLASSPATH=C:\STAF\bin\JSTAF.jar;C:\STAF\samples\demo\STAFDemo.jar;%CLASSPATH% set STAFCONVDIR=C:\STAF\codepage if "%1" EQU "" set STAF_INSTANCE_NAME=STAF if "%1" NEQ "" set STAF_INSTANCE_NAME=%1
Here's a sample STAFEnv.sh file for Linux:
#!/bin/sh # STAF environment variables for 3.0.2 PATH=/usr/local/staf/bin:$PATH LD_LIBRARY_PATH=/usr/local/staf/lib:$LD_LIBRARY_PATH CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar:$CLASSPATH STAFCONVDIR=/usr/local/staf/codepage if [ $# = 0 ] then STAF_INSTANCE_NAME=STAF else STAF_INSTANCE_NAME=$1 fi export PATH LD_LIBRARY_PATH CLASSPATH STAFCONVDIR STAF_INSTANCE_NAME
The sample scripts that are created automatically by STAF will use the actual install directories in the STAFEnv script files.
Here's an example of starting STAF V2 and STAF V3 on a Windows system, where STAF V2 is installed in C:\STAF and STAF V3 is installed in C:\STAF3. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.
C: cd \STAF STAFEnv.bat STAFProcIn another command prompt:
C: cd \STAF3 STAFEnv.bat STAFProc
Here's an example of starting two instances of STAF V3 on a Unix system, specifying instance name STAF (the default) for one instance and instance name STAF2 for another instance. The STAF configuration file used by each STAFProc instance specify different port numbers for each TCP Connection Provider.
cd /usr/local/staf . ./STAFEnv.sh STAFProc /usr/local/staf/bin/STAF.cfg & . ./STAFEnv.sh STAF2 STAFProc /usr/local/staf/bin/STAF2.cfg &
**Note: **The STAF_INSTANCE_NAME environment variable must be set to the same
value for a given STAFProc daemon and any applications/testcases that want
to communicate to the instance of STAF.
On Windows Vista and Windows Server 2008 and later (including Windows 7, Windows 8, and Windows Server 2012, etc) with User Account Controls (UAC) enabled, STAFProc is run using the least amount of privileges (e.g. that of a standard user) even if you are logged in as an administrator. If you want to run a process via the STAF PROCESS START request that requires administrative privileges, such as an install program, and not get UAC prompts, you may need to run STAFProc as an administrator. There are several ways to do this:
**Note: **When STAFProc.exe is run as an Administrator, you must also run STAF.exe
as an Administrator if you want to submit STAF requests from a command prompt
on the local Windows sytems. Otherwise, you'll get "Error registering with STAF, RC: 21".
The same is true if you run a program on this Windows system that submits
STAF service requests using the STAF APIs for Java, C/C++, Perl, Python, Tcl, etc,
such as the STAX Monitor Java application. The program must also be
run as an Administrator (e.g. by running it from an "Administrator: Command Prompt").
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"](#HDRSTAFSHS) for more information
on using the STAF command from within shell-scripts.
STAF [-verbose] <Endpoint> <Service> <Request>
[<Interface>://]<System Identifier>[@<Port>]where:
STAF local PING PING STAF local sem event SynchSem post STAF testmach1 PROCESS START COMMAND notepad STAF testmach1.company.com PROCESS LIST STAF -verbose testmach1.company.com PROCESS LIST STAF ssl://testmach1 PROCESS START SHELL COMMAND /tests/myTest RETURNSTDOUT STDERRTOSTDOUT WAIT STAF tcp://testmach1 TRUST LIST STAF alt-tcp2://9.3.283.13 SERVICE LIST STAF testmach1@6600 PROCESS START COMMAND notepad NOTIFY ONEND STAF tcp://testmach.company.com@6500 MISC WHOAMI STAF local ECHO ECHO "Hi there" STAF 9.3.823.20 LOG MACHINE LOGNAME MyLog LEVEL info MESSAGE "This is a message" STAF local var set SYSTEM var "SomeName=Some text string"
set STAF_INSTANCE_NAME=MySTAF staf local ping ping
On a successful STAF request (i.e., a request with a zero return code), the output from the STAF command will be as follows
Response -------- <Result string>
where
`<Result string>` is any information that was returned from
the STAF service request.
For example, the output of
`STAF LOCAL PING PING` should be
Response -------- PONG
On an unsuccessful STAF request (i.e., a request with a non-zero return code), the output from the STAF command will be as follows
Error submitting request, RC: <Return code> Additional info --------------- <Result string>
where
`<Return code>` is the actual return code from the request,
and `<Result string>` is any information returned from the request.
`<Result string>` usually contains information that explains why the
error occurred. Note, the "Additional info" will only be present if a non-empty
result string was returned. Additionally, you may refer to
[Appendix A, "API Return Codes"](#HDRRETCODE) 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"](#HDRMARSHALL)) is returned in the result
strings above, the STAF command will automatically unmarshall the data and
print it in the most appropriate format. If the data is a
`<List> of <String>`, then each entry in the list will be printed
on its own line. For example,
C:\> staf local fs list directory c:\ Response -------- AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT
If the data is a
`<Map>` (or `<Map:<Class>>`) which
has values which are all of type `<String>`, then each key/value pair will
be printed on its own line. For example,
C:\> staf local monitor list settings Response -------- Max Record Size : 1024 Resolve Message : Disabled Resolve Message Var: Disabled
The above two types of formatted output are frequently referred to as "default format".
If the data is a
`<List> of <Map:<Class>>` where every item in
the list is an instance of the same map class, then the data will be printed
out in a tabular format, called "table format". For example,
$ staf local handle list handles Response -------- Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20040929-13:57:40 2 STAF/Service/STAFServiceLoader1 InProcess 20040929-16:06:47 5 STAF/Service/LOG InProcess 20040929-13:57:52 7 STAF/Service/RESPOOL InProcess 20040929-13:58:04 51 STAF/Service/MONITOR InProcess 20040929-16:06:47 57 STAF/Client Registered 20040929-16:09:35
The column headings in the table format are determined using the display name specified for each key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.
By default a single record in the table format will only display the first 20 lines (the last line will show "(More...)" to indicate that there were more lines in the record). You can override the maximum number of lines that are displayed per record by setting the environment variable STAF_TABLE_LINES_PER_RECORD to the maximum number of lines.
You can disable the output of tables by setting the environment variable STAF_PRINT_NO_TABLES to any value. If you disable the output of tables, their data will show up in the more verbose mode (described below).
If the data is more complex than the above (or tables have been turned off), the output will be printed in a hierarchical nested format, called "verbose format". The best way to describe it is with an example.
C:\> staf local sem query event Test Response -------- { State : Reset Last Posted: { Machine : crankin3 Handle Name: STAF/Client Handle : 62 User : none://anonymous Date-Time : 20040929-16:20:56 } Last Reset : { Machine : crankin3 Handle Name: STAF/Client Handle : 65 User : none://anonymous Date-Time : 20040929-16:21:43 } Waiters : [ { Machine : crankin3 Handle Name: TestHandle Handle : 67 User : none://anonymous Date-Time : 20040929-16:22:16 } ] }
You can change the amount of indentation used by setting the environment variable STAF_INDENT_DELTA to any non-negative integer.
You can use the -verbose option to force the use of the verbose mode on a command basis. For example,
C:\> staf -verbose local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
You can force the exclusive use of the verbose mode by setting the environment variable STAF_PRINT_MODE to "verbose". For example,
C:\> set STAF_PRINT_MODE=verbose C:\> staf local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
If you should ever need to get at the raw result string (instead of the structured output), you can set the environment variable STAF_PRINT_MODE to "raw". For example,
C:\> set STAF_PRINT_MODE=raw C:\> staf local fs list directory C:/temp/docs Response -------- @SDT/*:267:@SDT/{:26::13:map-class-map@SDT/{:0:@SDT/[10:218:@SDT/$S:11:STAFTcl.h tm@SDT/$S:12:STAFPerl.htm@SDT/$S:14:STAFPython.htm@SDT/$S:7:History@SDT/$S:12:ST AFCMDS.htm@SDT/$S:11:STAFFAQ.htm@SDT/$S:10:STAFGS.pdf@SDT/$S:12:STAFHome.htm@SDT /$S:10:STAFRC.htm@SDT/$S:10:STAFUG.htm
Note, by default, any
`<String>` value that looks as though it, itself,
is a marshalled data structure will be recursively unmarshalled. For example,
if someone marshalls a data structure and uses the resultant string as the
message for a log request, and then you query the log, the data structure
in the log message string will automatically be unmarshalled. If you want
to turn off this behavior from the command line, and, instead, see the
marshalled string in the message, set the environment variable
STAF_IGNORE_INDIRECT_OBJECTS to any value.
There are two special environment variables that can be used to make the
STAF command blend in with shell-scripts. The first is STAF_QUIET_MODE.
Setting this environment variable to any non-null value will cause the STAF
command to only output the
`<Result string>` that the request
generated. For example, the "STAF local ping ping" command above would simply
return
PONG
This makes it easy to call STAF from shell-scripts. For example,
export STAF_QUIET_MODE=1 STAFResult=`STAF local ping ping` if [ $? -ne 0 ]; then echo "Non-zero return code from ping request"; elif [ "$STAFResult" != "PONG" ]; then echo "Expected PONG, received $STAFResult"; else echo "ping request succeeded" fi
The second environment variable is STAF_STATIC_HANDLE. If this environment
variable is set, the STAF command will use the handle number indicated by this
environment variable. This ensures that the shell-script can use the same
handle throughout its execution. You may obtain a static handle in one of two
ways. The first is using the CREATE command of the HANDLE service
(see
[8.6.2, "CREATE"](#HDRHANDCRT)). For example,
export STAF_STATIC_HANDLE=`STAF local handle create handle name "My Test"`
In this case, you are responsible for deleting the shell-scripts handle prior to your shell-script exiting. For example,
STAF local handle delete handle $STAF_STATIC_HANDLE
The second way is by using the STATICHANDLENAME option when starting your
script through the PROCESS service (see
[8.13.2, "START"](#HDRPROCSTR)). In this case
the STAF_STATIC_HANDLE environment variable will already be set for you. In
addition, the handle will automatically be deleted by STAF when your
shell-script completes.
You can test for the existence of the STAF_STATIC_HANDLE environment variable to determine if your shell-script was started via STAF, or whether it was started by hand from the command line.
STAF supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure.
STAF supports the following generic data types with its marshalling.
Most languages support some form of the None, String, List, and Map data types. However, a map class and a marshalling context are likely new concepts.
A map class is really just a specialized map that is associated with a map class definition. The map class definition is used to reduce the size of a marshalling map class in comparison to a map containing the same data. It also contains information about how to display instances of the map class. A map class definition contains for following information for each key defined for a map class:
You indicate that a map is an instance of a map class by setting the key "staf-map-class-name" to the name of the map class. And, when you unmarshall a data structure, if you see that a map has a key called "staf-map-class-name", you know that the map is really an instance of a map class. You get and set map class definitions using a marshalling context.
A marshalling context is simply a container for map class definitions and a data structure that uses (or is defined in terms of) them. In order to use a map class when marshalling data, you must add the map class definition to the marshalling context, set the root object of the marshalling context to the object you want to marshall, and then marshall the marshalling context itself. When you unmarshall a data structure, you will always receive a marshalling context. Any map class definitions referenced by map classes within the data structure will be present in the marshalling context.
When a string is unmarshalled into a data structure, it is possible that one of the string objects that is unmarshalled is itself the string form of another marshalled data structure. By default, STAF will recursively unmarshall these nested objects. However, each language has a way to disable these additional processing.
STAF externalizes six primary APIs to C/C++ programs. These APIs allow you to register/unregister with STAF, submit service requests, and free the memory associated with service request results. In addition, STAF provides a wide range of APIs for defining, manipulating, and marshalling data structures. Also, STAF provides some APIs for handling private data.
**Note: **STAF-enabled programs written in C must be linked with the C++ compiler
(or by using any other means which allows the C++ runtime to get initialized).
Otherwise, the C++ runtime won't get a chance to initialize so the STAF
static data doesn't get initialized. Most systems require mixed C and C++ code
to get linked by the C++ compiler.
The STAFRegister call is used by a C program to register with STAF.
STAFRC_t STAFRegister(char *handleName, STAFHandle *handle)
`handleName` points to the name by which you want this handle to
be known.
`handle` is a pointer to the STAFHandle that will be set on
successful return from the function. You will use this handle on all other
subsequent STAF calls.
char *myName = "MyProgram"; STAFHandle_t myHandle = 0; STAFRC_t rc = STAFRegister(myName, &myHandle);
The STAFRegisterUTF8 API is identical in all respects with STAFRegister,
except that
`handleName` is a string in UTF-8 format. This API is
used primarily by the Java interfaces.
The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.
STAFRC_t STAFUnRegister(STAFHandle handle)
`handle` is the handle that you received on the call to
STAFRegister.
/* myHandle was previously set by STAFRegister */ STAFRC_t rc = STAFUnRegister(myHandle);
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
STAFRC_t STAFSubmit(STAFHandle handle, char *where, char *service, char *request, unsigned int requestLength, char **resultPtr, unsigned int *resultLength);
`handle` is the handle you received on the call to STAFRegister.
`where` points to a string containing the destination machine for
the service request. This should be either LOCAL or the name of a machine.
`service` points to the name of the service to which you are
submitting the request.
`request` points to the actual request that you are sending to the
service. This request may contain NULL (0x00) bytes.
`requestLength` indicates the length of the request buffer passed
in.
`resultPtr` points to a char * that will contain the address of the
result on return from the function. If, on return from STAFSubmit,
`*resultPtr` is not 0, you must use STAFFree to free the result, even
if the return code from STAFSubmit was non-zero. Note, if resultPtr is
non-zero, then the buffer that resultPtr points to will always be NULL
terminated. However, this buffer may contain NULL (0x00) bytes, therefore, it
is not safe to determine the length of the buffer via strlen(). Instead, you
should use the length provided by `resultLength` below.
`resultLength` points to an unsigned int which, on return from
STAFSubmit, will contain the length of the result buffer.
/* myHandle was previously set by STAFRegister */ char *someMachine = "testmach1"; char *service = "PING"; char *request = "PING"; unsigned int requestLength = strlen(request); char *result = 0; unsigned int resultLength = 0; STAFRC_t rc = 0; rc = STAFSubmit(myHandle, someMachine, service, request, requestLength, &result, &resultLength);
The STAFSubmit2 API is identical to the STAFSubmit API except that it has an additional parameter, syncOption, which allows submission of asynchronous requests.
STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption, char *where, char *service, char *request, unsigned int requestLength, char **resultPtr, unsigned int *resultLength)
syncOption can be any of the following:
The format of the queued message obtained when specifying kSTAFReqQueue or
kSTAFReqQueueRetain will be a marshalled
`<Map:STAF/RequestComplete>`
which represents the request completion information. See table
[Table 3](#TBLSTAFREQUESTCOMPLETETABLE) for the map class definition.
[Table 3. Definition of map for "STAF/RequestComplete" type message]
Description: This map represents STAF/RequestComplete message information.
|Key Name||Type||Format / Value|
|requestNumber|<String>
|
|
|rc|<String>
|
|
|result|<String>
|
|
For example, if you submitted the request "RESOLVE STRING {STAF/Config/OS/Name}" to the VAR service using kSTAFReqQueue, and received a request number of 42, then the message you would receive when the request completed might look like
{ requestNumber: 42 rc : 0 result : WinNT }
The queued message will always be delivered with the default priority of 5.
The STAFSubmitUTF8 API is identical in all respects with STAFRegister,
except that
`where`, `service`, `request`,
and `*resultPtr` are all strings in UTF-8 format. This API is
used primarily by the Java interfaces.
The STAFSubmit2UTF8 API is identical in all respects with STAFSubmit2,
except that
`where`, `service`, `request`,
and `*resultPtr` are all strings in UTF-8 format. This API is
used primarily by the Java interfaces.
STAFFree is used to free the memory occupied by the result buffer on a call to STAFSubmit. You only need to call this if result buffer pointer is not zero on return from STAFSubmit.
STAFRC_t STAFFree(STAFHandle handle, char *result);
`handle` is the handle you received on the call to STAFRegister.
`result` is the pointer passed back from the STAFSubmit call.
/* myHandle was previously set by STAF */ /* result was previously set by STAFSubmit */ STAFRC_t rc = 0; if (result != 0) rc = STAFFree(myHandle, result);
STAF externalizes a wide range of APIs for defining data structures and (un)marshaling data structures. Here is a list of the APIs. A later version of this documentation will provide more details.
typedef enum { kSTAFNoneObject = 0, kSTAFScalarStringObject = 1, kSTAFListObject = 2, kSTAFMapObject = 3, kSTAFMarshallingContextObject = 4 } STAFObjectType_t; typedef enum { kSTAFMarshallingDefaults = 0x00000000 } STAFObjectMarshallingFlags_t; typedef enum { kSTAFUnmarshallingDefaults = 0x00000000, kSTAFIgnoreIndirectObjects = 0x00000001 } STAFObjectUnmarshallingFlags_t; // Object constructors/destructors // // Note: When a STAFObject is destructed, it recursively deletes all nested // objects STAFRC_t STAFObjectConstructCopy(STAFObject_t *copy, STAFObject_t source); STAFRC_t STAFObjectConstructReference(STAFObject_t *ref, STAFObject_t source); STAFRC_t STAFObjectConstructNone(STAFObject_t *pNone); STAFRC_t STAFObjectConstructScalarString(STAFObject_t *pScalar, STAFStringConst_t string); STAFRC_t STAFObjectConstructList(STAFObject_t *list); STAFRC_t STAFObjectConstructMap(STAFObject_t *map); STAFRC_t STAFObjectConstructMarshallingContext(STAFObject_t *context); STAFRC_t STAFObjectDestruct(STAFObject_t *object); // General functions STAFRC_t STAFObjectIsStringMarshalledData(STAFStringConst_t string, unsigned int *isMarshalledData); // Object functions STAFRC_t STAFObjectGetType(STAFObject_t object, STAFObjectType_t *type); STAFRC_t STAFObjectGetSize(STAFObject_t object, unsigned int *size); STAFRC_t STAFObjectIsReference(STAFObject_t object, unsigned int *isRef); STAFRC_t STAFObjectUnmarshallFromString(STAFObject_t *newContext, STAFStringConst_t string, STAFObject_t context, unsigned int flags); STAFRC_t STAFObjectMarshallToString(STAFObject_t object, STAFObject_t context, STAFString_t *string, unsigned int flags); STAFRC_t STAFObjectGetStringValue(STAFObject_t object, STAFString_t *string); // Scalar functions STAFRC_t STAFObjectScalarGetStringValue(STAFObject_t object, STAFStringConst_t *string); STAFRC_t STAFObjectScalarGetUIntValue(STAFObject_t object, unsigned int *uInt, unsigned int defaultValue); // List functions STAFRC_t STAFObjectListAppend(STAFObject_t list, STAFObject_t object); // Iterator functions STAFRC_t STAFObjectConstructListIterator(STAFObjectIterator_t *iter, STAFObject_t list); STAFRC_t STAFObjectIteratorHasNext(STAFObjectIterator_t iter, unsigned int *hasNext); STAFRC_t STAFObjectIteratorGetNext(STAFObjectIterator_t iter, STAFObject_t *object); STAFRC_t STAFObjectIteratorDestruct(STAFObjectIterator_t *iter); // Map functions STAFRC_t STAFObjectMapGet(STAFObject_t map, STAFStringConst_t key, STAFObject_t *object); STAFRC_t STAFObjectMapPut(STAFObject_t map, STAFStringConst_t key, STAFObject_t object); STAFRC_t STAFObjectMapHasKey(STAFObject_t map, STAFStringConst_t key, unsigned int *hasKey); STAFRC_t STAFObjectConstructMapKeyIterator(STAFObjectIterator_t *pIter, STAFObject_t map); STAFRC_t STAFObjectConstructMapValueIterator(STAFObjectIterator_t *pIter, STAFObject_t map); // Marshalling Context functions STAFRC_t STAFObjectMarshallingContextSetMapClassDefinition( STAFObject_t context, STAFStringConst_t name, STAFObject_t mapClassDefinition); STAFRC_t STAFObjectMarshallingContextGetMapClassDefinition( STAFObject_t context, STAFStringConst_t name, STAFObject_t *mapClassDefinition); STAFRC_t STAFObjectMarshallingContextHasMapClassDefinition( STAFObject_t context, STAFStringConst_t name, unsigned int *pHasMapClassDefinition); STAFRC_t STAFObjectMarshallingContextSetRootObject(STAFObject_t context, STAFObject_t object); STAFRC_t STAFObjectMarshallingContextGetRootObject(STAFObject_t context, STAFObject_t *object); STAFRC_t STAFObjectMarshallingContextAdoptRootObject(STAFObject_t context, STAFObject_t *object); STAFRC_t STAFObjectMarshallingContextGetPrimaryObject(STAFObject_t context, STAFObject_t *object); STAFRC_t STAFObjectConstructMapClassDefinitionIterator( STAFObjectIterator_t *pIter, STAFObject_t context);
STAF externalizes some APIs for handling private data in STAF command request options. Here are the definitions for these APIs.
// This method adds privacy delimiters to the data. // For example, if data passed in is "secret", sets result // to "!!@secret@!!". STAFRC_t STAFAddPrivacyDelimiters(STAFStringConst_t data, STAFString_t *result); // This method removes the specified number of levels of privacy // delimiters from the data. Set numLevels to 0 to remove all // levels of privacy delimiters. // For example, if data passed in is "!!@secret@!!", sets // result to "secret". STAFRC_t STAFRemovePrivacyDelimiters(STAFStringConst_t data, unsigned int numLevels, STAFString_t *result); // This method masks any private data indicated by the privacy // delimiters by replacing the private data with asterisks. // For example, if data passed in is "!!@secret@!!", sets // result to "************". STAFRC_t STAFMaskPrivateData(STAFStringConst_t data, STAFString_t *result); // This method escapes any privacy delimiters found in the data. // For example, if data passed in is "!!@secret@!!", sets // result to "^!!@secret^@!!". STAFRC_t STAFEscapePrivacyDelimiters(STAFStringConst_t data, STAFString_t *result);
STAF externalizes some other general utility APIs. Here are the definitions for these APIs.
/*********************************************************************/ /* STAFUtilFormatString - Generates a string based on a format */ /* string, ala printf(). This is generally */ /* used to format STAF request strings. */ /* */ /* Accepts: (In) The format string */ /* (Out) A pointer to the output string */ /* (In) All data indicated in the format string */ /* */ /* Returns: Standard return codes */ /* */ /* Notes : 1) The caller is responsible for destructing the */ /* output string */ /*********************************************************************/ /* Valid format string specifiers: */ /* */ /* %d - an unsigned integer */ /* %s - a STAFString_t */ /* %C - a STAFString_t which will be formatted in colon-length-colon */ /* delimited format */ /* %% - a percent sign */ /* */ /* Any other %<char> is simply ignored (and not copied) */ /*********************************************************************/ unsigned int STAFUtilFormatString(STAFStringConst_t formatString, STAFString_t *outputString, ...); /*********************************************************************/ /* STAFUtilFormatString2 - Generates a string based on a format */ /* string, ala printf(). This is generally */ /* used to format STAF request strings. */ /* */ /* Accepts: (In) The format string */ /* (Out) A pointer to the output string */ /* (In) A variable argument list */ /* */ /* Returns: Standard return codes */ /* */ /* Notes : 1) The caller is responsible for destructing the */ /* output string */ /* 2) Valid format strings are the same as defined for */ /* STAFUtilFormatString() */ /*********************************************************************/ unsigned int STAFUtilFormatString2(STAFStringConst_t formatString, STAFString_t *outputString, va_list args); /*********************************************************************/ /* STAFUtilStripPortFromEndpoint - Removes @<Port> from the end of */ /* an endpoint if present. */ /* */ /* Accepts: (In/Out) A pointer to a string containing the endpoint */ /* with format: */ /* [<Interface>://<Machine Identifier>[@<Port>] */ /* (Out) A pointer to a string containing the stripped */ /* endpoint with format: */ /* [<Interface>://<Machine Identifier> */ /* */ /* Returns: 0 */ /* Notes : 1) The caller is responsible for destructing the output */ /* string containing the stripped endpoint */ /*********************************************************************/ STAFRC_t STAFUtilStripPortFromEndpoint(STAFStringConst_t endpoint, STAFString_t *strippedEndpoint); /*********************************************************************/ /* STAFUtilConvertDurationString - Converts the time duration */ /* expressed as a string to a numeric value in milliseconds. */ /* */ /* Accepts: (In) The duration string */ /* The duration string may be expressed in */ /* milliseconds, seconds, minutes, hours, days, or */ /* weeks. Its format is: */ /* <Number>[<Type>] */ /* where <Number> is an integer >= 0 and <Type>, if */ /* specified, is one of the following: */ /* s (for seconds), m (for minutes), h (for hours), */ /* d (for days), or w (for weeks). For example: */ /* - 100 specifies 100 milliseconds, */ /* - 10s specifies 10 seconds, */ /* - 5m specifies 5 minutes, */ /* - 2h specifies 2 hours, */ /* - 1d specifies 1 day, */ /* - 1w specifies 1 week */ /* (Out) The numeric duration value in milliseconds */ /* (Out) A pointer to an error string */ /* */ /* Returns: 0, if successful */ /* 47 if unsuccessful (*errorBuffer will be set) */ /*********************************************************************/ STAFRC_t STAFUtilConvertDurationString(STAFStringConst_t durationString, unsigned int *duration, STAFString_t *errorBuffer);
STAF externalizes other APIs that fall into the following general classes
Please see the indicated header files for more information on syntax and use of these families of APIs.
STAF externalizes five primary classes to C++ programs. These class are
Additionally, these classes use several other classes which are
STAF also provides some other miscellaneous C++ classes, which are
In addition, C++ applications are able to take advantage of the C-only
APIs, such as Thread support.
The STAFHandle class is used to register with, and submit service requests to, STAF. In C++ STAFHandles are reference counted, so they are automatically freed for you. To obtain a STAFHandle, you call one of the create() methods. The first is the standard call you will use, and it allows you to specify the name by which your program should be known. The second create method allows you to create a STAFHandle object from an existing STAFHandle_t which would have been obtained from the C API STAFRegister(). By default, a STAFHandle obtained through the first method will automatically be unregistered when the STAFHandle is destructed. A STAFHandle created via the second method will not automatically be unregistered when the STAFHandle is destructed. In either case, you can change this behavior with the setDoUnreg() method.
Once you have a valid STAFHandlePtr, you can begin submitting requests to STAF. To do this, you use the submit() method, to which you specify the machine and service which should handle the request, as well as the request string itself. An optional fourth parameter defines whether this will be a synchronous or asynchronous request (if the parameter is not specified, the request will be synchronous). See the documentation for the C API STAFSubmit2 for the values allowed for this parameter. In return you get a reference counted pointer to a STAFResult object. Again, the underlying STAFResult object will be automatically freed when the reference count reaches zero. The STAFResult object itself contains a return code 'rc', a result string variable 'result', a result object variable 'resultObj', and a result marshalling context object variable 'resultContext'. If the STAFHandle's fDoUnmarshallResult flag is set to true (which it will be by default when a STAFHandle is created), then auto-unmarshalling will be performed which means the 'resultContext' variable will be set to the marshalling context obtaining from unmarshalling the string result data, and the 'resultObj' variable will contain the root object of this marshalling context. This allows you to not have to call the unmarshall() method to unmarshall the result immediately after call a submit() method. Note that if the STAFHandle's fDoUnmarshallResult flag is set to a false (which can be done using the setDoUnmarshallResult() method), the 'resultContext' and 'resultObj' variables will be set to the None object.
You may examine the underlying STAFHandle_t via getHandle(). You may take ownership of the underlying STAFHandle_t via adoptImpl(). In this latter case, you are now responsible for the STAFHandle_t and are required to call STAFUnRegister(). Additionally, after a call to adoptImpl(), the existing STAFHandle object is invalidated and may not be used to call the submit() method.
The utility function wrapData returns the colon-length-colon delimited
version of the specified string. This is useful for specifying the values in
STAF request string. See
[7.2, "Option Value Formats"](#HDROVFORM) 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"](#HDRPRIVATEDATA) for more information about handling private data.
// STAFResult - This class contains the results of a STAFSubmit call class STAFResult { public: STAFResult(STAFRC_t theRC = kSTAFOk, const STAFString &theResult = STAFString()) : rc(theRC), result(theResult) { /* Do Nothing */ } STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen, STAFString::CodePageType codePageType) : rc(theRC), result(data, dataLen, codePageType) { /* Do Nothing */ } STAFResult(STAFRC_t theRC, const char *data, unsigned int dataLen, STAFString::CodePageType codePageType, bool doUnmarshallResult) : rc(theRC), result(data, dataLen, codePageType) { if (doUnmarshallResult) { resultContext = STAFObject::unmarshall( result, kSTAFUnmarshallingDefaults); resultObj = resultContext->getRootObject(); } else { resultContext = STAFObject::createNone(); resultObj = STAFObject::createNone(); } } STAFRC_t rc; STAFString result; STAFObjectPtr resultObj; STAFObjectPtr resultContext; }; class STAFHandle; typedef STAFRefPtr<STAFResult> STAFResultPtr; typedef STAFRefPtr<STAFHandle> STAFHandlePtr; // STAFHandle - This class is used to interact with STAF. You obtain a // STAFHandle via the create() call. class STAFHandle { // This is the standard call to create a STAFHandle. By default, this // STAFHandle object will unregister with STAF when destructed. static STAFRC_t create(const STAFString &name, STAFHandlePtr &handle); // This call is used to create a STAFHandle which uses an existing // STAFHandle_t. By default, this STAFHandle object will not unregister // with STAF when destructed. static STAFRC_t create(STAFHandle_t handleT, STAFHandlePtr &handle, bool doUnreg = false); STAFResultPtr submit(const STAFString &where, const STAFString &service, const STAFString &request, const STAFSyncOption_t synchOption = kSTAFReqSync); // This returns the colon-length-colon delimited version of a string static STAFString wrapData(const STAFString &data); // This will format a string for you. See STAFUtilFormatString() in // STAFUtil.h // // Note: DO NOT try to pass STAFString's into the ... portion of this // function. The only supported data types are "unsigned int" and // STAFString_t. Therefore be sure to call getImpl() on all // STAFString's before passing them to this method. static STAFString formatString(STAFStringConst_t formatString, ...); // This returns the endpoint without the port (strips @nnnn from the end // of the endpoint, if present) static STAFString stripPortFromEndpoint(const STAFString &endpoint); // This method returns the data with privacy delimiters added. // For example, if pass in "secret", it returns "!!@secret@!!". static STAFString addPrivacyDelimiters(const STAFString &data); // This method removes any privacy delimiters from the data. // For example, if pass in "!!@secret@!!", it returns "secret". static STAFString removePrivacyDelimiters(const STAFString &data, unsigned int numLevels = 0); // This method masks any private data indicated by the privacy delimiters // by replacing the private data with asterisks. // For example, if pass in "!!@secret@!!", it returns "************". static STAFString maskPrivateData(const STAFString &data); // This method returns the data with privacy delimiters escaped. // For example, if pass in "!!@secret@!!", it returns "^!!@secret^@!!". static STAFString escapePrivacyDelimiters(const STAFString &data); STAFHandle_t getHandle() { return fHandle; } // This call allows you to claim ownership of the underlying STAFHandle_t. // Once this call is made, this STAFHandle object is no longer valid, and // it is your responsibility to unregister the STAFHandle_t with STAF. STAFHandle_t adoptHandle(); bool getDoUnreg() { return fDoUnreg; } void setDoUnreg(bool doUnreg) { fDoUnreg = doUnreg; } bool getDoUnmarshallResult() { return fDoUnmarshallResult; } void setDoUnmarshallResult(bool flag) { fDoUnmarshallResult = flag; } ~STAFHandle(); protected: STAFHandle(STAFHandle_t handle, bool doUnreg) : fDoUnreg(doUnreg), fHandle(handle) { fDoUnmarshallResult = true; } bool fDoUnreg; STAFHandle_t fHandle; bool fDoUnmarshallResult; };
#include "STAF.h" #include "STAF_iostream.h" int main(void) { STAFHandlePtr handle; unsigned int rc = STAFHandle::create("MyApplication", handle); if (rc != 0) { cout << "Error registering with STAF, RC: " << rc << endl; return 1; } STAFResultPtr result = handle->submit("LOCAL", "PING", "PING"); cout << "PING RC: " << result->rc << ", Result: " << result->result << endl; STAFString semName("Sem name with spaces"); result = handle->submit("LOCAL", "SEM", "POST EVENT " + STAFHandle::wrapData(semName)); cout << "Sem Post RC: " << result->rc << ", Result: " << result->result << endl; // Send an Asynchronous request result = handle->submit("LOCAL", "SERVICE", "LIST", kSTAFReqQueueRetain); cout << "Service List Request Number: " << result->result << endl; return 0; }
The STAFObject class is used to represent a variety of structured data types. Unlike newer languages, C++ doesn't have a reflective type system allowing us to marshall arbitrary data structures. Therefore, we introduced a class which would allow us to provide general data structures which could be reflectively marshalled. Note, that all data structure methods are provided in the one STAFObject class.
All data types are created via static methods. Note the createReference() method. This allows you to create a reference to another object. This is important to note, as when you add an object to another object (for example, adding a string to a list) the recipient takes ownership of the object. Thus, if you want to keep ownership of the object, you will need to add a reference of the object to the other object, instead of the object itself.
Note, when a STAFObject is destructed, all objects it contains are destructed (recursively) as well. At this point, any references to objects that were contained in that data structure are now "dangling". The only valid methods for a "dangling" reference are isRef(), type(), and destruction.
typedef enum { kSTAFNoneObject = 0, kSTAFScalarStringObject = 1, kSTAFListObject = 2, kSTAFMapObject = 3, kSTAFMarshallingContextObject = 4 } STAFObjectType_t; typedef enum { kSTAFMarshallingDefaults = 0x00000000 } STAFObjectMarshallingFlags_t; typedef enum { kSTAFUnmarshallingDefaults = 0x00000000, kSTAFIgnoreIndirectObjects = 0x00000001 } STAFObjectUnmarshallingFlags_t; typedef STAFRefPtr<STAFObject> STAFObjectPtr; class STAFObject { public: // Creation methods static STAFObjectPtr createReference(const STAFObject &source); static STAFObjectPtr createReference(const STAFObjectPtr &source); static STAFObjectPtr createReference(STAFObject_t source); static STAFObjectPtr createNone(); static STAFObjectPtr createScalar(const STAFString &aString); static STAFObjectPtr createList(); static STAFObjectPtr createMap(); static STAFObjectPtr createMarshallingContext(); // General methods static bool isMarshalledData(const STAFString &aString); // General object methods STAFObjectType_t type(); unsigned int size(); bool isRef(); STAFObjectPtr reference(); STAFString asString(); STAFString marshall(unsigned int flags = kSTAFMarshallingDefaults); void marshall(STAFString &output, unsigned int flags = kSTAFMarshallingDefaults); // Note: This method always returns a Marshalling Context static STAFObjectPtr unmarshall(const STAFString &input, unsigned int flags = kSTAFUnmarshallingDefaults); // List methods void append(const STAFObjectPtr &objPtr); void append(const STAFString &aString); STAFObjectIteratorPtr iterate(); // Map methods bool hasKey(const STAFString &key); STAFObjectPtr get(const STAFString &key); void put(const STAFString &key, const STAFObjectPtr &objPtr); void put(const STAFString &key, const STAFString &aString); STAFObjectIteratorPtr keyIterator(); STAFObjectIteratorPtr valueIterator(); // Marshalling Context methods void setMapClassDefinition(const STAFMapClassDefinitionPtr &defPtr); STAFMapClassDefinitionPtr getMapClassDefinition(const STAFString &name); bool hasMapClassDefinition(const STAFString &name); STAFObjectIteratorPtr mapClassDefinitionIterator(); void setRootObject(const STAFObjectPtr &objPtr); STAFObjectPtr getRootObject(); // Destructor ~STAFObject(); };
This example submits a request to the PROCESS service to start a command and wait for it to complete. The result from this request is a marshalled map containing the process completion information. So this example demonstrates how to get the process return code from the result object (the root object of the marshalling context for the result).
#include "STAF.h" #include "STAF_iostream.h" int main(void) { STAFHandlePtr handlePtr; unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr); if (rc != 0) { cout << "Error registering with STAF, RC: " << rc << endl; return rc; } // Submit a request to start a process on a machine and wait for // it to complete. For this example, simply starting the process // on the local machine and listing and contents of C:/temp. STAFString machine = STAFString("local"); STAFString command = STAFString("dir C:/temp"); STAFResultPtr res = handlePtr->submit( machine, "PROCESS", "START COMMAND " + STAFHandle::wrapData(command) + " RETURNSTDOUT RETURNSTDERR WAIT"); if (res->rc != kSTAFOk) { cout << "PROCESS START request failed with RC=" << STAFString(res->rc) << " Result=" << res->result << endl; return res->rc; } // The result buffer from a successful PROCESS START WAIT request // returns a marshalled map containing the process completion information. // The marshalling context (e.g. the unmarshalled result) is available in // the 'resultContext' variable of the STAFResultPtr and the root object // for the marshalling context (which, in this case, is a map) is available // in the 'resultObj' variable of the STAFResultPtr. That is, // res->resultContext = STAFObject::unmarshall(res->result); // res->resultObj = res->resultContext->getRootObject(); // assuming auto-unmarshalling has not been disabled for the handle. // Print the result from the PROCESS START WAIT request in a // "Pretty Print" format using the asFormattedString() method cout << "Process Result (Pretty Printed): " << endl << res->resultContext->asFormattedString() << endl << endl; // Check if the process RC is 0 by getting the "rc" key from the // process completion map if (res->resultObj->get("rc")->asString() == "0") cout << "Process completed successfully" << endl; else cout << "Process failed with RC=" << res->resultObj->get("rc")->asString() << endl; return 0; }
The STAFObjectIterator class represents an iterator over other objects. You can not directly create a STAFObjectIterator. You obtain a STAFObjectIterator via calling an iteration method on a STAFObject. You can iterate over the items in a list, the keys in a map, the values in a map, and the names of the map class definitions in a marshalling context.
typedef STAFRefPtr<STAFObjectIterator> STAFObjectIteratorPtr; class STAFObjectIterator { public: bool hasNext(); STAFObjectPtr next(); ~STAFObjectIterator(); };
This example submits a request to the FS service to list the contents of a directory (in the long, detailed format). The result from this request is a marshalled list of maps, so this example demonstrates how to get list object from the result object and how to iterate through this list using the STAFObjectIterator class.
#include "STAF.h" #include "STAF_iostream.h" int main(void) { STAFHandlePtr handlePtr; unsigned int rc = STAFHandle::create("STAF/TestProcess", handlePtr); if (rc != 0) { cout << "Error registering with STAF, RC: " << rc << endl; return rc; } // Submit a request to the FS service to list the contents of a // directory in the long format with detailed information about // the entries in the directory STAFString directory = "C:/temp/staf"; STAFResultPtr res = handlePtr->submit( machine, "FS", "LIST DIRECTORY " + STAFHandle::wrapData(directory) + " LONG DETAILS"); if (res->rc != kSTAFOk) { cout << "FS LIST DIRECTORY " << directory << " LONG DETAILS request" << " failed with RC=" << STAFString(res->rc) << " Result=" << res->result << endl; return res->rc; } // The result buffer from a successful LIST DIRECTORY LONG DETAILS // request returns a marshalled list of maps containing information // about the entries in the directory. // The marshalling context (e.g. the unmarshalled result) is available in // the 'resultContext' variable of the STAFResultPtr and the root object // for the marshalling context (which, in this case, is a map) is available // in the 'resultObj' variable of the STAFResultPtr. That is, // res->resultContext = STAFObject::unmarshall(res->result); // res->resultObj = res->resultContext->getRootObject(); // assuming auto-unmarshalling has not been disabled for the handle. // Print the result in a "Pretty Print" format using the // asFormattedString() method cout << endl << "LIST DIRECTORY Result (Pretty Printed): " << endl << res->resultContext->asFormattedString() << endl << endl; // Iterate through the result object (which is a List containing a Map // for each entry in the directory). // Check if the directory contains a file named test.txt that // was last modified after 20060306-00:00:00. STAFObjectIteratorPtr iter = res->resultObj->iterate(); while (iter->hasNext()) { STAFObjectPtr entryMap = iter->next(); if (entryMap->get("name")->asString() == "test.txt") { if (entryMap->get("lastModifiedTimestamp")->asString() > "20060306-00:00:00") { cout << "Entry test.txt was modified at " << entryMap->get("lastModifiedTimestamp")->asString() << endl; } } } return 0; }
The STAFMapClassDefinition class is used to represent the metadata associated with a map class. Note, the order with which keys are added determines their display order.
typedef STAFRefPtr<STAFMapClassDefinition> STAFMapClassDefinitionPtr; class STAFMapClassDefinition { public: static STAFMapClassDefinitionPtr create(const STAFString &name); static STAFMapClassDefinitionPtr createReference( STAFMapClassDefinitionPtr source); STAFObjectPtr createInstance(); STAFMapClassDefinitionPtr reference(); void addKey(const STAFString &keyName); void addKey(const STAFString &keyName, const STAFString &displayName); void setKeyProperty(const STAFString &keyName, const STAFString &propName, const STAFString &propValue); STAFObjectIteratorPtr keyIterator(); STAFString name() const; STAFObjectPtr getMapClassDefinitionObject(); };
STAF externalizes three APIs to Rexx programs. These APIs allow you to register/unregister with STAF and submit service requests. These APIs are located in the RXStaf DLL. A Rexx program wishing to use these APIs must be sure to load them from the DLL, with the following two lines of code.
call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs" call STAFLoadFuncs
STAF also provides wrapper interfaces around the LOG, MONITOR, and RESPOOL services, as well as a small set of utility functions. These wrapper interfaces and utility functions are provided in Rexx Library files which have the extension .rxl. In order to incorporate these wrappers into your Rexx programs, you may do one of the following:
The names of these libraries are as follows:
The STAFRegister call is used by a Rexx program to register with STAF.
call STAFRegister handleName[, handleVarName]
`handleName` is the name by which you want this handle to be
known.
`handleVarName` is the name of the Variable which you want to
contain the handle that you will use on all other subsequent STAF calls.
If this parameter is not specified, the handle will be placed in the variable
STAFHandle.
call STAFRegister "MyHandleName", "MyHandle" say "My handle is:" MyHandle
or
call STAFRegister "MyHandleName" say "My handle is:" STAFHandle
The STAFUnRegister call is used by a Rexx program to unregister with STAF, which frees up any internal STAF resources used by the handle.
call STAFUnRegister [handle]
`handle` is the handle that you received on the call to
STAFRegister. If this parameter is not specified, the handle will be
retrieved from the STAFHandle variable.
call STAFUnRegister MyHandle
or
call STAFUnRegister
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
call STAFSubmit [handle,] where, service, request [, resultVarName]
`handle` is the handle you received on the call to STAFRegister.
If this parameter is not specified, the handle will be retrieved from the
STAFHandle variable.
`where` is the destination machine for the service request. This
should be either LOCAL or the name of a machine.
`service` is the name of the service to which you are submitting
the request.
`request` is the actual request that you are sending to the service.
`resultVarName` is the name of a variable that will contain the
result of the service request. If you specify `resultVarName`, you
must also specify `handle`
**Note: **The Rexx variable "STAFResult" will always be set to the result of the
service request. However, `resultVarName` allows you to get another
variable set if needed.
**Note: **To define whether a submit request should be synchronous or asynchronous,
the STAFSyncOption variable should be set prior to calling STAFSubmit (if it
is not set, the submit will be synchronous). The possible values for
STAFSyncOption are defined in STAFUtil.
/* myHandle was previously set by a call to STAFRegister */ someMachine = "testmach1" service = "PING" request = "PING" call STAFSubmit myHandle, someMachine, service, request, "SomeVar" say "STAFSubmit return code :" RESULT say "Service request result :" STAFResult say "Also service request result:" SomeVar
or
/* STAFHandle was previously set by a call to STAFRegister */ someMachine = "testmach1" service = "PING" request = "PING" call STAFSubmit someMachine, service, request say "STAFSubmit return code :" RESULT say "Service request result :" STAFResult call STAFSyncValues STAFSyncOption = STAFSync.!ReqRetain call STAFSubmit someMachine, service, request say "Asynchronous Service request number :" STAFResult
The STAFMon wrapper library provides a wrapper around the MONITOR service. The following functions are provided:
call STAFMonErrorText call STAFMonitor <Message>[, <Extra request data>]
`<Message>` is the message that you wish to log to the MONITOR
service.
`<Extra request data>` is any additional information that should
be passed along with the MONITOR service LOG request, such as additional
options like RESOLVEMESSAGE.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFMonErrorText do i = 1 to numLoops call STAFMonitor "Beginning of loop #"i ... ... end
The STAFLog wrapper library provides a wrapper around the LOG service. The following functions are provided:
call STAFLogErrorText call STAFInitLog <Reference>, <Log name>[, [Log type], [Monitor mask]] call STAFSetCurrentLog <Reference> call STAFLog <Log level>, <Message>[, <Extra request data>]
`<Reference>` is a text string of your desire that is used to
refer to a log. This facilitates switching between several different log
files.
`<Log name>` is the name of the log to which you wish to log
messages
`[Log type]` is the type of log. This should be one of GLOBAL,
MACHINE, or HANDLE. The default is MACHINE.
`[Monitor mask]` is a string which specifies which logging levels
should also be sent to the MONITOR service. The default is "FATAL ERROR
WARNING INFO STATUS"
`<Log level>` is the logging level of the message to be logged,
e.g. ERROR or WARNING.
`<Message>` is the message that you wish to log to the LOG
service.
`<Extra request data>` is any additional information that should
be passed along with the LOG service LOG request, such as additional
options like RESOLVEMESSAGE.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFLogErrorText call STAFInitLog "Public", "Testcase1", "MACHINE" call STAFInitLog "Private", "Testcase1", "HANDLE", "FATAL ERROR WARNING" call STAFSetCurrentLog "Public" call STAFLog "INFO", "Beginning testcase 1" ... call STAFSetCurrentLog "Private" call STAFLog "DEBUG", "Some private debug data"
The STAFPool wrapper library provides a wrapper around the RESPOOL service. The following functions are provided:
call STAFPoolErrorText call STAFPoolRequest <Pool name>, <Entry variable name>[, [Entry type], [Timeout]] call STAFPoolRelease <Pool name>, <Entry>[, <Force>]
`<Pool name>` is the name of the pool from which to request or
release an entry.
`<Entry variable name>` is the name of the variable in which to
place the actual requested entry's value.
`[Entry type]` is the type of entry requested. This should be
either FIRST or RANDOM. The default is RANDOM.
`[Timeout]` is an amount of time, in milliseconds, after which
the request should timeout. The default is to wait indefinitely.
`<Force>` specifies whether the entry should be forceable released.
This should be either FORCE or NOFORCE. The default is NOFORCE.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFPoolErrorText call STAFPoolRequest "Pool1", "Entry1" say "The entry obtained was:" Entry1 ... call STAFPoolRelease Entry1
The STAFUtil library provides some utilitiy functions for use by Rexx programs. The following functions are provided:
call STAFErrorText call STAFSyncValues wrappedData = STAFWrapData(<Data>) serviceResult = MakeSTAFResult(<Return code>[, <Result string>])
`<Data>` is the data for which to generate the colon delimited
version.
`<Return code>` is the service request's return code.
`<Result string>` is the service request's result string.
/* STAFHandle was set by a previous call to STAFRegister */ call STAFErrorText someData = "..." wrappedData = STAFWrapData(someData) /* The following would only be used by a service provider */ returnCode = 0 resultString = "..." serviceResult = MakeSTAFResult(returnCode, resultString) /* The following sets the STAFSyncOption variable to one of the STAFSync constants */ STAFSyncOption = STAFSync.!ReqRetain
For information on STAF's V3 support for the Java language, see the
[STAF Java User's Guide](http://staf.sourceforge.net/current/STAFJava.htm).
For information on STAF's V3 support for the Perl language, see the
[STAF Perl User's Guide](http://staf.sourceforge.net/current/STAFPerl.htm).
For information on STAF's V3 support for the Python language, see the
[STAF Python User's Guide](http://staf.sourceforge.net/current/STAFPython.htm).
For information on STAF's V3 support for the Tcl language, see the
[STAF Tcl User's Guide](http://staf.sourceforge.net/current/STAFTcl.htm).
Services are what provide all the capabilities of STAF.
When examining the syntax statements for each service, keep the following rules in mind.
For example,
LOG <GLOBAL | MACHINE | HANDLE> MESSAGE <Message>
indicates that option LOG is required and requires no value, option MESSAGE is required and requires a value, and exactly one of options GLOBAL, MACHINE, and HANDLE must be specified (and none of these options requires a value).
START COMMAND <Command> [WORKLOAD <Name>] [WAIT | ASYNC]indicates that option START is required and requires no value, option COMMAND is required and requires a value, option WORKLOAD is not required, but, if specified, requires a value, and one of the options WAIT and ASYNC may be specified, and neither requires a value.
Values for options may be specified in one of three ways.
MESSAGE Hello
MESSAGE "Hello World"
specifies the message
`Hello World`
MESSAGE "He said, \"What is that\""
specifies the message
`He said, "What is that"`
MESSAGE "c:\\MyApp\\Some directory with spaces"
specifies the message
`c:\MyApp\Some directory with spaces`
MESSAGE :11:Hello World
specifies the message
`Hello World`
MESSAGE :23:He said, "What is that"
specifies the message
`He said, "What is that"`
MESSAGE :35:c:\MyApp\Some directory with spaces
specifies the message
`c:\MyApp\Some directory with spaces`
The first two formats are most appropriate when using the STAF command line. The third is most appropriate and easiest from within programs using one of the supplied "wrapData" functions.
Note that when the value of an option is the same as the name of the option (or another supported option), the value must be distinguished as such either by quoting the value or by using the length delimited format. For example, if NAME is the name of an option and you also want to specify NAME as the value of the option, you should specify either NAME "NAME" or NAME :4:NAME.
Also, note that when you want to specify an empty string for the value of an option, you must use the third format (the length delimited format) because if you specify no value or "", then the STAF command parser thinks that no value was specified for the option and this will cause an "Invalid Request String" error (RC 7) if the option requires a value. For example,
MESSAGE :0:
Some command options allow their values to contain private data which will be handled by the service. This will be noted in the command options that allow it.
Private data is denoted by surrounding the private data, e.g. a password, between an opening privacy delimiter (!!@) and a closing privacy delimiter (@!!). For example, !!@password@!!. Because of this special significance of "!!@" and "@!!", if you do not want them to denote private data, use a caret (^), as an escape character for "!!@" and "@!!". Nested private data is allowed.
Using privacy delimiters indicates that the data enclosed between opening
and closing privacy delimiters should be protected so that if the private
data is displayed (e.g. in a
`LIST` or `QUERY` request),
any private data will be masked (replaced with asterisks).
The Process service's
`START` request handles
private data in the `COMMAND`, `PARMS`, and/or
`PASSWORD` options. If the command contains
a password (e.g. secret) that you want to keep private, enclose the
password between privacy delimiters as follows:
START SHELL COMMAND "C:/tests/myTest.exe -password !!@secret@!!"The above command would be displayed as "myTest.exe -password ************" in a
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"](#HDRMARSHALL) for more information on marshalled data structures
(and how they are mapped to the various languages that STAF supports).
In the simplest case, a service will return no value or a simple string (i.e.,
a string which is not the marshalled form of a data structure). In this case,
the service result will simple describe what the simple string contains. For
example, the HANDLE service documentation (see
[8.6.2, "CREATE"](#HDRHANDCRT)) indicates that when creating
a static handle the result buffer will simply contain the handle number that
was created.
If the service result contains the marshalled form of a data structure (which will now be referred to as "structured data"), the service documentation will describe it in terms of various structured content. The following are the types of structured data you will encounter.
In some cases, the structured data that is returned will be one of a number of possible values. In that case, you will see the "or" symbol, '|', used to list the possible choices. Two common cases are
<String> | <None>and
<Map:<Class>> | <None>
In the first case, this means that you will either get a string object
or the special
`<None>` object. In the second case, it means you will
either get an instance of the specified map class or the special `<None>`
object.
To further document map classes, each map class will have an associated table defining the metadata associated with the map class. The general format of this table is as follows.
[Table 4. Definition of map class <Map Class Name>]
Description: This contains a description of the map class
|Key Name||Display Name||Type||Format / Value|
|key1||Key 1 display name
|
(Key 1 short display name) if one is provided
|key1 type||key1 format/value information|
|...||...||...||...|
|keyX||Key X display name
|
(Key 1 short display name) if one is provided
|keyX type||keyX format/value information|
Notes:
Any notes about the definition of the map class.
The "Display Name" field shows the display name for each key, and, optionally, a "short" display name may be specified (in parenthesis) for a key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.
The "Format / Value" field is used predominantly to document the data
present in
`<String>` objects. When, the string will contain one of a limited
set of possible values, then the set of possible values will be listed in
this column. This might look like the following
'Default' | 'Enabled' | 'Disabled'
When the string will be in a particular format, the format will be documented in this column. For example, a common string value is a timestamp, which is documented in the "Format / Value" column as follows
<YYYYMMDD-HH:MM:SS>
All STAF services provide a HELP command that list basic service syntax information.
It is recommended that external service writers also provide a HELP facility.
The following table contains a brief description of the services provided
with STAF. The chapter that follows provides a detailed explanation of each
service.
|Service name||Description String Representation|
|CONFIG||Provides a way to save the current STAF configuration|
|DELAY||Provides a means to sleep a specified amount of time|
|DIAG||Provides diagnostics services|
|ECHO||Echos back a supplied message|
|FS||Provides file transfer between systems|
|HANDLE||Provides information about existing STAF handles|
|HELP||Provides help on STAF error codes|
|LIFECYCLE||Runs STAF service requests when STAFProc starts up or shuts down|
|LOG||Provides robust logging services|
|MISC||Handles miscellaneous commands such as displaying the version of STAF that is currently running|
|MONITOR||Provides a means to monitor the status of running programs|
|PING||Provides a simple is-alive message|
|PROCESS||Handles starting, stopping, and querying processes|
|QUEUE||Interacts with STAF queues|
|RESPOOL||Manages pools of named elements|
|SEM||Provides named event and mutex semaphores|
|SERVICE||Provides information on available STAF services|
|SHUTDOWN||Provides a means to shutdown STAF and register for shutdown notifications|
|TRACE||Provides tracing information for STAF services|
|TRUST||Interfaces with STAF's security|
|VAR||Allows inspection and manipulation of STAF variable pools|
|ZIP||Provides a means to zip/unzip/list/delete PKZip/WinZip compatible archives|
The foundation services that STAF provides are described in this chapter. For each service the following sections are listed.
The CONFIG service is one of the internal STAF services. It provides a way to save the current STAF configuration to a file, reflecting any changes made since STAFProc was started.
SAVE will display the current STAF configuration data or save it to a file, reflecting any changes made since STAFProc was started. This includes any dynamic changes made by:
SAVE [FILE <Name>] [VARS <Current | Startup>]
`FILE` specifies that name of a file where you want to save
the current STAF configuration data. This file cannot already exist.
This option will resolve variables.
`VARS` specifies which STAF system and shared variables to save.
This option will resolve variables. Recognized values are the following:
This command requires trust level 3.
However, if the
`DEFAULTAUTHPASSWORD` has been set for the
`PROCESS` service, this command requires trust level 5.
All return codes from SAVE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, if the
`FILE` option is not specified,
the result buffer will contain the current STAF configuration data.
On successful return, if the
`FILE` option is specified,
the result buffer will contain no data and the current STAF configuration data
will be saved to the specified file name.
**Syntax:**
`SAVE FILE /tmp/mySTAF.cfg`
**Results:**
**Syntax:**
`SAVE FILE /tmp/mySTAF.cfg VARS Startup`
**Results:**
**Syntax:**
`SAVE`
**Results:**
# --------------------------------------------------------------------- # STAF Configuration File # --------------------------------------------------------------------- # --------------------------------------------------------------------- # Tracing # --------------------------------------------------------------------- TRACE ENABLE ALL SERVICES TRACE ENABLE TRACEPOINTS "ERROR WARNING DEPRECATED DEBUG" # --------------------------------------------------------------------- # Variables # --------------------------------------------------------------------- SET SYSTEM VAR STAFDemo/JavaAppClassPath=C:\STAF\lib\JSTAF.zip;C:\STAF\samples\demo\STAFDemo.jar; SET SYSTEM VAR STAFDemo/JavaAppCommand=javaw.exe # --------------------------------------------------------------------- # Operational Parameters # --------------------------------------------------------------------- SET MAXQUEUESIZE 1000 SET MAXRETURNFILESIZE 5120 # --------------------------------------------------------------------- # Interfaces (Connection Providers) # --------------------------------------------------------------------- INTERFACE ssl LIBRARY STAFTCP OPTION ConnectTimeout=5000 OPTION Port=6550 \ OPTION Protocol=IPv4 OPTION Secure=Yes INTERFACE tcp LIBRARY STAFTCP OPTION ConnectTimeout=5000 OPTION Port=6500 \ OPTION Protocol=IPv4 OPTION Secure=No # --------------------------------------------------------------------- # Trust Levels # --------------------------------------------------------------------- TRUST LEVEL 5 MACHINE *://client1.mycompany.com TRUST LEVEL 5 MACHINE *://client2.mycompany.com TRUST LEVEL 5 MACHINE *://server1.mycompany.com TRUST LEVEL 5 MACHINE local://local # --------------------------------------------------------------------- # Service Loader Service Registrations # --------------------------------------------------------------------- SERVICELOADER LIBRARY STAFDSLS # --------------------------------------------------------------------- # Service Registrations # --------------------------------------------------------------------- SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar \ OPTION JVMName=STAX OPTION J2=-Xmx512m \ PARMS "CLEARLOGS Enabled FILECACHEALGORITHM LFU" SERVICE EVENT LIBRARY JSTAF EXECUTE C:\STAF\services\STAFEvent.jar \ OPTION JVMName=STAX
The DELAY service is an internal STAF service. A DELAY request simply
sleeps for a specified amount of time before returning to the calling program.
DELAY <Number>[s|m|h|d|w]
`DELAY` specifies an amount of time to sleep. The time duration
may be expressed in milliseconds, seconds, minutes, hours, days, weeks, or years.
Its format is <Number>[s|m|h|d|w], where <Number> is an integer >= 0 and
indicates milliseconds unless one of the following case-insensitive suffixes
is specified:
This command requires trust level 2.
All return codes from DELAY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
DELAY 100
DELAY 5s
Note that this is equivalent to:
DELAY 5000
DELAY 1m
Note that this is equivalent to:
DELAY 60000
DELAY 2h
The Diagnostics service, called DIAG, is an internal STAF service which lets you record and list diagnostics data. It provides the following commands:
The purpose of the DIAG service is to allow you to record diagnostics data consisting of a trigger and its source. The number of times each trigger/source combination occurs is accumulated by the DIAG service. You may list the trigger(s)/source(s) and their counts, as well as clear all data from the diagnostics map.
**Note: **The commands for the DIAG service and their result formats are
subject to change.
RECORD writes diagnostics data (a trigger and its source) to a diagnostics map where a count is kept of the number of times each unique trigger/source combination occurs.
**Note: **You must enable diagnostics before you can record diagnostics
data.
RECORD TRIGGER <Trigger> SOURCE <Source>
`TRIGGER` specifies the trigger (event) that you want
to record in the diagnostics map. You can specify anything for
the trigger, but we recommend that you don't specify a semi-colon (;)
in the trigger to make it easier to parse the list output which uses
a semi-colon to separate fields. This option will resolve variables.
`SOURCE` specifies information about the originator of
the trigger. It is also recorded in the diagnostics map. For example,
you may want to include the originating machine's name, handle, and
handle name. This option will resolve variables.
This command requires trust level 3.
**Note: **This command is only valid if submitted to the local machine,
not to remote machines.
All return codes from RECORD are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
If successful, the result buffer will contain information
about the
`LIST` request based on the options specified:
The result buffer for a
`LIST` request (without specifying options
`TRIGGER, SOURCE, TRIGGERS, SOURCES, or SETTINGS`) will contain a
marshalled `<Map:STAF/Service/Diag/AllDiagInfo>`
representing the diagnostics information for all of the unique
trigger/source combinations.
The maps are defined as follows:
[Table 6. Definition of map class STAF/Service/Diag/AllDiagInfo]
Description: This map class represents the diagnostics
information for all of the unique trigger/source combinations.
|Key Name||Display Name||Type||Format / Value|
|fromTimestamp||From Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|toTimestamp||To Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|elapsedTime||Elapsed Time|<String> | <None>
<[H]HH:MM:SS>
|numberOfTriggers||Number of Triggers|<String>
|
|
|numberOfSources||Number of Sources|<String>
|
|
|comboList||Trigger/Source Combinations|<List> of <Map:STAF/Service/Diag/ComboCount>
|
|
Notes:
[Table 7. Definition of map class STAF/Service/Diag/ComboCount]
Description: This map class represents a unique trigger/source
combination and a count of how many times it was recorded.
|Key Name||Display Name||Type||Format / Value|
|trigger||Trigger|<String>
|
|
|source||Source|<String>
|
|
|count||Count|<String>
|
|
Notes:
"Count" specifies the number of times each trigger/source
combination has been recorded.
The result buffer for a
`LIST TRIGGERS` request will contain a
marshalled `<Map:STAF/Service/Diag/TriggersInfo>`
representing the diagnostics information for all of the unique triggers
that have been recorded.
The maps are defined as follows:
[Table 8. Definition of map class STAF/Service/Diag/TriggersInfo]
Description: This map class represents the diagnostics
information for all of the unique triggers that have been recorded.
|Key Name||Display Name||Type||Format / Value|
|fromTimestamp||From Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|toTimestamp||To Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|elapsedTime||Elapsed Time|<String> | <None>
<[H]HH:MM:SS>
|numberOfTriggers||Number of Triggers|<String>
|
|
|triggerList||Triggers|<List> of <Map:STAF/Service/Diag/TriggerCount>
|
|
Notes:
[Table 9. Definition of map class STAF/Service/Diag/TriggerCount]
Description: This map class represents a trigger
and a count of how many times it was recorded.
|Key Name||Display Name||Type||Format / Value|
|trigger||Trigger|<String>
|
|
|count||Count|<String>
|
|
Notes:
"Count" specifies the number of times a trigger has been recorded.
The result buffer for a
`LIST SOURCES` request will contain a
marshalled `<Map:STAF/Service/Diag/SourcesInfo>`
representing the diagnostics information for all of the unique sources
that have been recorded.
The maps are defined as follows:
[Table 10. Definition of map class STAF/Service/Diag/SourcesInfo]
Description: This map class represents the diagnostics
information for all of the unique sources that have been recorded.
|Key Name||Display Name||Type||Format / Value|
|fromTimestamp||From Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|toTimestamp||To Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|elapsedTime||Elapsed Time|<String> | <None>
<[H]HH:MM:SS>
|numberOfSources||Number of Sources|<String>
|
|
|sourceList||Sources|<List> of <Map:STAF/Service/Diag/SourceCount>
|
|
Notes:
[Table 11. Definition of map class STAF/Service/Diag/SourceCount]
Description: This map class represents a source
and a count of how many times it was recorded.
|Key Name||Display Name||Type||Format / Value|
|source||Source|<String>
|
|
|count||Count|<String>
|
|
Notes:
"Count" specifies the number of times a source has been recorded.
The result buffer for a
`"LIST TRIGGER <Trigger>"` request
will contain a marshalled
`<Map:STAF/Service/Diag/TriggerInfo>`
representing the diagnostics information for the unique sources
that have been recorded for the specified trigger.
The maps are defined as follows:
[Table 12. Definition of map class STAF/Service/Diag/TriggerInfo]
Description: This map class represents the diagnostics
information for the specified trigger.
|Key Name||Display Name||Type||Format / Value|
|fromTimestamp||From Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|toTimestamp||To Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|elapsedTime||Elapsed Time|<String> | <None>
<[H]HH:MM:SS>
|trigger||Trigger|<String>
|
|
|numberOfSources||Number of Sources|<String>
|
|
|sourceList||Sources|<List> of <Map:STAF/Service/Diag/SourceCount>
|
|
Notes:
The result buffer for a
`"LIST SOURCE <Source>"` request
will contain a marshalled
`<Map:STAF/Service/Diag/SourceInfo>`
representing the diagnostics information for all of the unique triggers
that have been recorded for the specified source.
The maps are defined as follows:
[Table 13. Definition of map class STAF/Service/Diag/SourceInfo]
Description: This map class represents the diagnostics
information for the specified source.
|Key Name||Display Name||Type||Format / Value|
|fromTimestamp||From Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|toTimestamp||To Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|elapsedTime||Elapsed Time|<String> | <None>
<[H]HH:MM:SS>
|source||Source|<String>
|
|
|numberOfTriggers||Number of Triggers|<String>
|
|
|triggerList||Triggers|<List> of <Map:STAF/Service/Diag/TriggerCount>
|
|
Notes:
The result buffer for a
`"LIST SETTINGS"` request
will contain a marshalled
`<Map:STAF/Service/Diag/Settings>`
representing the current operational settings for the DIAG service.
The maps are defined as follows:
[Table 14. Definition of map class STAF/Service/Diag/Settings]
Description: This map class represents the current
operational settings for the DIAG service.
|Key Name||Display Name||Type||Format / Value|
|diagnostics||Diagnostics|<String>
'Enabled' | 'Disabled'.
|lastResetTimestamp||Last Reset / First Enabled|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|lastDisabledTimestamp||Last Disabled|<String>
<YYYYMMDD-HH:MM:SS>
Notes:
**Syntax:** `LIST`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Date-Time : 20040926-12:20:05 Elapsed Time : 00:05:01 Number of Triggers : 3 Number of Sources : 2 Trigger/Source Combinations: [ { Trigger: MYSERVICE QUERY Source : MyApp;machine1.austin.ibm.com;77 Count : 10 } { Trigger: MYSERVICE QUERY Source : myApp2;machine1.austin.ibm.com;97 Count : 7 } { Trigger: SAMPLE1 QUERY Source : myApp2;machine1.austin.ibm.com;97 Count : 4 } { Trigger: MYSERVICE LIST Source : myApp2;machine1.austin.ibm.com;97 Count : 1 } ] }
**Syntax:** `LIST SORTBYTRIGGER`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Date-Time : 20040926-12:21:09 Elapsed Time : 00:06:05 Number of Triggers : 3 Number of Sources : 2 Trigger/Source Combinations: [ { Trigger: MYSERVICE LIST Source : myApp2;machine1.austin.ibm.com;97 Count : 1 } { Trigger: MYSERVICE QUERY Source : MyApp;machine1.austin.ibm.com;77 Count : 10 } { Trigger: MYSERVICE QUERY Source : myApp2;machine1.austin.ibm.com;97 Count : 7 } { Trigger: SAMPLE1 QUERY Source : myApp2;machine1.austin.ibm.com;97 Count : 4 } ] }
**Syntax:** `LIST TRIGGERS SORTBYTRIGGER`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Timestamp : 20040926-12:28:20 Elapsed Time : 00:13:16 Number of Triggers: 3 Triggers : [ { Trigger: MYSERVICE LIST Count : 1 } { Trigger: MYSERVICE QUERY Count : 17 } { Trigger: SAMPLE1 QUERY Count : 4 } ] }
**Syntax:** `LIST SOURCES`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Date-Time : 20040926-12:32:53 Elapsed Time : 00:17:49 Number of Sources: 2 Sources : [ { Source: MyApp;machine1.austin.ibm.com;77 Count : 10 } { Source: MyApp2;machine1.austin.ibm.com;97 Count : 12 } ] }
**Syntax:** `LIST TRIGGER "MYSERVICE QUERY" SORTBYSOURCE`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Date-Time : 20040926-12:36:18 Elapsed Time : 00:21:14 Trigger : MYSERVICE QUERY Number of Sources: 2 Sources : [ { Source: MyApp;machine1.austin.ibm.com;77 Count : 10 } { Source: MyApp2;machine1.austin.ibm.com;97 Count : 7 } ] }
**Syntax:** `LIST SOURCE "MyApp2;machine1.austin.ibm.com;97"`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
{ From Date-Time : 20040926-12:15:04 To Date-Time : 20040926-12:40:08 Elapsed Time : 00:25:04 Source : MyApp2;machine1.austin.ibm.com;97 Number of Triggers: 3 Triggers : [ { Trigger: MYSERVICE QUERY Count : 7 } { Trigger: SAMPLE1 QUERY Count : 4 } { Trigger: MYSERVICE LIST Count : 1 } ] }
**Syntax:** `LIST SETTINGS`
**Results:** If the request is issued from the
command line, the result, in default format, could look like:
Diagnostics : Enabled Last Reset / First Enabled: 20040926-12:15:04 Last Disabled : 20040926-12:14:53
RESET allows you to clear all data from the diagnostics map.
RESET FORCE
`FORCE` is a confirmation that you want to clear all data.
This command requires trust level 4.
All return codes from RESET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
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"](#HDRRETCODE).
The result buffer will contain no data on a successful return from a DISABLE command.
The ECHO service is an internal STAF service. ECHO provides a
similar service as PING. The difference is that ECHO allows you
to specify the return string that STAFProc will return.
ECHO can also be used to determine if STAFProc is up and running
and accessible.
ECHO <Message>
**Note: **ECHO does not follow the request parsing rules described earlier.
Any text after the ECHO command will be returned verbatim.
This command requires trust level 2.
All return codes from ECHO are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain
`<Message>` on a successful
return from an ECHO command.
Goal: Have STAFProc return the string Hello World to you.
ECHO Hello World
The File System service, called FS, allows you to interface with the file system on STAF Clients. It provides the following commands.
In the descriptions of these commands, three different options are used to
refer to objects in the file system.
`FILE` is used when the object in
question must be a file. `DIRECTORY` is used when the object in
question must be a directory. `ENTRY` is used when the object in
question may be any object in the file system.
Some of these commands (e.g. COPY DIRECTORY, LIST DIRECTORY, DELETE) allow match patterns to be specified. These patterns recognize two special characters, '*' and '?', as wildcards:
COPY FILE allows you to copy one file between machines, or to another location on the same machine.
COPY FILE <FileName> [TOFILE <Name> | TODIRECTORY <Name>] [TOMACHINE <Machine>] [TEXT [FORMAT <Format>]] [FAILIFEXISTS | FAILIFNEW]
`FILE` specifies the name of the file to copy. This option will resolve variables.
`TOFILE` specifies the name of the file to create. The directory path
specified must already exist on the machine where the file is being copied to, or
else the copy request will fail with RC 17 (File open error).
If neither `TOFILE` nor `TODIRECTORY` is specified, this
defaults to the same, unresolved, name as specified in `FILE`.
This option will resolve variables. These variables will be resolved on the target machine.
`TODIRECTORY` specifies the name of the directory to copy the file to.
The name of the "to file" will be the same as specified in `FILE`.
This directory must already exist on the target machine.
This option will resolve variables. These variables will be resolved on the target machine.
`TOMACHINE` specifies the machine to copy the file to. This
defaults to the machine which originated the request.
Specifying ` local `indicates to copy the file to the same
machine that the file is being copied from.
Note that specifying ` local `instead of the from machine's host name can
significantly improve performance, especially if your TCP network performance
is slow. This is because ` local `(or ` local://local`) indicates
to use the local network interface versus specifying a TCP host name or IP address
which indicates to use the TCP network interface. This option will resolve variables.
`TEXT` specifies to convert line-ending characters in the file being
copied as specified via the `FORMAT` option and to perform codepage conversion.
This option should only be specified for a text file, not a binary file.
`FORMAT` specifies the end-of-line character(s) to use. This option will resolve variables.
See [8.5.6, "GET FILE"](#HDRFSGETFILE) 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"](#HDROPPARMS) for
more information on the ` STRICTFSCOPYTRUST `operational parameter.
All return codes from COPY FILE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a COPY FILE command.
In the following examples, assume the command is being submitted locally from machine TestSrv1.
**Syntax:** `COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1`
**Syntax:** Note that both of these `COPY FILE` examples are equivalent.
COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT FORMAT Native
**Syntax:** `COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " "`
In the following examples, assume the command is being submitted to machine Client1 from machine TestSrv1.
**Syntax:** `COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log `
**Syntax:** `COPY FILE d:\WebTests\Logs\WebTC1.log TODIRECTORY h:\Logs TOMACHINE LogSrv`
**Syntax:** `COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local`
**Syntax:** `COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT`
COPY DIRECTORY allows you to copy selected files from a directory or entire
directories (including subdirectories if needed) between machines, or to another
directory on the same machine. It allows you to specify wildcards (e.g. *, ?)
in the
`NAME` and/or `EXT` options to match patterns in file
names to be copied from the specified directory and its subdirectories too if
the `RECURSE` option is specified.
COPY DIRECTORY <Name> [TODIRECTORY <Name>] [TOMACHINE <Machine>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] [TEXTEXT <Pattern>... [FORMAT <Format>]] [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]] [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
`DIRECTORY` specifies the name of the source directory to copy. This option will resolve variables.
`TODIRECTORY` specifies the name of the destination directory. This defaults
to the same, unresolved, name as specified in `DIRECTORY`. This option will resolve variables. These
variables will be resolved on the target machine.
`TOMACHINE` specifies the machine to copy the directory and its contents to.
This defaults to the machine which originated the request.
Specifying `local` indicates to copy the directory and its contents to the same
machine that the directory is being copied from.
Note that specifying ` local `instead of the from machine's host name can
significantly improve performance, especially if your TCP network performance
is slow. This is because ` local `(or ` local://local`) indicates
to use the local network interface versus specifying a TCP host name or IP address
indicates to use the TCP network interface. This option will resolve variables.
`NAME` specifies a pattern used to match the name of files in the specified
directory (and files in its subdirectories, if `RECURSE` is specified).
Only the files whose names match this pattern will be copied.
Match patterns may be specified using special characters '*' and/or '?' as wildcards.
The default pattern is "*". This option will resolve variables.
`EXT` specifies a pattern used to match the extension of files in the specified
directory (and files in its subdirectories, if `RECURSE` is specified).
Only the files whose extensions match this pattern will be copied.
Match patterns may be specified using special characters '*' and/or '?' as wildcards.
The default pattern is "*". This option will resolve variables.
**Note: **The COPY DIRECTORY command recognize the "name" ( `NAME`)
portion of a filename as the character(s) that precede a period (or the entire
filename if it does not include a period) and the "extension" ( `EXT`)
portion of a filename are character(s) that follow a period.
For example, for filename myfile.txt the "name" portion is "myfile" and
the "extension" portion is "txt". To match filenames whose name begins
with "my" and whose extension is "txt", you could specify options
`NAME my* EXT txt`.
`CASESENSITIVE` specifies that the patterns specified by `NAME`,
`EXT`, and `TEXTEXT` are to be matched in a case sensitive manner.
`CASEINSENSITIVE` specifies that the patterns specified by `NAME`,
`EXT`, and `TEXTEXT` are to be matched in a case insensitive manner.
**Note: **If neither `CASESENSITIVE` nor `CASEINSENSITIVE` is
specified, the default is determined by the operating system -- unix systems
default to `CASESENSITIVE`, all others default to `CASEINSENSITIVE`.
Options `CASESENSITIVE` and `CASEINSENSITIVE` only have an effect if
you also specify a pattern to match using at least one of the following options:
`NAME`, `EXT`, or `TEXTEXT`.
`TEXTEXT` specifies a pattern used to match the extension of text files being
copied. The files whose extensions match this pattern should contain text, not binary
data. The line-ending characters in the files being copied whose extensions match
this pattern will be converted as specified via the `FORMAT` option and
codepage conversion will be performed.
Multiple `TEXTEXT` patterns are handled as an "or" condition.
Match patterns may be specified using special characters '*' and/or '?' as wildcards.
This option will resolve variables.
`FORMAT` specifies the end-of-line character(s) to use. This option will resolve variables.
See [8.5.6, "GET FILE"](#HDRFSGETFILE) for more information on available formats.
`RECURSE` specifies that the subdirectories in `DIRECTORY` will be
recursively copied.
`KEEPEMPTYDIRECTORIES` specifies that the empty directories are also to be
created in the `TODIRECTORY` on the target. The default behavior is to prune
the empty directories while copying files.
`ONLYDIRECTORIES` specifies that the directory (empty directories and no files
copied) structure is to be created in the `TODIRECTORY` on the target machine.
Using the `NAME`, `EXT`, `CASESENSITIVE` and
`CASEINSENSITIVE` options with the `ONLYDIRECTORIES` option will be
ignored as no files will be copied.
`IGNOREERRORS` specifies that errors encountered copying entries should not
be returned. By default, all errors encountered while copying entries will be returned
in the result buffer.
`FAILIFEXISTS` specifies that the copy should fail if
`TODIRECTORY` already exists. The default is to copy over the directory contents
if it exists.
`FAILIFNEW` specifies that the copy should fail if `TODIRECTORY`
does not already exist. The default is to create the directory if it does not exist if
at least one file is copied.
This command requires trust level 4 as follows:
An exception to these trust requirements is if the
` orgMachine `is the same
as the ` toMachine `and the ` STRICTFSCOPYTRUST `operational setting
is disabled (which it is by default), then the ` toMachine `does not have to
give trust level 4 to the ` sourceMachine`. See [4.7, "Operational parameters"](#HDROPPARMS) for
more information on the ` STRICTFSCOPYTRUST `operational parameter.
All return codes from COPY DIRECTORY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
[Table 15. Definition of map class STAF/Service/FS/ErrorInfo]
Description: This map class represents error information for an entry
in a directory.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|rc||RC|<String>
|
|
|osRC||OS RC|<String> | <None>
|
|
Notes:
For example, if a copy directory request is submitted from the command line, and two errors occurred during the copy, the result, in table format, could look like:
Name RC OS RC ------------------- -- ------ c:\tmp\project.htm 17 <None> c:\tmp\project5.xml 10 32
In the following examples, assume the command is being issued locally from machine TestSrv1.
In the following examples, assume the command is being issued locally from machine TestSrv1 and the following directory structures exist under the c:/testcase directory:
c:\testcase c:\testcase\error.txt c:\testcase\web.exe c:\testcase\web.txt c:\testcase\web.xml c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2 c:\testcase\subdir\subdir_2\readme.txt
The expected result is that the following entries exist on machine Client1:
c:\testcase c:\testcase\error.txt c:\testcase\web.exe c:\testcase\web.txt c:\testcase\web.xml c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2 c:\testcase\subdir\subdir_2\readme.txt
The expected result is that the following entries were created on machine Client1:
c:\testcase c:\testcase\subdir c:\testcase\subdir\subdir_1 c:\testcase\subdir\subdir_2
**Syntax:**
Note that both of these `COPY DIRECTORY` examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1 NAME web TEXTEXT txt TEXTEXT xml COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1 NAME web TEXTEXT txt TEXTEXT xml FORMAT Native
The expected result is that the following entries were created on machine Client1. Note that error.txt was not copied since its name is not 'web'.
/testcase /testcase/web.exe /testcase/web.txt /testcase/web.xml
**Syntax:**
Note that both of these `COPY DIRECTORY` examples are equivalent.
COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1 EXT txt TEXTEXT "*" RECURSE COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1 EXT txt TEXTEXT txt FORMAT Native RECURSE
The expected result is that the following entries were created on machine Client1.
/testcase /testcase/error.txt /testcase/subdir /testcase/subdir/subdir_2 /testcase/subdir/subdir_2/readme.txt
In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.
MOVE FILE allows you to rename a file or move files from one directory to another directory on a machine.
MOVE FILE <Name> <TOFILE <Name> | TODIRECTORY <Name>>
`FILE` specifies the name of the file to move/rename.
You may specify wildcards using '*' to move multiple files from one directory
to another directory. This option will resolve variables.
`TOFILE` specifies the new name of the file.
The directory path specified must already exist, or else the move request
will fail (e.g. if specify C:\Tests\Test1\test1.exe, directory C:\Tests\Test1
must already exist). Existing destination files will be overwritten. This option will resolve variables.,
`TODIRECTORY` specifies the name of the directory to move the
file(s) to. This directory must already exist.
Existing destination files will be overwritten. This option will resolve variables.
This command requires trust level 4
All return codes from MOVE FILE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain no data or may contain
information about the files moved (e.g. if a wildcard is specified in
the
`FILE` value).
If the request failed, the result buffer may contain information about
the error.
**Syntax:** `MOVE FILE C:\testcase\test1.exe TOFILE C:\testcase\test2.exe`
**Syntax:** `MOVE FILE C:\testcase\test1.exe TODIRECTORY C:\testcase\TestDir`
**Syntax:** `MOVE FILE C:\testcase\test*.txt TODIRECTORY D:\Saved_Tests`
**Syntax:** `MOVE FILE {STAF/Config/BootDrive}\startup.cmd TODIRECTORY E:\`
**Syntax:** `MOVE FILE /tmp/testcase/test1.sh TOFILE /opt/MyTests/test1.sh`
MOVE DIRECTORY allows you to rename a directory on a machine.
MOVE DIRECTORY <Name> TODIRECTORY <Name>
`DIRECTORY` specifies the name of the directory to move. This option will resolve variables.
`TODIRECTORY` specifies the name of the directory to move the
directory to. If this directory does not already exist, the directory will
be renamed to it. If this directory already exists, the directory will be moved
to a new subdirectory within it.
The path to the directory must already exist, or else the move request will
fail (e.g. if specify C:\Tests\Test1, directory C:\Tests must already exist).
This option will resolve variables.
This command requires trust level 4
All return codes from MOVE DIRECTORY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain no data or may contain information about the files moved. If the request failed, the result buffer may contain information about the error.
**Syntax:** `MOVE DIRECTORY C:\testcase TODIRECTORY C:\MyTestcases`
**Syntax:** `MOVE DIRECTORY C:\testcase\Test1 TODIRECTORY "D:\My Testcases"`
If directory "D:\My Testcases" exists, the directory will be renamed to "D:\My Testcases\Test1" (assuming a directory named Test1 does not already exist in "D:\My Testcases"). If directory "C:\My Testcases" does not exist, the directory will be renamed to "D:\My Testcases".
**Syntax:** `MOVE DIRECTORY {STAF/Config/BootDrive}/mydir TODIRECTORY E:\`
GET FILE retrieves the contents of a text file.
Notes:
GET FILE <FileName> [[TEXT | BINARY] [FORMAT <Format>]]
`FILE` specifies the name of the text file to get. This option will resolve variables.
`TEXT` specifies to convert line-ending characters in the file being
retrieved as specified via the `FORMAT` option and to perform codepage conversion.
This option should only be specified for a text file, not a binary file.
This is the default.
`BINARY` specifies to retrieve the contents of the file in binary.
`FORMAT` specifies the format of the file's contents. This option will resolve variables.
This command requires trust level 4.
All return codes from GET FILE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
Notes:
On successful return, the result buffer will contain the contents of the specified file.
GET FILE {STAF/Config/BootDrive}/CONFIG.SYS GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT FORMAT Native
GET FILE c:/testcases/test1.cmp BINARY GET FILE c:/testcases1/test1.cmp BINARY FORMAT HEX
GET ENTRY retrieves an attribute of a file system entry, such as its type, size, last modification time, link target, or checksum.
GET ENTRY <Name> <TYPE | SIZE | MODTIME | LINKTARGET | CHECKSUM [<Algorithm>]>
`ENTRY` specifies the name of the file system entry for which to
retrieve an attribute. This option will resolve variables.
`TYPE` specifies the type of the file system entry should be
retrieved.
`SIZE` specifies the size of the file system entry should be
retrieved. Note that if the file system entry is a directory, it retrieves
the size of only the directory entry, not the total size of all the entries
within the directory. To get the total size of a directory, use the FS
service's LIST DIRECTORY request with the SUMMARY option.
`MODTIME` specifies the last modification time of the file
system entry should be retrieved.
`LINKTARGET` specifies the link target for the file system
entry should be retrieved. If the file system entry is not a symbolic link,
`<None>` will be returned.
`CHECKSUM` specifies to calculate a fixed-size checksum of the
file system entry and return its value in a hexadecimal form.
Getting a file's checksum is a simple way to check to see that a file has
not been tampered with or to verify that a file has been downloaded or
copied correctly. You may optionally specify the cryptographic hashing
algorithm used to produce a unique checksum for any file. The following
algorithms are supported: MD2, MD4, MD5, RIPEMD160, SHA, SHA1
(case-insensitive). The default is MD5.
Note that SHA1 (160 bits) and RIPEMD160 (160 bits) are considered more
current and more secure than MD5 (128 bits), but MD5 is still widely used.
You cannot retrieve the checksum for a directory. This option will resolve variables.
If the file system entry is a symbolic link, information about the entry referenced by the link (e.g. the link target) will be provided. This includes the type, size, last modification time, or checksum of the link target.
This command requires trust level 2.
All return codes from GET ENTRY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the contents of the result buffer will depend on the attribute type requested.
[Table 16. File System Entry Types Reference]
|Type identifier||Description|
|F||File|
|D||Directory|
|P||Pipe|
|S||Socket|
|B||Block device|
|C||Character device|
|O||Other undefined type|
|?||Unknown type|
[Table 17. Definition of map class STAF/Service/FS/SizeInfo]
Description: This map class represents the 64-bit size of
the file system entry.
|Key Name||Display Name||Type||Format / Value|
|size||Size|<String>
|
|
|upperSize||Upper 32-bit Size|<String>
|
|
|lowerSize||Lower 32-bit Size|<String>
|
|
Notes:
The "Size" value is the 64-bit size of the file system entry in bytes.
The "Upper 32-bit Size" and "Lower 32-bit Size" values are provided for
historical reasons as the "Size" value wasn't added until STAF V3.3.5.
They represent the upper 32-bits of the size and the lower 32-bits of
the size in bytes. Note that if the size < 4,294,967,296 bytes (aka 4G),
the upper 32-bit size will be 0 and the lower 32-bit size will be the
same as the size field.
F
20040512-18:07:52
Size : 340488704 Upper 32-bit Size: 0 Lower 32-bit Size: 340488704
Size : 4800000000 Upper 32-bit Size: 1 Lower 32-bit Size: 505032704
/usr/local/staf/bin/STAF
3F6C5A05CA3E7422C57851CAFA223FA2
83B4F130E213D61AE6BB393FA9AEE711CC9FF91B
QUERY retrieves all associated attributes of a file system entry.
Note that if the file system entry queried is a symbolic link, information about the entry referenced by the link will be retrieved.
QUERY ENTRY <Name>
`ENTRY` specifies the name of the file system entry to query.
This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer for a
`QUERY` request
will contain a marshalled `<Map:STAF/Service/FS/QueryInfo>`
representing information about the file system entry attributes.
The map is defined as follows:
[Table 18. Definition of map class STAF/Service/FS/QueryInfo]
Description: This map class represents information about
a file system entry attributes.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|linkTarget||Link Target|<String> | <None>
|
|
|type||Type|<String>
|
|
|size||Size|<String>
|upperSize||Upper 32-bit Size|<String>
|
|
|lowerSize||Lower 32-bit Size|<String>
|
|
|lastModifiedTimestamp||Modified Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
Notes:
The values for "Link Target", "Type", "Size", "Upper 32-bit Size", "Lower 32-bit Size",
and "Last Modification Time" are formatted as specified
in section
Name : /tests/project.tar.gz Link Target : <None> Type : F Size : 340488704 Upper 32-bit Size : 0 Lower 32-bit Size : 340488704 Modified Date-Time: 20080512-18:07:52
Name : C:/tests/myproject.zip Link Target : <None> Type : F Size : 4800000000 Upper 32-bit Size : 1 Lower 32-bit Size : 505032704 Modified Date-Time: 20090712-08:30:01
Name : /usr/local/staf/bin/staf Link Target : /usr/local/staf/bin/STAF Type : F Size : 91098 Upper 32-bit Size : 0 Lower 32-bit Size : 91098 Modified Date-Time: 20090708-21:43:11
LIST DIRECTORY lists the selected contents of a directory, or provides summary information for the selected contents of a directory (e.g. total size, number of files and subdirectories).
LIST DIRECTORY <Name> [RECURSE] [LONG [DETAILS] | SUMMARY] [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
`DIRECTORY` specifies the name of the directory to list. This option will resolve variables.
`RECURSE` specifies that any subdirectories will be recursively listed.
`LONG` specifies to list the selected contents of the directory
in a long format. That is, the list of child entries should include their
name, type, size, last modification time, and link target. By default, it
returns a list that only includes the name of the entry if neither the
`LONG` nor `SUMMARY` option is specified.
`DETAILS` specifies to provide more details about the child entries
in the list. Specifically, the upper 32-bit size and lower 32-bit size will be
shown in separate fields and the size will be shown in bytes instead of rounding
the size in kilobytes or megabytes.
`SUMMARY` specifies to provide only a summary of the selected contents
of the directory including its total size in bytes, number of files, and number of
subdirectories.
`TYPE` specifies the types of child entries to return. These types
are the same types described in section [8.5.7, "GET ENTRY"](#HDRFSGETE), with the addition
of '!', which, when specified along with 'D', includes the special directories
'.' and '..'. You may also specify the string "ALL" to include all entry types.
By default, only files and non-special directories are included. This option will resolve variables.
`NAME` specifies a pattern used to match the name of child entries
in the specified directory (and child entries in its subdirectories, if the
`RECURSE` option is specified). Only child entries whose name match
this pattern will be listed. Match patterns may be specified using special
characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.
`EXT` specifies a pattern used to match the extension of child entries
in the speciifed directory (and child entries in its subdirectories if the
`RECURSE` option is specified). Only child entries whose extension match
this pattern will be listed. Match patterns may be specified using special
characters '*' and/or '?' as wildcards. The default pattern is "*". This option will resolve variables.
**Note: **The LIST DIRECTORY command recognizes the "name" ( `NAME`)
portion of a filename as the character(s) that precede a period (or the entire
filename if it does not include a period) and the "extension" ( `EXT`)
portion of a filename are character(s) that follow a period.
For example, for filename myfile.txt the "name" portion is "myfile" and
the "extension" portion is "txt". To match filenames whose name begins
with "my" and whose extension is "txt", you could specify options
`NAME my* EXT txt`.
`CASESENSITIVE` specifies that the patterns specified by
`NAME` and `EXT` are to be matched in a case sensitive manner.
It also affects the sorting performed by `SORTBYNAME`.
`CASEINSENSITIVE` specifies that the patterns specified by
`NAME` and `EXT` are to be matched in a case insensitive
manner. It also affects the sorting performed by `SORTBYNAME`.
**Note: **If neither `CASESENSITIVE` nor `CASEINSENSITIVE` is
specified, the default is determined by the operating system -- unix systems
default to `CASESENSITIVE`, all others default to
`CASEINSENSITIVE`.
`SORTBYNAME` specifies that the list of child entries should be
sorted by their name.
`SORTBYSIZE` specifies that the list of child entries should be
sorted by their size.
`SORTBYMODTIME` specifies that the list of child entries should be
sorted by their last modification time.
**Note: **If none of the sorting options is used, the default is not to sort the
list. It will be in the same order as returned by the operating system, which
is not guaranteed to perform any sorting of its own.
This command requires trust level 2.
All return codes from LIST DIRECTORY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain the contents of the specified directory as follows:
[Table 19. Definition of map class STAF/Service/FS/ListLongInfo]
Description: This map class represents information about an entry
in a specified directory.
|Key Name||Display Name||Type||Format / Value|
|type||Type|<String>
|
|
|size||Size|<String>
|
|
|lastModifiedTimestamp||Modified Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|name||Name|<String>
|
|
|linkTarget||Link Target
|
(Link)
<String> | <None>
|
|
Notes:
[Table 20. Definition of map class STAF/Service/FS/ListDetailsInfo]
Description: This map class represents detailed information about
an entry in a specified directory.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|linkTarget||Link Target
|
(Link)
<String> | <None>
|
|
|type||Type|<String>
|
|
|size||Size|<String>
|upperSize||U-Size|<String>
|
|
|lowerSize||L-Size|<String>
|
|
|lastModifiedTimestamp||Modified Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
Notes:
[Table 21. Definition of map class STAF/Service/FS/ListSummaryInfo]
Description: This map class represents summary information about
the matching entries in a specified directory.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|size||Size|<String>
|
|
|numFiles||Files|<String>
|
|
|numDirectories||Directories|<String>
|
|
Notes:
win2003.exe 2-ltp-logfile test1 project.tar ACME_NEW2.xml project.htm AutoFVT.bsh
Type Size Modified Date-Time Name Link Target ---- ----- ------------------ ------------- ------------------ F 324M 20080512-18:07:52 win2003.exe <None> F 323 20080706-16:13:10 2-ltp-logfile <None> D 0 20080728-11:21:44 test1 <None> F 1210K 20080517-11:57:10 project.tar <None> F 258K 20080412-11:49:06 ACME_NEW2.xml <None> F 12505 20070506-19:14:40 project.htm <None> F 44 20080928-16:24:40 AutoFVT.bsh /tests/AutoFVT.bsh
Name Link Target Type Size U-Size L-Size Modified Date-Time -------------- ----------- ---- --------- ------ --------- ------------------ test1 <None> D 0 0 0 20080728-11:21:44 AutoFVT.bsh /tests/Auto F 44 0 44 20080928-16:24:40 FVT.bsh 2-ltp-logfile <None> F 323 0 323 20080706-16:13:10 project.htm <None> F 12505 0 12505 20070506-19:14:40 ACME_NEW2.xml <None> F 264691 0 264691 20080412-11:49:06 project.tar <None> F 1239040 0 1239040 20080517-11:57:10 win2003.exe <None> F 340488704 0 340488704 20080512-18:07:52
Type Size Modified Date-Time Name Link Target ---- ----- ------------------ ------------- ------------------ F 323 20080706-16:13:10 2-ltp-logfile <None> F 258K 20080412-11:49:06 ACME_NEW2.xml <None> F 44 20080928-16:24:40 AutoFVT.bsh /tests/AutoFVT.bsh F 324M 20080512-18:07:52 win2003.exe <None> F 1210K 20080517-11:57:10 project.tar <None> F 12505 20070506-19:14:40 project.htm <None>
javacore.20080420.041412.7713.txt windoc.txt mytest.txt svt-spa02dynos390.txt
backup/docs/hello.txt docs/hello.txt hello.txt
dumpData output
Name Link Type Size U-Size L-Size Modified Date-Time -------------------- ------ ---- ---- ------ ------ ------------------ icu\source\test1.ucm <None> F 871 0 871 20081028-19:18:22 test1 <None> D 0 0 0 20080707-11:47:40 test1.bak <None> F 83 0 83 20080919-11:10:22 test4\test1.txt <None> F 32 0 34 20090331-13:03:04
Name : C:\tests Size : 239152838 Files : 1976 Directories: 182
Name : C:\tests\stax Size : 4250936 Files : 888 Directories: 0
LIST COPYREQUESTS displays the File System copy requests currently in progress.
LIST COPYREQUESTS [LONG] [INBOUND] [OUTBOUND] [FILE [[BINARY] [TEXT]]] [DIRECTORY[
`COPYREQUESTS` specifies to list the `COPY` requests currently
in progress.
`LONG` specifies to list more detailed information about the
copy requests, such as the copy mode and current state of the copy request.
`INBOUND` specifies to list `COPY` requests that are copying
to the machine.
`OUTBOUND` specifies to list `COPY` requests that are copying
from the machine.
`FILE` specifies to list `COPY FILE` requests.
`BINARY` specifies to list `COPY FILE` requests that are
copying a file in binary format.
`TEXT` specifies to list `COPY FILE` requests that are copying
a file in text format.
`DIRECTORY` specifies to list `COPY DIRECTORY` requests.
If none of the optional options are specified (other than a
`LONG`
option), all of the copy requests currently in progress will be shown.
This command requires trust level 2.
All return codes from LIST COPYREQUESTS are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a list of the copy requests currently in progress as follows:
[Table 22. Definition of map class STAF/Service/FS/CopyRequest]
Description: This map class represents a copy request in progress.
|Key Name||Display Name||Type||Format / Value|
|startTimestamp||Start Date-Time
|
(Date-Time)
<String>
<YYYYMMDD-HH:MM:SS>
|io||In/Out
|
(I/O)
<String>
'In' | 'Out'
|machine||Machine|<String>
|
|
|name||Name|<String>
|
|
|type||Type|<String>
'D' | 'F'
Notes:
The maps used in representing detailed information about copy requests
are defined as follows:
[Table 23. Definition of map class STAF/Service/FS/CopyFile]
Description: This map class represents detailed information
about a file being copied.
|Key Name||Display Name||Type||Format / Value|
|startTimestamp||Start Date-Time
|
(Date-Time)
<String>
<YYYYMMDD-HH:MM:SS>
|io||In/Out
|
(I/O)
<String>
'In' | 'Out'
|machine||Machine|<String>
|
|
|name||File Name|<String>
|
|
|type||Type|<String>
'F'
|mode||Mode|<String>
'Binary' | 'Text'
|state||Transfer State|<Map:STAF/Service/FS/FileCopyState>
|
|
Notes:
[Table 24. Definition of map class STAF/Service/FS/FileCopyState]
Description: This map class represents detailed information
about the state of a file being copied.
|Key Name||Display Name||Type||Format / Value|
|fileSize||File Size|<String> | <None>
|
|
|bytesCopied||Bytes Copied|<String>
|
|
Notes:
[Table 25. Definition of map class STAF/Service/FS/CopyDirectory]
Description: This map class represents detailed information
about a directory being copied.
|Key Name||Display Name||Type||Format / Value|
|startTimestamp||Start Date-Time
|
(Date-Time)
<String>
<YYYYMMDD-HH:MM:SS>
|io||In/Out
|
(I/O)
<String>
'In' | 'Out'
|machine||Machine|<String>
|
|
|name||File Name|<String>
|
|
|type||Type|<String>
'D'
|state||Transfer State|<Map:STAF/Service/FS/DirectoryCopyState>
|
|
Notes:
[Table 26. Definition of map class STAF/Service/FS/DirectoryCopyState]
Description: This map class represents detailed information
about the state of the directory being copied.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|mode||Mode|<String>
'Binary' | 'Text'
|fileSize||File Size|<String> | <None>
|
|
|bytesCopied||Bytes Copied|<String>
|
|
Notes:
Start Date-Time I/O Machine Name Type ----------------- --- ---------------------- ------------------------- ---- 20050725-18:31:32 Out tcp://client2.company. c:/temp/TestA D com 20050725-18:31:38 Out tcp://client1.company. c:/tests/Instructions.txt F com@6500 20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F 20050725-18:31:41 Out tcp://client3.company. c:/tests/TestB/TestB.zip F com 20050725-18:32:05 In client2.company.com c:/tests/TestC D
[ { Start Date-Time: 20050725-18:31:32 In/Out : Out Machine : tcp://client2.company.com Directory Name : c:/temp/TestA Type : D Transfer State : { Name : c:/temp/TestA/TestA.zip Mode : Binary File Size : 9873006 Bytes Copied: 1288000 } } { Start Date-Time: 20050725-18:31:38 In/Out : Out Machine : tcp://client1.company.com@6500 File Name : c:/tests/Instructions.txt Type : F Mode : Text Transfer State : { File Size : 26019 Bytes Copied: 12000 } } { Start Date-Time: 20050725-18:31:38 In/Out : In Machine : client1.company.com File Name : c:/temp/Instructions.txt Type : F Mode : Text Transfer State : { File Size : <None> Bytes Copied: 12000 } } { Start Date-Time: 20050725-18:31:41 In/Out : Out Machine : tcp://client3.company.com File Name : c:/temp/TestB/TestB.zip Type : F Mode : Binary Transfer State : { File Size : 70483006 Bytes Copied: 63614000 } } { Start Date-Time: 20050725-18:32:05 In/Out : In Machine : client2.company.com Directory Name : c:/temp/TestC Type : D Transfer State : { Name : c:/temp/TestC/TestC.txt Mode : Text File Size : <None> Bytes Copied: 8000 } } ]
Start Date-Time In/Out Machine Name Type ----------------- ------ ------------------- ------------------------ ---- 20050725-18:31:38 In client1.company.com c:/temp/Instructions.txt F
[ { Start Date-Time: 20050725-18:31:38 In/Out : Out Machine : tcp://client1.company.com@6500 File Name : c:/tests/Instructions.txt Type : F Mode : Text Transfer State : { File Size : 26019 Bytes Copied: 12000 } } { Start Date-Time: 20050725-18:31:41 In/Out : Out Machine : tcp://client3.company.com File Name : c:/temp/TestB/TestB.zip Type : F Mode : Binary Transfer State : { File Size : 70483006 Bytes Copied: 63614000 } } ]
[ { Start Date-Time: 20050725-18:31:41 In/Out : Out Machine : tcp://client3.company.com File Name : c:/temp/TestB/TestB.zip Type : F Mode : Binary Transfer State : { File Size : 70483006 Bytes Copied: 63614000 } } ]
LIST SETTINGS shows the operational settings for the FS service.
LIST SETTINGS
`SETTINGS` specifies that you want to list the current operational
settings for the FS service.
This command requires trust level 2.
All return codes from LIST SETTINGS are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a marshalled
`<Map:STAF/Service/FS/Settings>` representing the current
settings for the File System service.
The map is defined as follows:
[Table 27. Definition of map class STAF/Service/FS/Settings]
Description: This map class represents the operational
settings for the File System service.
|Key Name||Display Name||Type||Format / Value|
|strictFSCopyTrust||Strict FS Copy Trust|<String>
'Enabled' | 'Disabled'
Strict FS Copy Trust: Disabled
CREATE creates a directory.
CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
`DIRECTORY` specifies the name of the directory to create. This option will resolve variables.
`FULLPATH` specifies that any intermediate parent directories should
be created if they don't exist.
`FAILIFEXISTS` specifies that the request should generate an error
if the specified directory already exists. By default, the request will succeed
if the specified directory already exists.
This command requires trust level 4.
All return codes from CREATE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will be empty.
DELETE deletes selected file system entries.
Note that if a file system entry being deleted is a symbolic link, the symbolic link will be deleted, not the entry referenced by the link.
DELETE ENTRY <Name> CONFIRM [RECURSE] [IGNOREERRORS] [ CHILDREN [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] ]
`ENTRY` specifies the name of the file system entry to delete.
This option will resolve variables.
`CHILDREN` specifies that only children matching `NAME`,
`EXT`, and `TYPE` should be deleted. The entry itself will
not be deleted.
`NAME` specifies a pattern used to match the name of child entries.
Only child entries whose name match this pattern will be deleted. Match
patterns may be specified using special characters '*' and/or '?' as wildcards.
The default pattern is "*". This option will resolve variables.
`EXT` specifies a pattern used to match the extension of child
entries. Only child entries whose extension match this pattern will be
deleted. Match patterns may be specified using special characters '*' and/or
'?' as wildcards. The default pattern is "*". This option will resolve variables.
**Note: **The DELETE command recognizes the "name" ( `NAME`)
portion of a file system name as the character(s) that precede a period (or the
entire name if it does not include a period) and the "extension" ( `EXT`)
portion of a file system name are character(s) that follow a period.
For example, for file system name myfile.txt, the "name" portion is "myfile" and
the "extension" portion is "txt". To match file system names whose name begins
with "my" and whose extension is "txt", you could specify options
`NAME my* EXT txt`.
`TYPE` specifies the types of child entries to delete. These types
are the same types described in section [8.5.7, "GET ENTRY"](#HDRFSGETE). 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"](#HDRRETCODE).
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"](#HDROPPARMS) 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"](#HDRRETCODE).
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"](#HDRSTAFSHS) for more
information on how to use static handles with the STAF command.
**Note: **Be sure to DELETE any static handles you create via the CREATE command.
CREATE HANDLE NAME <Handle Name>
`NAME` specifies the registered name of the handle.
This command is only valid if submitted to the local machine, not to remote machines.
All return codes from CREATE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
On successful return, the result buffer will be empty.
LIST allows you to display brief information about all handles, or about groups of handles by name or state. Note that if you do not specify a set of states to display, it will show only those that are in REGISTERED, INPROCESS, and STATIC states. To see all processes, specify PENDING, REGISTERED, INPROCESS, and STATIC. You can also display summary information about handles using the SUMMARY option.
LIST [ HANDLES <[NAME <Handle Name>] [LONG] [PENDING] [REGISTERED] [INPROCESS] [STATIC]> | [SUMMARY] ]
`HANDLES` specifies that you want to list information about handles.
`NAME` specifies that you only want information on handles with
the name `<Handle Name>`.
`LONG` specifies to list more detailed information on the handles,
such as the process id (PID) used by each handle.
`PENDING` shows handles that are in a pending state. A handle is
in pending state when a process has been started via the PROCESS service, but
that process has not yet registered with STAF.
`REGISTERED` shows handles that are registered with STAF.
`INPROCESS` shows handles for external services that are running
within the same process as STAFProc.
`STATIC` shows static handles. A static handle is a handle which was created
using the CREATE command of the HANDLE service or by using the STATICHANDLENAME option
when starting a process through the PROCESS service.
`SUMMARY` specifies that you want summary information about handles
such as the number of active handles, the total number of handles that have
been created/registered since STAFProc was started, the number of times the
handle number has been reset, the handle number range, and the maximum number
of active handles.
This command requires trust level 1.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a list of the handles as follows:
[Table 28. Definition of map class STAF/Service/Handle/HandleInfo]
Description: This map class represents status of a handle.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle
|
(H#)
<String>
|
|
|name||Handle Name
|
(Name)
<String> | <None>
|
|
|state||State|<String>
|
|
|lastUsedTimestamp||Last Used Date-Time
|
(Last Used)
<String>
<YYYYMMDD-HH:MM:SS>
[Table 29. Definition of map class STAF/Service/Handle/HandleInfoLong]
Description: This map class represents detailed information about the status
of a handle.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle
|
(H#)
<String>
|
|
|name||Handle Name
|
(Name)
<String> | <None>
|
|
|state||State|<String>
|
|
|lastUsedTimestamp||Last Used Date-Time
|
(Last Used)
<String>
<YYYYMMDD-HH:MM:SS>
|pid||PID|<String>
|
|
Notes:
The "PID" value will contain the process id assigned by the operating system.
The process id for a static handle that is not associated with a process will be 0.
[Table 30. Definition of map class STAF/Service/Handle/HandleSummary]
Description: This map class represents summary information for handles.
|Key Name||Display Name||Type||Format / Value|
|activeHandles||Active Handles|<String>
|
|
|totalHandles||Total Handles|<String>
|
|
|resetCount||Reset Count|<String>
|
|
|handleNumberRange||Handle Number Range|<String>
|<Minimum - Maximum>|
|maxActiveHandles||Maximum Active Handles|<String>
|
|
Notes:
Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20051205-12:41:42 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 4 STAF/Service/STAX Registered 20051205-12:41:51 5 STAF/Service/LOG InProcess 20051205-12:41:53 6 STAF/SERVICE/Event Registered 20051205-12:41:51 14 MyTest Registered 20051205-13:08:53 16 STAF/Client Registered 20051205-13:08:40 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time PID ------ ------------------------------- ---------- ------------------- ---- 1 STAF_Process InProcess 20051205-12:41:42 1636 2 STAF/Authenticator/AuthSample Registered 20051205-12:41:49 2360 3 STAF/Service/STAFServiceLoader1 InProcess 20051205-12:41:51 1636 4 STAF/Service/STAX Registered 20051205-12:41:51 2844 5 STAF/Service/LOG InProcess 20051205-12:41:53 1636 6 STAF/SERVICE/Event Registered 20051205-12:41:51 2844 14 MyTest Registered 20051205-13:08:53 2892 16 STAF/Client Registered 20051205-13:16:40 2900
Handle Handle Name State Last Used Date-Time ------ ----------- ---------- ------------------- 14 MyTest Registered 20051205-13:08:53
Handle Handle Name State Last Used Date-Time ------ ----------- ------ ------------------- 20 WebTest Static 20051205-13:17:35
Handle Handle Name State Last Used Date-Time ------ ----------- ------- ------------------- 17 <None> Pending 20051205-13:16:55 23 <None> Pending 20051205-13:18:59
Active Handles : 19 Total Handles : 129 Reset Count : 0 Handle Number Range : 1 - 2147483647 Maximum Active Handles: 2147483647
QUERY will allow you to display detailed information about a given handle number.
QUERY HANDLE <Handle>
`HANDLE` specifies the handle number you want information on.
This option will resolve variables.
This command requires trust level 1.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a marshalled
`<Map:STAF/Service/Handle/QueryHandle>` representing
the handles, handle name, state, last used date and time,
operating system process id, authenticator, and user identifier.
The map is defined as follows:
[Table 31. Definition of map class STAF/Service/Handle/QueryHandle]
Description: This map class represents status of a handle.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle|<String>
|
|
|name||Handle Name|<String> | <None>
|
|
|state||State|<String>
|
|
|lastUsedTimestamp||Last Used Date-Time
|
(Last Used)
<String>
<YYYYMMDD-HH:MM:SS>
|pid||PID|<String>
|
|
|user||User|<String>
<Authenticator>://<UserID>
|instanceUUID||Instance UUID|<String>
|
|
Notes:
Handle : 1 Handle Name : STAF_Process State : InProcess Last Used Date-Time: 20100126-15:45:40 PID : 1636 User : none://anonymous Instance UUID : 7D625F3CB40100000929369C75636194
AUTHENTICATE authenticates the handle submitting the request. An authenticated handle has the specified user identifier and authenticator associated with it.
AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials> [AUTHENTICATOR <Name>]
`USER` specifies the user identifier to authenticate.
`CREDENTIALS` specifies the credentials for the user identifier,
such as a password. This option will handle private data.
`AUTHENTICATOR` specifies the name of the Authenticator to
use to authenticate the handle instead of the default Authenticator.
This command is only valid if submitted to the local machine, not to remote machines.
All return codes from AUTHENTICATE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will be empty.
UNAUTHENTICATE un-authenticates the handle submitting the request. An unauthenticated handle has user 'none://anonymous' associated with it.
UNAUTHENTICATE
This command requires trust level 5.
**Note: **This command is only valid if submitted to the local machine,
not to remote machines.
All return codes from UNAUTHENTICATE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
If successful, the result buffer will contain information about the request based on the options specified:
The result buffer for a
`"LIST ERRORS"` or
`"LIST ERRORS SERVICE <Service Name>"` request will contain a
marshalled `<List> of <Map:STAF/Service/Help/ErrorInfo>`
representing the errors that can be generated by STAF internal services or
for a specific external service. The map is defined as follows:
[Table 32. Definition of map class STAF/Service/Help/ErrorInfo]
Description: This map class represents information about an error.
|Key Name||Display Name||Type||Format / Value|
|returnCode||Return Code|<String>
|
|
|description||Description|<String>
|
|
Notes:
The value for "Description" will be a short description of the error.
**Syntax:** `LIST ERRORS`
**Results:**
Return Code Description ----------- ------------------------------ 0 No error 1 Invalid API 2 Unknown service 3 Invalid handle 4 Handle already exists 5 Handle does not exist 6 Unknown error 7 Invalid request string 8 Invalid service result 9 REXX Error 10 Base operating system error 11 Process already complete 12 Process not complete 13 Variable does not exist 14 Unresolvable string 15 Invalid resolve string 16 No path to endpoint 17 File open error 18 File read error 19 File write error 20 File delete error 21 STAF not running 22 Communication error 23 Trusteee does not exist 24 Invalid trust level 25 Insufficient trust leevl 26 Registration error 27 Service configuration error 28 Queue full 29 No queue element 30 Notifiee does not exist 31 Invalid API level 32 Service not unregisterable 33 Service not available 34 Semaphore does not exist 35 Not sempahore owner 36 Semaphore has pending requests 37 Timeout 38 Java error 39 Converter error 40 Not used 41 Invalid object 42 Invalid parm 43 Request number not found 44 Invalid asynchronous option 45 Request not complete 46 Process authentication denied 47 Invalid value 48 Does not exist 49 Already exists 50 Directory Not Empty 51 Directory Copy Error 52 Diagnostics Not Enabled 53 Handle Authentication Denied 54 Handle Already Authenticated 55 Invalid STAF Version 4000+ Service specific errors
**Syntax:** `LIST SERVICE Log ERRORS`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Return Code Description ----------- ------------------------------- 4004 Invalid level 4007 Invalid file format 4008 Unable to purge all log records
**Syntax:** `LIST SERVICES`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
EVENT LOG RESPOOL STAX
[SERVICE <Service name>] ERROR <Return code>
`SERVICE` indicates that only information specific to the given
service should be return. Otherwise, information will be returned for all
services which have registered the indicated return code.
`ERROR` specifies the return code about which you want information
This command requires trust level 2.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain information about the request based on the options specified:
[Table 33. Definition of map class STAF/Service/Help/ErrorDetails]
Description: This map class represents information about an error.
|Key Name||Display Name||Type||Format / Value|
|description||Description|<String>
|
|
|details||Details|<String>
|
|
[Table 34. Definition of map class STAF/Service/Help/ErrorDetails]
Description: This map class represents information about an error
registered by an external service.
|Key Name||Display Name||Type||Format / Value|
|service||Service|<String>
|
|
|description||Description|<String>
|
|
|details||Details|<String>
|
|
**Syntax:** `ERROR 22`
**Results:** If the request is issued from the
command line, the result, in default format, could look like:
Description: Communication error Details : This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request.
**Syntax:** `ERROR 4007`
**Results:** If the request is issued from the
command line, the result, in verbose format, could look like:
[ { Service : LOG Description: Invalid file format Details : An invalid/unknown record format was encountered while reading the log file } { Service : RESPOOL Description: Resource pool has no entries available Details : The resource pool has no entries } ]
**Syntax:** `SERVICE Log ERROR 4007`
**Results:** If the request is issued from the
command line, the result, in default format, could look like:
Description: Invalid file format Details : An invalid/unknown record format was encountered while reading the log file
REGISTER SERVICE <Service name> ERROR <Return code> INFO <String> DESCRIPTION <String>
`SERVICE` indicates the service for which to register information
`ERROR` indicates the return code for which to register information
`INFO` specifies a short description string which is displayed
when using the Help service's LIST command.
`DESCRIPTION` specifies the full information about the return code.
This information is displayed when using the Help service's ERROR command.
This command requires trust level 3.
This command is only valid when issued by local services.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
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"](#HDRRETCODE).
The LifeCycle service provides the following commands.
The registrations for the LifeCycle service are persistent. This means
that if STAF is shutdown and restarted (or if the machine is rebooted),
the prior registration information for the LifeCycle service will still exist.
When STAFProc starts, it reads in the existing registration data and executes
the enabled registered STAF service requests with the "Startup" phase specified.
When STAFProc is shutdown, it reads in the existing registration data and
executes the enabled registered STAF service requests with the "Shutdown" phase
specified. The LifeCycle service's registration data is stored in file
`{STAF/DataDir}/service/lifecycle/lifecycle.reg`.
The STAF LifeCycle service maintains a STAF machine log where it writes
information about the STAF service requests that have been registered with
the LifeCycle service and that it has submitted. When debugging a problem
with a registration for the LifeCycle service, be sure to check the LifeCycle
service log to determine the results of STAF service requests submitted by
the LifeCycle service. See
[8.8.11, "LifeCycle Service Logging"](#HDRLIFECYCLESERVICELOG) for more
information on the LifeCycle service log.
Each STAF service request that is registered will be submitted
synchronously when STAFProc starts up or shuts down, or is triggered
via a
`TRIGGER` request. This means that if you register
a STAF service request that never completes (e.g. a `PROCESS START
WAIT` request without a `TIMEOUT` option for a command
that never completes, or a `SEM MUTEX REQUEST` request with a
`TIMEOUT` option for a mutex semaphore that never becomes
available), then if registered for the `Startup` phase, STAFProc
will not complete starting up. Or, if registered for the `Shutdown`
phase, STAFProc will not complete shutting down.
REGISTER PHASE <Startup | Shutdown> MACHINE <Machine> SERVICE <Service> REQUEST <Request> [ONCE] [PRIORITY <Priority>] [DESCRIPTION <Description>]
`PHASE` specifies when the service request will be submitted.
Valid values are "Startup" and "Shutdown" (case-insensitive).
Specifying "Startup" indicates to submit the service request when
STAFProc starts up. Specifying "Shutdown" indicates to submit the
service request when STAFProc shuts down.
This option will resolve variables.
`MACHINE` specifies the endpoint for a machine where the
service request will be submitted.
`SERVICE` specifies the name of the STAF service to which
a request will be submitted.
`REQUEST` specifies the request to be submitted to the
specified service.
`ONCE` specifies that the STAF service request should only be
executed once. After the STAF service request has been submitted at Startup or
Shutdown (depending on the specified phase), the ID for this request will
be unregistered.
`PRIORITY` specifies the priority of the registration which is
used in determining the order in which the registration will be submitted
(if there is more than one registration) when STAFProc starts up or shuts
down. It must be a number from 1 to 99. The default is 50.
Registrations with priority 1 will be submitted first, followed by
registrations with priority 2, and so on.
Registrations with the same priority will be submitted in order by
registration ID.
This option will resolve variables.
`DESCRIPTION` specifies a description of the registration.
It is for informational purposes only and is optional.
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain the registration ID.
**Syntax:**
`REGISTER PHASE Startup MACHINE client1.company.com SERVICE Process
REQUEST "START SHELL COMMAND C:/tests/TestA.exe" DESCRIPTION "Start TestA"`
**Syntax:**
`REGISTER PHASE Startup MACHINE server1 SERVICE STAX REQUEST
"EXECUTE FILE /tests/TestA.xml ARGS \"{'testMach': 'client1',
'serverMach': 'server1'}\""`
**Syntax:**
`REGISTER PHASE Shutdown MACHINE local SERVICE Process REQUEST
"START SHELL COMMAND C:/tests/TestB.exe" DESCRIPTION "Start TestB"`
**Syntax:**
`REGISTER PHASE Startup MACHINE server1 SERVICE QUEUE REQUEST
"QUEUE NAME MyTestHandle TYPE :12:STAF Startup MESSAGE :0:" ONCE`
UNREGISTER ID <Registration ID>
`ID` specifies the registration ID of the STAF service request
to be unregistered.
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will be empty.
**Syntax:**
`UNREGISTER ID 2`
UPDATE ID <Registration ID> [PRIORITY <Priority>] [ONCE <True | False>] [MACHINE <Machine>] [SERVICE <Service>] [REQUEST <Request>] [PHASE <Startup | Shutdown>] [DESCRIPTION <Description>]
`ID` specifies the registration ID of the STAF service request
to be updated.
`PRIORITY` specifies the priority of the registration which is
used in determining the order in which the registration will be submitted
(if there is more than one registration) when STAFProc starts up or shuts
down. It must be a number from 1 to 99.
Registrations with priority 1 will be submitted first, followed by
registrations with priority 2, and so on.
Registrations with the same priority will be submitted in order by
registration ID.
This option will resolve variables.
`ONCE` specifies whether the STAF service request should only be
executed once. Valid values are "True" and "False" (case-insensitive).
Specifying "True" indicates to submit the STAF service request only once
which means after the STAF service request has been submitted at Startup or
Shutdown (depending on the specified phase), this registration will be
unregistered. Specifying "False" indicates that the STAF service request
should be submitted each time STAFProc starts up or shuts down (depending
on the specified phase).
This option will resolve variables.
`MACHINE` specifies the endpoint for a machine where the
service request will be submitted.
`SERVICE` specifies the name of the STAF service to which
a request will be submitted.
`REQUEST` specifies the request to be submitted to the
specified service.
`PHASE` specifies when the service request will be submitted.
Valid values are "Startup" and "Shutdown" (case-insensitive).
Specifying "Startup" indicates to submit the service request when
STAFProc starts up. Specifying "Shutdown" indicates to submit the
service request when STAFProc shuts down.
This option will resolve variables.
`DESCRIPTION` specifies a description of the registration.
It is for informational purposes only and is optional.
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will be empty.
**Syntax:**
`UPDATE ID 2 PRIORITY 25 DESCRIPTION "Run TestA"`
LIST [PHASE <Startup | Shutdown>] [LONG]
`PHASE` specifies to list only the registrations with a
matching phase. Valid values for "Startup" and "Shutdown" (case-insensitive).
This option will resolve variables.
`LONG` specifies to include all of the registration information,
including the description for each registration.
This command requires trust level 2.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain information about the request based on the options specified:
[Table 35. Definition of map class STAF/Service/LifeCycle/Reg]
Description: This map class represents information about
a registration.
|Key Name||Display Name||Type||Format / Value|
|phase||Phase|<String>
|'Startup' | 'Shutdown'|
|priority||Priority
|<String>
|'1' - '99'|
|id||ID|<String>
|
|
|state||State|<String>
|'Enabled' | 'Disabled'|
|machine||Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked|
|once||Once|<String>
|'True' | 'False'|
The result buffer for a
`LIST` with the `LONG`
option will contain a marshalled `<List> of
<Map:STAF/Service/LifeCycle/RegDetails>` representing the
matching registrations for the LifeCycle service.
The map is defined as follows:
[Table 36. Definition of map class STAF/Service/LifeCycle/RegDetails]
Description: This map class represents detailed
information about a registration.
|Key Name||Display Name||Type||Format / Value|
|phase||Phase|<String>
|'Startup' | 'Shutdown'|
|priority||Priority
|<String>
|'1' - '99'|
|id||ID|<String>
|
|
|state||State|<String>
|'Enabled' | 'Disabled'|
|machine||Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked|
|description||Description|<String> | <None>
|
|
|once||Once|<String>
|'True' | 'False'|
**Syntax:** `LIST`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Phase P ID State Machine Service Request Once ------- -- -- ------- ------- ------- ------------------------------------ ---- Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals xe e Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals e WAIT e Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals d e WAIT e Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals e Shutdow 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTer True n m.exe Shutdow 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals n e
**Syntax:** `LIST PHASE Startup`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Phase P ID State Machine Service Request Once ------- -- -- ------- ------- ------- ------------------------------------ ---- Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/tests/TestA.e Fals xe e Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/test/TestB.ex Fals e WAIT e Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/test/TestC.ex Fals d e WAIT e Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jobA.xml Fals e
**Syntax:** `LIST PHASE Shutdown`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Phase P ID State Machine Service Request Once -------- -- -- ------- ------- ------- ----------------------------------- ---- Shutdown 25 2 Enabled local PROCESS START SHELL COMMAND C:/tests/TestTe True rm.exe Shutdown 50 6 Enabled server1 STAX EXECUTE FILE C:/stax/jobTerm.xml Fals e
**Syntax:** `LIST PHASE Startup LONG`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Phase P ID State Machine Service Request Description Once ------- -- -- ------- ------- ------- ----------------------- ----------- ----- Startup 25 1 Enabled local PROCESS START SHELL COMMAND C:/ Run TestA False tests/TestA.exe Startup 25 4 Enabled client1 PROCESS START SHELL COMMAND C:/ Run TestB False test/TestB.exe WAIT Startup 40 3 Disable local PROCESS START SHELL COMMAND C:/ Run TestC False d test/TestC.exe WAIT Startup 50 5 Enabled server1 STAX EXECUTE FILE C:/stax/jo Run STAX Jo False bA.xml bA
QUERY ID <Registration ID>
`ID` specifies the registration ID of the STAF service request
to be queried.
This option will resolve variables.
This command requires trust level 2.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain a marshalled
`<Map:STAF/Service/LifeCycle/RegQuery>` representing
information about the registration.
The map is defined as follows:
[Table 37. Definition of map class STAF/Service/LifeCycle/RegQuery]
Description: This map class represents information about
a registration.
|Key Name||Display Name||Type||Format / Value|
|phase||Phase|<String>
|'Startup' | 'Shutdown'|
|priority||Priority|<String>
|'1' - '99'|
|id||ID|<String>
|
|
|state||State|<String>
|'Enabled' | 'Disabled'|
|machine||Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked|
|description||Description|<String> | <None>
|
|
|once||Once|<String>
|'True' | 'False'|
**Syntax:** `QUERY 5`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Phase : Startup Priority : 50 ID : 5 State : Enabled Machine : server1 Service : STAX Request : EXECUTE FILE C:/stax/jobA.xml Description: Run STAX JobA Once : False
Only enabled STAF requests will be submitted by a
`TRIGGER PHASE`
request. A `TRIGGER ID` request will submit enabled and disabled
STAF requests. Each STAF service request that is triggered will be
submitted synchronously (e.g. waits for the STAF service request to complete)
before returning or submitting the next STAF service request if the
`PHASE` option was specified and there are more STAF service
requests registered for the specified phase. This means that if you register
a STAF service request that never completes (e.g. a `PROCESS START`
request using the `WAIT` option but not the `TIMEOUT` option,
or a `SEM MUTEX REQUEST` request without a `TIMEOUT` option
for a mutex semaphore that never becomes available), then the
`TRIGGER` request will never complete.
Note that if the submitted STAF service request was registered with the
ONCE option, triggering the STAF command will not cause the registration
to be unregistered.
TRIGGER <ID <Registration ID> { PHASE <Startup | Shutdown>> CONFIRM
`ID` specifies the registration ID of the STAF service request
to be triggered.
This option will resolve variables.
`PHASE` specifies to trigger all the registrations with
a matching phase. Valid values are "Startup" and "Shutdown"
(case-insensitive).
This option will resolve variables.
`CONFIRM` specifies you really want to trigger submitting
the STAF service requests specified by the matching registration(s).
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain information about the request based on the options specified:
[Table 38. Definition of map class STAF/Service/LifeCycle/TriggerId]
Description: This map class represents information about
the submitted STAF service request.
|Key Name||Display Name||Type||Format / Value|
|machine||Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked|
|rc||RC|<String>
|
|
|result||Result|<String> | <Marshalling Context>.
|
|
Notes:
[Table 39. Definition of map class STAF/Service/LifeCycle/TriggerIds]
Description: This map class represents information about
the submitted STAF service requests.
|Key Name||Display Name||Type||Format / Value|
|id||ID|<String>
|
|
|machine||Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked|
|rc||RC|<String>
|
|
|result||Result|<String> | <Marshalling Context>.
|
|
Notes:
**Syntax:** `TRIGGER ID 5 CONFIRM`
**Results:** If the request is issued from the command line,
the result, in default format, could look like the following if the
registration submitted a "EXECUTE FILE C:/stax/jobA.xml" request to the
STAX service on machine server1:
Machine: server1 Service: STAX Request: EXECUTE FILE C:/stax/jobA.xml RC : 0 Result : 4
**Syntax:** `TRIGGER PHASE Startup CONFIRM`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like the following:
[ { ID : 1 Machine: local Service: PROCESS Request: START SHELL COMMAND C:/tests/TestA.exe RC : 0 Result : 58 } { ID : 4 Machine: client1 Service: PROCESS Request: START SHELL COMMAND C:/test/TestB.exe WAIT RC : 0 Result : { Return code: 0 Key : <None> Files : [ { Return code: 0 Data : TestB was successful } ] } } { ID : 5 Machine: server1 Service: STAX Request: EXECUTE FILE C:/stax/jobA.xml RC : 0 Result : 4 } ]
**Syntax:** `TRIGGER PHASE Shutdown CONFIRM`
**Results:** If the request is issued from the command line,
the result, in tabular format, could look like the following:
ID Machine Service Request RC Result -- ------- ------- ---------------- -- ---------------------------------------- 2 local PROCESS START SHELL COMM 0 293 AND C:/tests/Tes tTerm.exe 6 server1 STAX EXECUTE FILE C:/ 16 STAFConnectionProviderConnect: Timed out stax/jobTerm.xml connecting to endpoint: select() timeou t: 22, Endpoint: tcp://server1
ENABLE ID <Registration ID>
`ID` specifies the registration ID which is to be enabled.
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already enabled.
**Syntax:**
`ENABLE ID 2`
DISABLE ID <Registration ID>
`ID` specifies the registration ID which is to be disabled.
This command requires trust level 5.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will be empty. Note that an error will not be returned if the registration ID is already disabled.
**Syntax:**
`ENABLE ID 2`
All return codes from the LifeCycle service are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The STAF LifeCycle service maintains a STAF machine log where it writes information about the STAF service requests that have been registered with the LifeCycle service and that it has submitted. When debugging a problem with a registration for the LifeCycle service, be sure to check the LifeCycle service log to determine the results of STAF service requests submitted by the LifeCycle service.
The logname for the STAF LifeCycle service is LIFECYCLE.
Note that tags like
`[ID=<id>]` in the log entries can be useful
when querying the LifeCycle service log by using the `CONTAINS`
option in the LOG QUERY request.
For example:
STAF local LOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=1]" Response -------- Date-Time Level Message ----------------- ----- ------------------------------------------------------- 20071127-17:45:19 Info [ID=1] [client10.company.com, STAF/Client, 24] Register request: register phase Startup machine local service PROCESS request :38:START SHELL COMMAND C:/tests/TestA. exe priority 25 description :9:Run TestA 20071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER Startup] Submitted: STAF local PROCESS START SHELL COM MAND C:/tests/TestA.exe 20071127-18:05:56 Info [ID=1] [client10.company.com, STAF/Client, 48] [TRIGGER Startup] Completed. RC=0, Result=49 20071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER Startup] Submitted: STAF local PROCESS START SHELL COM MAND C:/tests/TestA.exe 20071128-11:37:37 Info [ID=1] [client10.company.com, STAF_Process, 1] [TRIGGER Startup] Completed. RC=0, Result=22
STAF local lOG QUERY MACHINE {STAF/Config/MachineNickname} LOGNAME LIFECYCLE CONTAINS "[ID=2]" Response -------- Date-Time Level Message ----------------- ----- ------------------------------------------------------- 20071127-17:46:18 Info [ID=2] [client10.company.com, STAF/Client, 25] Register request: register phase Shutdown machine local service PROCESS request :41:START SHELL COMMAND C:/tests/TestT erm.exe priority 25 20071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER Shutdown] Submitted: STAF local PROCESS START SHELL CO MMAND C:/tests/TestTerm.exe 20071127-18:08:54 Info [ID=2] [client10.company.com, STAF/Client, 50] [TRIGGER Shutdown] Completed. RC=0, Result=51 20071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER Shutdown] Submitted: STAF local PROCESS START SHELL CO MMAND C:/tests/TestTerm.exe 20071128-11:36:27 Info [ID=2] [client10.company.com, STAF_Process, 1] [TRIGGER Shutdown] Completed. RC=0, Result=78
The LifeCycle service will log an entry when the following actions occur:
`
[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Register request: <request>
`
where:
`
[ID=<id>] [<orgMachine>, <orgHandleName>, <orgHandle#>] Unregistered.
`
where:
where:
where:
where:
where:
where:
where:
where:
where:
where:
The purpose of the Log service is to allow a test case to easily and flexibly manage information that needs to be logged. It allows you to specify a log mask which defines which messages actually get logged to the log file. This log mask can be dynamically changed to alter the set of log messages written to the log file(s). This can greatly assist in debugging. For example, while a test case is running, you can dynamically alter the log mask to allow debug and trace log messages to start being logged. The log query mechanism allows for record selection based on many selection criteria matches.
The Log service can be run in one of two modes. In local mode, all log requests are handled locally, and all log files are stored locally. In remote mode, all log requests are forwarded to a central system for processing. In addition, all log files are stored on the central system. While it is possible to delegate the log service to a central system, this has some unwanted side effects. The primary one being that many unwanted messages are likely to be sent over the network, consuming time and bandwidth.
The following is an example of the major difference between delegating the Log service and using the Log service in remote logging mode.
Example Delegated Log NETWORK start ! start info ! info warning ! warning +------+ trace +-----------+ ! trace +-------+ ! TEST !-> debug -> ! STAF !-> ! debug -> ! STAF ! -> WRITE LOG ! CASE ! trace ! DELEGATED ! ! trace ! LOG ! ========= +------+ error ! LOG ! ! error ! Mask= ! error debug +-----------+ ! debug ! Error ! fail trace ! trace ! Fail ! debug ! debug +-------+ fail ! fail Example Remote Logging NETWORK start ! info ! warning ! +------+ trace +-----------+ ! +------+ ! TEST !-> debug -> ! LOG !-> ! error -> ! STAF ! -> WRITE LOG ! CASE ! trace ! Mask= ! ! fail ! LOG ! ========= +------+ error ! Error ! ! +------+ error debug ! Fail ! ! fail trace +-----------+ ! debug ! fail !
In the above Delegated Log service example, all the messages flowed over the network to the ultimate log server even though only error and fail conditions were selected to be logged. In the above Remote Logging example, the selection of the messages occur at the local box and only those messages that are selected get sent over the network to the ultimate log server.
**Note: **When using the Log service in remote logging mode, you should have the
log mask disabled (i.e. log everything) at the ultimate log server to avoid
confusion and multiple log mask filtering.
SERVICE
<Name>LIBRARY STAFLog [PARMS <Log parameters>] `<Name>` is the name by which the Log service will be known on this
machine. The recommended name of the Log service is "LOG"
`<Log parameters>` are valid log parameters described below.
service log library STAFLog service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata ResolveMessage"
The Log service accepts a parameter string in the following formats
[DIRECTORY <Log Directory Root>] [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>] [RESOLVEMESSAGE | NORESOLVEMESSAGE] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]or
ENABLEREMOTELOGGING REMOTELOGSERVER <Server name> [REMOTELOGSERVICE <Service Name>]
`DIRECTORY` specifies the root directory under which log files are
stored. The default is `{STAF/DataDir}/service/<Service Name (lower-case)>`.
**Note: **Previously, in STAF 2.x, the default root directory was
`{STAF/Config/STAFRoot}/data/log`.
So, if you want to continue to use the STAF 2.x log files with the
current version of STAF, move the log files to the new default root
directory or specify the old root directory for the `DIRECTORY` parameter.
`MAXRECORDSIZE` specifies the maximum length (in characters) of a
logged message. The default is 100000.
`DEFAULTMAXQUERYRECORDS` specifies the maximum number of records
that will be returned if your query criteria selects more records than this number.
The default is 100. If no limit on the maximum number of records returned by
a query is desired, specify 0.
If a non-zero value is specified, it's equivalent to specifying LAST <Number>.
This limit is only used if none of the following options are specified on a
`QUERY` request: `FIRST, LAST, ALL, TOTAL, or STATS`.
`RESOLVEMESSAGE` specifies that variables in log messages should
be resolved by default.
`NORESOLVEMESSAGE` specifies that variables in log messages should
not be resolved by default. This is the default.
`ENABLERESOLVEMESSAGEVAR` specifies that the log service should
check the value of the STAF/Service/<Name>/ResolveMessage variable to determine
if variables in log messages should be resolved. This option will adversely
affect the performance of the Log service. See below for more information.
`DISABLERESOLVEMESSAGEVAR` specifies that the log service should not
check the value of the STAF/Service/<Name>/ResolveMessage variable to determine
if variables in log messages should be resolved. See below for more information.
This is the default.
`ENABLEREMOTELOGGING` specifies that the Log service should operate
in remote/forwarding mode.
`REMOTELOGSERVER` specifies the server to which forwarded log
requests should be sent. This machine must be running STAF V3.0.0 or later.
**Note: **From a trust perspective, the tcp interface names on the remote log
server and on the machine forwarding requests to it must match or the remote
log server must use a wildcard to match any interface in the trust statement for
the machine that is forwarding log requests to it.
`REMOTELOGSERVICE` specifies the service to which forwarded log
requests should be sent. The default is the same name under which the Log
service was registered on the local machine.
**Note: **All these parameters, with the exception of `DIRECTORY`,
`ENABLEREMOTELOGGING`, `REMOTELOGSERVER`, and
`REMOTELOGSERVICE` may be changed with the `SET` command,
see [8.9.10, "SET"](#HDRLOGSET) for more information.
See
[8.9.11, "Logging Levels Reference"](#HDRLOGLEV) for a complete list of logging levels.
The log mask contains the set of levels that will actually be logged to the log file.
**Note: **This variable is not checked unless the `ENABLERESOLVEMESSAGEVAR`
option has been set.
**Note: **There are three places where message resolution can be affected. They are
evaluated in the following order
LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level> MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
`GLOBAL` indicates you want to write to a global log. The global
log is intended to facilitate multiple testcases on multiple machines all
writing to a common log.
`MACHINE` indicates you want to write to a machine log. The machine
log is intended to facilitate multiple testcases on a single machine all writing
to a common machine name log.
`HANDLE` indicates you want to write to a handle log. The handle
log is intended to facilitate each testcase writing to a separate log (no matter
how many machines and processes are involved)
`LOGNAME` contains the name of the log to which you want to write.
This option will resolve variables.
`LEVEL` determines the level that you want to log. This can be in
the form of level type such as "FATAL", "ERROR", WARNING", etc. or a 32 byte
binary string such as "00000000000000000000000000000001". This option will resolve variables.
See [8.9.11, "Logging Levels Reference"](#HDRLOGLEV) for a complete list of logging levels.
`MESSAGE` contains the message (data) that you want to write to the
log. This option will not resolve messages by default but can be configured to
do so in the STAF configuration file or by using RESOLVEMESSAGE.
Any private data in the message will be masked before writing to the log.
`RESOLVEMESSAGE` causes the LOG service to call the STAF variable
service to resolve any variables in the message before being written. This
overrides any other message resolution settings.
`NORESOLVEMESSAGE` causes the LOG service to not call the STAF
variable service. This overrides any other message resolution settings.
This command requires trust level 3.
The result buffer will contain no data on return from a LOG command.
Allows you to query records from a log based on a set of selection criteria.
**Note: **A stand-alone utility also exists, called FmtLog, that can read a log file
and write the data to an output file in a readable format.
See [9.4, "Format Log Utility"](#HDRFMTLOG) for additional information.
QUERY <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]... [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]... [CONTAINS <String>]... [CSCONTAINS <String>]... [STARTSWITH <String>]... [CSSTARTSWITH <String>]... [FROM <Timestamp> | AFTER <Timestamp>] [BEFORE <Timestamp> | TO <Timestamp>] [FROMRECORD <Num>] [TORECORD <Num>] [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG] [LEVELBITSTRING]
`GLOBAL` indicates you want to query to a global log. The global log is intended
to facilitate multiple testcases on multiple machines all writing to a common log.
`MACHINE` indicates you want to query to a machine log. Specify the machine nickname.
The machine log is intended to facilitate multiple testcases on a single machine all
writing to a common log. This option will resolve variables.
`HANDLE` indicates you want to query to a handle log. The handle log is intended
to facilitate each testcase writing to a separate log. This option will resolve variables.
`LOGNAME` contains the name of the log you want to query. All log files have the ".log"
extension automatically added to the file name. This option will resolve variables.
`LEVELMASK` determines the levels that are selected. This can be in the form of
"FATAL ERROR WARNING" or a 32 byte bit string such as "00000000000000000000000000000111". This option will resolve variables.
`QMACHINE` selects only those records that originated from a certain machine.
Multiple `QMACHINE` statements are handled as an "or" condition. This option will resolve variables.
`QHANDLE` selects only those records that are associated with a certain handle.
Multiple `QHANDLE` statements are handled as an "or" condition. This option will resolve variables.
`NAME` selects only those records with a certain registered name.
Multiple `NAME` statements are handled as an "or" condition. This option will resolve variables.
`USER` selects only those records with a certain user.
`<User>` format is `<Authenticator>://<User Identifier>` (e.g.
none://anonymous, SampleAuth://johnDoe@company.com).
Multiple `USER` statements are handled as an "or" condition. This option will resolve variables.
`ENDPOINT` selects only those records with a certain endpoint.
Multiple `ENDPOINT` statements are handled as an "or" condition. This option will resolve variables.
`CONTAINS` selects only those records that contain a specified string in the message. Note
that this match is case insensitive. Multiple `CONTAINS` statements are
handled as an "or" condition. This option will resolve variables.
`CSCONTAINS` selects only those records that contain a specified string in the message. Note
that this match is case sensitive. Multiple `CSONTAINS` statements are
handled as an "or" condition. This option will resolve variables.
`STARTSWITH` selects only those records that start with a specified string in the message.
Note that this match is case insensitive. Multiple `STARTSWITH/CSSTARTSWITH` statements are
handled as an "or" condition. This option will resolve variables.
`CSSTARTSWITH` selects only those records that start with a specified string in the message.
Note that this match is case sensitive. Multiple `CSSTARTSWITH/STARTSWITH` statements are
handled as an "or" condition. This option will resolve variables.
`FROM` selects only those records that have a date and/or time from the specified format. This option will resolve variables.
`AFTER` selects only those records that have a date and/or time after the specified format. This option will resolve variables.
`TO` selects only those records that have a date and/or time to the specified format. This option will resolve variables.
`BEFORE` selects only those records that have a date and/or time before the specified format. This option will resolve variables.
**Note: ** `<Timestamp>` format is date, @time, or date@time (e.g. 19980214, @16:30:45, 19980214@16:30:45)
**Note: **The keyword ** can be used for the current date in the TODAY** `FROMRECORD` selects only those records whose record number is greater than or equal
to the specified record number (which must be >= 1). This option will resolve variables.
`TORECORD` selects only those records whose record number is less than or equal to
the specified record number (which must be >= 1). This option will resolve variables.
`FIRST` selects only the first <Num> records. This option will resolve variables.
`LAST` selects only the last <Num> records. This option will resolve variables.
`ALL` selects all the records that meet the query criteria.
`TOTAL` display only the total number of records selected instead of the records themselves.
`STATS` display the totals for each level instead of the records themselves.
`LONG` displays all of the fields for each log record instead of just the timestamp, level, and
message fields.
`LEVELBITSTRING` displays the selected records with the level displayed as a 32 byte binary bit
string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error.
See [8.9.11, "Logging Levels Reference"](#HDRLOGLEV) 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"](#HDRRETCODE),
QUERY also returns codes documented in [8.9.12, "Log Error Code Reference"](#HDRLOGERR).
If the query criteria selects more records than allowed by the DefaultMaxQueryRecords
parameter/setting (and none of the following options are specified:
`FIRST, LAST,
ALL, TOTAL, or STATS`), the return code will be set to 4010 and the result buffer will
contain only the 'last' default maximum number of query records.
If successful, the result buffer will contain data based on the QUERY command:
[Table 40. Definition of map class STAF/Service/Log/QueryStats]
Description: This map class represents the totals for the log levels of the
selected records in the log.
|Key Name||Display Name||Type||Value / Format|
|fatal||Fatal|<String>
|
|
|error||Error|<String>
|
|
|warning||Warning|<String>
|
|
|info||Info|<String>
|
|
|trace||Trace|<String>
|
|
|trace2||Trace2|<String>
|
|
|trace3||Trace3|<String>
|
|
|debug||Debug|<String>
|
|
|debug2||Debug2|<String>
|
|
|debug3||Debug3|<String>
|
|
|start||Start|<String>
|
|
|stop||Stop|<String>
|
|
|pass||Pass|<String>
|
|
|fail||Fail|<String>
|
|
|status||Status|<String>
|
|
|user1||User1|<String>
|
|
|user2||User2|<String>
|
|
|user3||User3|<String>
|
|
|user4||User4|<String>
|
|
|user5||User5|<String>
|
|
|user6||User6|<String>
|
|
|user7||User7|<String>
|
|
|user8||User8|<String>
|
|
[Table 41. Definition of map class STAF/Service/Log/LogRecordLong]
Description: This map class represents detailed information for a log record.
|Key Name||Display Name||Type||Value / Format|
|recordNumber||Record #
|
(R#)
<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|machine||Machine|<String>
|
|
|handle||Handle
|
(H#)
<String>
|
|
|handleName||Handle Name
|
(Name)
<String>
|
|
|user||User|<String>
|
|
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|level||Level|<String>
|
|
|message||Message|<String>
|
|
[Table 42. Definition of map class STAF/Service/Log/LogRecord]
Description: This map class represents a log record.
|Key Name||Display Name||Type||Value / Format|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|level||Level|<String>
|
|
|message||Message|<String>
|
|
Assume this example log file called STRESSTST contains the following records:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ---------------------- -- ------ ---------------- --------------------------------- ------- ---------------------------------- 1 20070210-18:04:00 automate.austin.ibm.com 37 Test1A none://anonymous local://local Start Stress Test 1A Initiated 2 20070210-19:37:15 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 1: processing time: 01:31:26 3 20070210-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 1: debug: files=23 threads=37 4 20070210-22:20:34 automate.austin.ibm.com 37 Test1A none://anonymous local://local Warning Step 2: File not ready, retry=3 5 20070210-22:21:01 automate.austin.ibm.com 37 Test1A none://anonymous local://local Info Step 2: File ready on retry 3 6 20070211-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 2: processing time: 03:02:41 7 20070211-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 8 20070211-01:37:25 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Trace Step 1: processing time: 03:11:53 9 20070211-01:43:46 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug Step 1: debug: files=43 threads=67 10 20070211-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local Error Step 3: Sharing buffer exceeded 11 20070211-02:54:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local User1 Step 3: Error recovery started 12 20070211-04:32:53 automate.austin.ibm.com 37 Test1A none://anonymous local://local User2 Step 3: Error recovery completed 13 20070211-04:33:49 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 3: processing time: 03:10:41 14 20070211-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 3: debug: files=78 threads=98 15 20070211-08:46:22 automate.austin.ibm.com 37 Test1A none://anonymous local://local Stop Stress Test 1A Completed 16 20070211-08:47:21 automate.austin.ibm.com 37 Test1A none://anonymous local://local Pass Stress Test 1A: Errors=1 Recover=1 17 20070211-08:48:46 automate.austin.ibm.com 37 Test1A none://anonymous local://local Status Step1=P, Step2=P, Step3=W, TC=P
**Note: ** The output for these examples are formatted for ease of reading in this
document, the actual format will vary depending on whether the command is
submitted via STAF.exe or via a program's submit(), etc. method.
**Syntax:** `QUERY GLOBAL LOGNAME stresstst LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"`
**Results:** If the request was issued from the
command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ----- ---------------------------------- 20070210-19:37:15 Trace Step 1: processing time: 01:31:26 20070210-19:39:09 Debug Step 1: debug: files=23 threads=37 20070211-01:21:39 Trace Step 2: processing time: 03:02:41 20070211-01:21:58 Debug Step 2: debug: files=31 threads=54 20070211-01:37:25 Trace Step 1: processing time: 03:11:53 20070211-01:43:46 Debug Step 1: debug: files=43 threads=67 20070211-04:33:49 Trace Step 3: processing time: 03:10:41 20070211-04:34:07 Debug Step 3: debug: files=78 threads=98
**Syntax:** `QUERY GLOBAL LOGNAME stresstst LEVELMASK "ERROR"`
**Results:** If the request was issued from the
command line, the result in table format, could look like:
Date-Time Level Message ----------------- ----- ------------------------------- 20070211-02:53:20 Error Step 3: Sharing buffer exceeded
**Syntax:** `QUERY GLOBAL LOGNAME stresstst total`
**Results:**
17
**Syntax:** `QUERY GLOBAL LOGNAME stresstst FROM 20070210@19:00:00 QMACHINE automate to today@08:00:00`
**Results:** If the request was issued from the
command line, the result, in table format, could look like:
Date-Time Level Message ----------------- ------- ---------------------------------- 20070210-19:37:15 Trace Step 1: processing time: 01:31:26 20070210-19:39:09 Debug Step 1: debug: files=23 threads=37 20070210-22:20:34 Warning Step 2: File not ready, retry=3 20070210-22:21:01 Info Step 2: File ready on retry 3 20070211-01:21:39 Trace Step 2: processing time: 03:02:41 20070211-01:21:58 Debug Step 2: debug: files=31 threads=54 20070211-02:53:20 Error Step 3: Sharing buffer exceeded 20070211-02:54:22 User1 Step 3: Error recovery started 20070211-04:32:53 User2 Step 3: Error recovery completed 20070211-04:33:49 Trace Step 3: processing time: 03:10:41 20070211-04:34:07 Debug Step 3: debug: files=78 threads=98
**Syntax:** `QUERY LONG GLOBAL LOGNAME stresstst FROM 20070210@19:00:00 TO today@08:00:00 CONTAINS threads CONTAINS buffer`
**Results:** If the request was issued from the
command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 3 20070210-19:39:09 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 1: debug: files=23 threads=37 7 20070211-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 9 20070211-01:43:46 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug Step 1: debug: files=43 threads=67 10 20070211-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local Error Step 3: Sharing buffer exceeded 14 20070211-04:34:07 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 3: debug: files=78 threads=98
**Syntax:** `QUERY LONG GLOBAL LOGNAME stresstst CSCONTAINS "Step 1:" CSCONTAINS "Step 2:" LEVELMASK Debug`
**Results:** If the request was issued from the
command line, the result, in verbose format, could look like:
[ { Record # : 3 Date-Time : 20070210-19:39:09 Machine : automate.austin.ibm.com Handle : 37 Handle Name: Test1A User : none://anonymous Endpoint : local://local Level : Debug Message : Step 1: debug: files=23 threads=37 } { Record # : 7 Date-Time : 20070211-01:21:58 Machine : automate.austin.ibm.com Handle : 37 Handle Name: Test1A User : none://anonymous Endpoint : local://local Level : Debug Message : Step 2: debug: files=31 threads=54 } { Record # : 9 Date-Time : 20070211-01:43:46 Machine : crazy8s.austin.ibm.com Handle : 41 Handle Name: Test2 User : none://anonymous Endpoint : tcp://crazy8s.austin.ibm.com@6500 Level : Debug Message : Step 1: debug: files=43 threads=67 } ]
**Syntax:** `QUERY GLOBAL LOGNAME stresstst STATS`
**Results:** If the request was issued from the
command line, the result, in default format, could look like:
Fatal : 0 Error : 1 Warning: 1 Info : 1 Trace : 4 Trace2 : 0 Trace3 : 0 Debug : 4 Debug2 : 0 Debug3 : 0 Start : 1 Stop : 1 Pass : 1 Fail : 0 Status : 1 User1 : 1 User2 : 1 User3 : 0 User4 : 0 User5 : 0 User6 : 0 User7 : 0 User8 : 0
**Syntax:** `QUERY GLOBAL LOGNAME stresstst FROMRECORD 5 TORECORD 10 LONG`
**Results:** If the request was issued from the
command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 5 20070210-22:21:01 automate.austin.ibm.com 37 Test1A none://anonymous local://local Info Step 2: File ready on retry 3 6 20070211-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 2: processing time: 03:02:41 7 20070211-01:21:58 automate.austin.ibm.com 37 Test1A none://anonymous local://local Debug Step 2: debug: files=31 threads=54 8 20070211-01:37:25 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Trace Step 1: processing time: 03:11:53 9 20070211-01:43:46 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Debug Step 1: debug: files=43 threads=67 10 20070211-02:53:20 automate.austin.ibm.com 37 Test1A none://anonymous local://local Error Step 3: Sharing buffer exceeded
**Syntax:** `QUERY GLOBAL LOGNAME stresstst FROMRECORD 5 TORECORD 10 LEVELMASK Trace LONG`
**Results:** If the request was issued from the
command line, the result, in table format, could look like:
R# Date-Time Machine H# Name User Endpoint Level Message -- ----------------- ----------------------- -- ------ ---------------- --------------------------------- ----- ---------------------------------- 6 20070211-01:21:39 automate.austin.ibm.com 37 Test1A none://anonymous local://local Trace Step 2: processing time: 03:02:41 8 20070211-01:37:25 crazy8s.austin.ibm.com 41 Test2 none://anonymous tcp://crazy8s.austin.ibm.com@6500 Trace Step 1: processing time: 03:11:53
LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLES | HANDLE <Handle>]or
LIST SETTINGS
`GLOBAL` indicates you want to list all global logs.
`MACHINES` indicates you want to list all the machines which have
created machine logs.
`MACHINE` indicates you want to list all the machine logs for the
specified machine nickname. This option will resolve variables.
`HANDLES` indicates you want to list all the handles that have
created handle logs for the given machine.
`HANDLE` indicates you want to list all the handle logs for the
specified handle of the specified machine. This option will resolve variables.
`SETTINGS` indicates you want to list the current operational
settings.
This command requires trust level 2.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
LIST also returns codes documented in [8.9.12, "Log Error Code Reference"](#HDRLOGERR).
If successful, the result buffer will contain data based on the LIST command:
If option
`MACHINE` is specified without the
`HANDLES` option, the result buffer will contain a marshalled
`<List> of <Map:STAF/Service/Log/ListLogs>`,
which represents the machine logs for the specified machine nickname.
If both options
`MACHINE` and `HANDLE` are specified,
the result buffer will contain a marshalled
`<List> of <Map:STAF/Service/Log/ListLogs>`,
which represents the handle logs for the specified machine nickname and handle.
The map is defined as follows:
[Table 43. Definition of map class STAF/Service/Log/ListLogs]
Description: This map class represents a log file.
|Key Name||Display Name||Type||Value / Format|
|logName||Log Name|<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|upperSize||U-Size|<String>
|
|
|size||L-Size|<String>
|
|
Notes:
The "U-Size" value is the upper 32-bits of the size and the "L-Size" value is
the lower 32-bits of the size. The sizes are shown in bytes.
[Table 44. Definition of map class STAF/Service/Log/ListLocalSettings]
Description: This map class represents the settings for a Log service
whose logging mode is local.
|Key Name||Display Name||Type||Value / Format|
|loggingMode||Logging Mode|<String>
'Local'
|directory||Directory|<String>
|
|
|maxRecordSize||Max Record Size|<String>
|
|
|defaultMaxQueryRecords||Default Max Query Records|<String>
|
|
|resolveMessage||Resolve Message|<String>
'Enabled' | 'Disabled'
|resolveMessageVar||Resolve Message Var|<String>
'Enabled' | 'Disabled'
[Table 45. Definition of map class STAF/Service/Log/ListRemoteSettings]
Description: This map class represents the settings for a Log service
whose logging mode is remote.
|Key Name||Display Name||Type||Format / Value|
|loggingMode||Logging Mode|<String>
'Remote'
|remoteLogServer||Remote Log Server|<String>
|
|
|remoteLogService||Remote Log Service|<String>
|
|
**Syntax:** `LIST GLOBAL`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size --------- ----------------- ------ ------ StressTST 20070210-14:17:00 0 120823 Suite100 20070211-15:45:00 0 2622
**Syntax:** `LIST MACHINES`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
**Syntax:** `LIST MACHINE automate.austin.ibm.com`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ AutoGlob 20070210-10:54:00 0 1168
**Syntax:** LIST MACHINE automate.austin.ibm.com HANDLES
**Results:** If the request is submitted from the
command line, the result could look like:
42 43 44 45
**Syntax:** `LIST MACHINE automate.austin.ibm.com HANDLE 43`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Log Name Date-Time U-Size L-Size -------- ----------------- ------ ------ HandLog1 20070210-10:54:00 0 19043 HandLog2 20070211-18:23:00 0 45264
**Syntax:** `LIST SETTINGS`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Logging Mode : Local Directory : C:\STAF\data\STAF\service\log Max Record Size : 100000 Default Max Query Records: 100 Resolve Message : Disabled Resolve Message Var : Disabled
DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME<Logname> CONFIRM
`GLOBAL` indicates you want to delete a global log.
`MACHINE` indicates you want to delete a machine log. Specify the machine nickname. This option will resolve variables.
`HANDLE` indicates you want to delete a handle log. This option will resolve variables.
`LOGNAME` contains the name of the log you want to delete. This option will resolve variables.
`CONFIRM` confirms you really want to delete the log file.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
DELETE also returns codes documented in [8.9.12, "Log Error Code Reference"](#HDRLOGERR).
The result buffer will contain no data on return from a DELETE command.
PURGE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> CONFIRM | CONFIRMALL [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]... [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]... [CONTAINS <String>]... [CSCONTAINS <String>]... [STARTSWITH <String>]... [CSSTARTSWITH <String>]... [FROM <Timestamp> | AFTER <Timestamp>] [BEFORE <Timestamp> | TO <Timestamp>] [FROMRECORD <Num>] [TORECORD <Num>] [FIRST <Num> | LAST <Num>]
`GLOBAL` indicates you want to purge a global log.
`MACHINE` indicates you want to purge a machine log. Specify the machine nickname. This option will resolve variables.
`HANDLE` indicates you want to purge a handle log. This option will resolve variables.
`LOGNAME` contains the name of the log you want to purge. This option will resolve variables.
`CONFIRM` confirms you really want to purge the log file,
but protects you from deleting all records in the log file accidently.
`CONFIRMALL` confirms you really want to purge the log file,
even if your purge selection criteria selects every record in the log file.
**Note: **If your purge selection criteria selects every record in the log
file and you specified the `CONFIRM` option, you will receive
an error indicating you need to use the `CONFIRMALL` option instead,
or you can submit a DELETE request to the LOG service if you really want
to delete all records in the log file.
Purge allows almost the same selection options as Query.
See
[8.15.9, "QUERY"](#HDRQUERY) for a list of valid purge selection options with
the exception of TOTAL, STATS, ALL, LONG, and LEVELBITSTRING not allowed.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
PURGE also returns codes documented in [8.9.12, "Log Error Code Reference"](#HDRLOGERR).
If successful, the result buffer will contain a marshalled
`<Map:STAF/Service/Log/PurgeStats>`, representing
the number of log records that were purged and the total number of
log records. The map is defined as follows:
[Table 46. Definition of map class STAF/Service/Log/PurgeStats]
Description: This map class respresents the purge statistics for the log.
|Key Name||Display Name||Type||Format / Value|
|purgedRecords||Purged Records|<String>
|
|
|totalRecords||Total Records|<String>
|
|
For example, suppose you submitted a
`PURGE` request for a log that
contained 129 records and 21 of the records met the purge criteria you
specified. If the `PURGE` request was submitted from the
command line, the result could look like:
Purged Records: 21 Total Records : 129
**Syntax:** `PURGE GLOBAL LOGNAME stresstst CONFIRM LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"`
**Results:** If the `PURGE` request was issued from the
command line, the result could look like:
Purged Records: 8 Total Records : 17
**Syntax:** `PURGE MACHINE {STAF/Config/MachineNickname} LOGNAME test1 CONFIRM BEFORE 20080101`
**Results:** If the `PURGE` request was issued from the
command line, the result could look like:
Purged Records: 2710 Total Records : 3269
**Syntax:** `PURGE MACHINE {STAF/Config/MachineNickname} LOGNAME myTest CONFIRMALL`
**Results:** If the `PURGE` request was issued from the
command line, the result could look like:
Purged Records: 152 Total Records : 152
SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR] [RESOLVEMESSAGE | NORESOLVEMESSAGE]
See section
[8.9.3, "Parameters"](#HDRLOGPARMS) 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"](#HDRRETCODE),
SET also returns codes documented in [8.9.12, "Log Error Code Reference"](#HDRLOGERR).
The result buffer will contain no data on return from a successful SET command.
**Syntax:** `SET MaxRecordSize 150000`
**Syntax:** `SET DefaultMaxQueryRecords 50`
**Syntax:** `SET ResolveMessage`
[Table 47. Logging Levels Reference]
|Level Definition||32 Byte Bit String Representation|
Fatal
|00000000000000000000000000000001|
Error
|00000000000000000000000000000010|
Warning
|00000000000000000000000000000100|
Info
|00000000000000000000000000001000|
Trace
|00000000000000000000000000010000|
Trace2
|00000000000000000000000000100000|
Trace3
|00000000000000000000000001000000|
Debug
|00000000000000000000000010000000|
Debug2
|00000000000000000000000100000000|
Debug3
|00000000000000000000001000000000|
Start
|00000000000000000000010000000000|
Stop
|00000000000000000000100000000000|
Pass
|00000000000000000001000000000000|
Fail
|00000000000000000010000000000000|
Status
|00000000000000000100000000000000|
<Reserved1>
|00000000000000001000000000000000|
<Reserved2>
|00000000000000010000000000000000|
<Reserved3>
|00000000000000100000000000000000|
<Reserved4>
|00000000000001000000000000000000|
<Reserved5>
|00000000000010000000000000000000|
<Reserved6>
|00000000000100000000000000000000|
<Reserved7>
|00000000001000000000000000000000|
<Reserved8>
|00000000010000000000000000000000|
<Reserved9>
|00000000100000000000000000000000|
User1
|00000001000000000000000000000000|
User2
|00000010000000000000000000000000|
User3
|00000100000000000000000000000000|
User4
|00001000000000000000000000000000|
User5
|00010000000000000000000000000000|
User6
|00100000000000000000000000000000|
User7
|01000000000000000000000000000000|
User8
|10000000000000000000000000000000|**Note: **The **User1-8** logging levels have been set aside for the user of
STAFLog to implement as deemed necessary. You may decide that for a
testcase or test suite that you want to log a certain behavior
as "User1" for example. This will enable you to easily extract
log records associated with level "User1".
**Note: **The **<Reserved1-8>** levels cannot be used and as the name implies,
they are reserved by STAF for future use. If you would like to see a common
logging level added to this list, please contact the document
owners for discussion.
In addition to the common STAF return codes (see
[Appendix A, "API Return Codes"](#HDRRETCODE) for additional information),
the following Log return codes are defined:
[Table 48. Log Service Return Codes]
|Error Code||Meaning||Comment|
4004
|Invalid level||An invalid logging level was specified.
See |
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"](#HDRRETCODE).
On successful return, the result buffer will contain the version number.
**Syntax:**
`VERSION`
**Results:**
3.4.6
WHOAMI will display information about who a system thinks you are. This can be useful in debugging trust issues and other problems.
WHOAMI
This command requires trust level 1.
All return codes from WHOAMI are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer for a
`WHOAMI` request
will contain a marshalled `<Map:STAF/Service/Misc/Whoami>`
representing information about who a system thinks you are.
The map is defined as follows:
[Table 49. Definition of map class STAF/Service/Misc/Whoami]
Description: This map class represents information about
who a system thinks you are.
|Key Name||Display Name||Type||Format / Value|
|instanceName||Instance Name|<String>
|
|
|instanceUUID||Instance UUID|<String>
|
|
|requestNumber||Request Number|<String>
|
|
|interface||Interface|<String>
|
|
|logicalID||Logical ID|<String>
|
|
|physicalID||Physical ID|<String>
|
|
|endpoint||Endpoint|<String>
|
|
|machine||Macine|<String>
|
|
|machineNickname||Machine Nickname|<String>
|
|
|isLocalRequest||Local Request|<String>
'Yes' | 'No'
|handle||Handle|<String>
|
|
|handleName||Handle Name|<String>
|
|
|user||User|<String>
|
|
|trustLevel||Trust Level|<String>
|
|
Notes:
**Syntax:**
`WHOAMI`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Request Number : 1812 Interface : tcp Logical ID : server1.austin.ibm.com Physical ID : 9.41.53.147 Endpoint : tcp://server1.austin.ibm.com@6500 Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : No Handle : 33 Handle Name : myHandle User : authSample://User1 Trust Level : 5
**Syntax:**
`WHOAMI`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Request Number : 92 Interface : local Logical ID : local Physical ID : local Endpoint : local://local Machine : server1.austin.ibm.com Machine Nickname: Server1 Local Request : Yes Handle : 29 Handle Name : STAF/Client User : none://anonymous Trust Level : 5
WHOAREYOU will display information about a system, such as the STAF instance name, instance UUID, machine name (the value of the STAF/Config/Machine system variable for the machine), machine nickname, (the value of the STAF/Config/MachineNickname variable for the machine) and if it's the same system as the machine who submitted the request.
WHOAREYOU
This command requires trust level 1.
All return codes from WHOAREYOU are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer for a
`WHOAREYOU` request
will contain a marshalled `<Map:STAF/Service/Misc/WhoAreYou>`
representing information about a system.
The map is defined as follows:
[Table 50. Definition of map class STAF/Service/Misc/WhoAreYou]
Description: This map class represents information about
a system.
|Key Name||Display Name||Type||Format / Value|
|instanceName||Instance Name|<String>
|
|
|instanceUUID||Instance UUID|<String>
|
|
|machine||Macine|<String>
|
|
|machineNickname||Machine Nickname|<String>
|
|
|isLocalRequest||Local Request|<String>
'Yes' | 'No'
|currentTimestamp||Current Date-Time|<String>
|<YYYYMMDD-HH:MM:SS>|
Notes:
**Syntax:**
`WHOAREYOU`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Instance Name : STAF Instance UUID : 648C8241CC0B00000929359375636173 Machine : server1.austin.ibm.com Machine Nickname : Server1 Local Request : No Current Date-Time: 20100615-14:46:30
**Syntax:**
`WHOAREYOU`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Instance Name : STAF Instance UUID : 711E9E411B0A00000929359245636173 Machine : client2.austin.ibm.com Machine Nickname : client2.austin.ibm.com Local Request : Yes Current Date-Time: 20100615-15:35:11
LIST allows you to obtain information about the interfaces (aka connection providers) that are enabled for a system, or you can list the current operational settings for STAF, or you can show the cached endpoints used by automatic interface cycling or, or you can list the STAF install properties.
LIST INTERFACES | SETTINGS | ENDPOINTCACHE | PROPERTIES
`INTERFACES` specifies that you want information for interfaces.
`SETTINGS` specifies that you want to list the current operational
settings for STAF.
`ENDPOINTCACHE` specifies that you want to show the cached
endpoints used by automatic interface cycling.
`PROPERTIES` specifies that you want to list the install
properties for STAF.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
[Table 51. Definition of map class STAF/Service/Misc/Interface]
Description: This map class represents an interface.
|Key Name||Display Name||Type||Format / Value|
|name||Interface Name|<String>
|
|
|library||Library|<String>
|
|
|optionMap||Options|<Map> of <String>
|
|
Notes:
[Table 52. Definition of map class STAF/Service/Misc/Settings]
Description: This map class represents the operational
settings for STAF.
|Key Name||Display Name||Type||Format / Value|
|connectAttempts||Connection Attempts|<String>
|
|
|connectRetryDelay||Connect Retry Delay|<String>
|
|
|interfaceCycling||Interface Cycling|<String>
'Enabled' | 'Disabled'
|maxQueueSize||Maximum Queue Size|<String>
|
|
|maxReturnFileSize||Maximum Return File Size|<String>
|
|
|handleGCInterval||Handle GC Interval|<String>
'5000' - '86400000'
|initialThreads||Initial Threads|<String>
|
|
|threadGrowthDelta||Thread Growth Delta|<String>
|
|
|dataDir||Data Directory|<String>
|
|
|defaultInterface||Default Interface|<String>
|
|
|defaultAuthenticator||Default Authenticator|<String>
|
|
|resultCompatibilityMode||Result Compatibility Mode|<String>
'Verbose' | 'None'
[Table 53. Definition of map class STAF/Service/Misc/EndpointCache]
Description: This map class represents an cached endpoint.
|Key Name||Display Name||Type||Format / Value|
|endpoint||Endpoint|<String>
|
|
|interface||Interface|<String>
|
|
|createdTimestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
Notes:
[Table 54. Definition of map class STAF/Service/Misc/Properties]
Description: This map class represents the install properties
for STAF.
|Key Name||Display Name||Type||Format / Value|
|version||version|<String>
|
|
|platform||platform|<String>
|
|
|architecture||architecture|<String>
'32-bit' | '64-bit'
|installer||installer|<String>
'IA' | 'IA_NoJVM' | 'STAFInst'
|file||file|<String>
|
|
|osname||osname|<String>
|
|
|osversion||osversion|<String>
|"*" indicates the build is supported on any version of the OS; a version number followed by a "+" indicates the build supports that version or later|
|osarch||osarch|<String>
|
|
**Syntax:**
`LIST INTERFACES`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
[ { Interface Name: local Library : STAFLIPC Options : { IPCMethod: Shared memory IPCName : STAF } } { Interface Name: ssl Library : STAFTCP Options : { ConnectTimeout : 5000 Port : 6550 Protocol : IPv4 SSL/CACertificate : C:\STAF\bin\CAList.crt SSL/ServerCertificate: C:\STAF\bin\STAFDefault.crt SSL/ServerKey : C:\STAF\bin\STAFDefault.key Secure : Yes } } { Interface Name: tcp Library : STAFTCP Options : { ConnectTimeout: 5000 Port : 6500 Protocol : IPv4 Secure : No } } { Interface Name: alt-tcp Library : STAFTCP Options : { ConnectTimeout: 30000 Port : 6502 Protocol : IPv6 Secure : No } } ]
**Syntax:**
`LIST SETTINGS`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Connection Attempts : 2 Connect Retry Delay : 1000 Interface Cycling : Enabled Maximum Queue Size : 10000 Maximum Return File Size : 0 Handle GC Interval : 60000 Initial Threads : 10 Thread Growth Delta : 1 Data Directory : c:\STAF\data\STAF Default Interface : tcp Default Authenticator : none Result Compatibility Mode: Verbose
**Syntax:**
`LIST ENDPOINTCACHE`
**Results:** If the request is issued from the command line,
the result, in tabular format, could look like:
Endpoint Interface Date-Time -------------------- --------- ----------------- machine1 tcp2 20051101-16:42:41 machine1.company.com tcp2 20051102-11:11:37 machine2.company.com tcp3 20051101-15:23:59 machine3 tcp2 20051102-09:05:34
**Syntax:**
`LIST PROPERTIES`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
version : 3.4.22 platform : win32 architecture: 32-bit installer : IA file : STAF3422-setup-win32.exe osname : Windows osversion : * osarch : x86
QUERY allows you to obtain detailed information about an enabled interface (aka connection provider).
QUERY INTERFACE <Name>
`INTERFACE` specifies the name of the interface you want
information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer for a
`QUERY INTERFACE`
request will contain a marshalled
`<Map:STAF/Service/Misc/Interface>`
representing the specified interface (aka connection provider).
The map is defined as follows:
[Table 55. Definition of map class STAF/Service/Misc/Interface]
Description: This map class represents an interface.
|Key Name||Display Name||Type||Format / Value|
|name||Interface Name|<String>
|
|
|library||Library|<String>
|
|
|optionMap||Options|<Map> of <String>
|
|
Notes:
**Syntax:**
`QUERY INTERFACE ssl`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Interface Name: ssl Library : STAFTCP Options : { ConnectTimeout : 5000 Port : 6550 Protocol : IPv4 SSL/CACertificate : C:\STAF\bin\CAList.crt SSL/ServerCertificate: C:\STAF\bin\STAFDefault.crt SSL/ServerKey : C:\STAF\bin\STAFDefault.key Secure : Yes } }
**Syntax:**
`QUERY INTERFACE tcp`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Interface Name: tcp Library : STAFTCP Options : { ConnectTimeout: 5000 Port : 6500 Protocol : IPv4 Secure : No } }
**Syntax:**
`QUERY INTERFACE local`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Interface Name: local Library : STAFLIPC Options : { IPCMethod: Shared memory IPCName : STAF } }
Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>] [MAXQUEUESIZE <Number>] [HANDLEGCINTERVAL <Number>[s|m|h|d]] [INTERFACECYCLING <Enabled | Disabled>] [DEFAULTINTERFACE <Name>] [DEFAULTAUTHENTICATOR <Name>] [RESULTCOMPATIBILITYMODE <Verbose | None>]
See section
[4.7, "Operational parameters"](#HDROPPARMS) 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"](#HDRRETCODE).
The result buffer will contain no data on return from a successful SET command.
**Syntax:** `SET MAXQUEUESIZE 50`
**Syntax:** `SET CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2s`
**Syntax:** `SET INTERFACECYCLING Disabled`
**Syntax:** `SET DEFAULTINTERFACE tcp`
**Syntax:** `SET HANDLEGCINTERVAL 50s`
PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM>
`ENDPOINTCACHE` indicates that you want to purge one or
more endpoints from the endpoint cache.
`ENDPOINT` specifies the endpoint that you want to purge.
This option will resolve variables.
`CONFIRM` indicates that you really want to purge the entire
contents of the endpoint cache.
This command requires trust level 5.
All return codes from
`PURGE` are documented in [Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain a marshalled
`<Map:STAF/Service/Misc/PurgeStats>`, representing the number
of endpoints that were purged and the number of endpoints remaining in the
endpoint cache. The map is defined as follows:
[Table 56. Definition of map class STAF/Service/Misc/PurgeStats]
Description: This map class represents the purge statistics
for the endpoint cache.
|Key Name||Display Name||Type||Format / Value|
|numPurged||Purged Endpoints|<String>
|
|
|numRemaining||Remaining Endpoints|<String>
|
|
**Syntax:** `PURGE ENDPOINTCACHE ENDPOINT client1 ENDPOINT client1.company.com`
**Results:** If the request is issued from the command line,
the result, in tabular format, could look like:
Purged Endpoints : 2 Remaining Endpoints: 8
**Syntax:** `PURGE ENDPOINTCACHE CONFIRM`
**Results:** If the request is issued from the command line,
the result, in tabular format, could look like:
Purged Endpoints : 8 Remaining Endpoints: 0
SERVICE <Name> LIBRARY STAFMon PARMS <Parms>
`<Name>` is the name by which the Monitor service will be known on this machine.
`<Parms>` is any parameters that are accepted at initialization time. The same
parameters for the Monitor SET command can be specified during initialization time. See the
Monitor SET command for details on the available parameters.
service Monitor library STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 512"
**Note: **Note that this variable will only be examined if the ENABLERESOLVEMESSAGEVAR option
is set either during the Monitor registration (via the PARMS options) or by use of the
SET ENABLERESOLVEMESSAGEVAR Monitor command.
**Note: **The default if STAF/Service/ `<Name>`/ResolveMessage is not specified, is
not to resolve messages. This is due to the fact that you can resolve variables
yourself before logging messages and the fact that the messages could be quite
large. This can be overridden on a per message basis by using the
RESOLVEMESSAGE or NORESOLVEMESSAGE option.
LOG MESSAGE <Message> [NAME <Name>] [RESOLVEMESSAGE | NORESOLVEMESSAGE]
`MESSAGE` contains the message (data) that you want to write to
the monitor. This option will not resolve messages by default but can be
configured to do so in the STAF configuration file or by using RESOLVEMESSAGE.
Any private data in the message will be masked before writing to the monitor.
`NAME` indicates that the status message should be written to the
specified named monitor. This option will be resolved for variables. If this
option is not specified, the status message will be written to the originating
handle's monitor.
`RESOLVEMESSAGE` causes the MONITOR service to call the STAF
variable service to resolve any variables in the message before being written.
`NORESOLVEMESSAGE` causes the MONITOR service to not call the STAF
variable service to resolve any variables in the message.
This command requires trust level 3.
All return codes from LOG are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a LOG command.
QUERY MACHINE <Machine Nickname> < HANDLE <Handle> | NAME <Name> >
`MACHINE` determines what machine the monitor message originated
from. This option will resolve variables.
`HANDLE` determines the process handle that originated the
message. This option will resolve variables.
`NAME` determines the name of the
message. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain a marshalled
`<Map:STAF/Service/Monitor/MonitorInfo>`, representing
the last monitor message generated by the specified machine/handle or
for the specified machine/name..
The map is defined as follows:
[Table 57. Definition of map class STAF/Service/Monitor/MonitorInfo]
Description: This map class represents a monitor message.
|Key Name||Display Name||Type||Format / Value|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|message||Message|<String>
|
|
Notes:
The "Date-Time" is the date/time at which the last monitor
message was logged.
**Syntax:** `QUERY MACHINE automate.austin.ibm.com HANDLE 32`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Date-Time: 20040911-16:00:32 Message : Testcase aborted with error "255"
**Syntax:** `QUERY MACHINE testmachine1 HANDLE 85`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Date-Time: 20041022-17:58:01 Message : TestC: Step 2 of 5
**Syntax:** `QUERY MACHINE automate.austin.ibm.com NAME ActiveXYZRequests`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Date-Time: 20061205-08:24:01 Message : TestW: Step 32 of 109
LIST <MACHINES | MACHINE <Machine> [NAMES] | SETTINGS>
`MACHINES` indicates you want list all the machine nicknames that
have created monitor data.
`MACHINE` indicates you want to list the monitor data for the
specified machine nickname. This option will resolve variables. If the `NAMES` option is
specified, only the monitor data for named monitors will be displayed;
otherwise, the monitor data for (un-named) process handles will be displayed.
`NAMES` indicates you want to list the named monitors for the
specified machine nickname. This option will resolve variables.
`SETTINGS` returns the Monitor settings.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain data based on the LIST command:
[Table 58. Definition of map class STAF/Service/Monitor/HandleInfo]
Description: This map class represents the handle that generated
the monitor message on the specified machine.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle|<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|size||Size|<String>
|
|
Notes:
The "Date-Time" is the date/time at which the last monitor
message was logged.
The "Size" is the size of the last monitor message logged.
[Table 59. Definition of map class STAF/Service/Monitor/NameInfo]
Description: This map class represents the named monitors
on the specified machine.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|size||Size|<String>
|
|
Notes:
The "Date-Time" is the date/time at which the last monitor
message was logged.
The "Size" is the size of the last monitor message logged.
[Table 60. Definition of map class STAF/Service/Monitor/Settings]
Description: This map class represents the settings for
the Monitor service.
|Key Name||Display Name||Type||Value|
|maxRecordSize||Max Record Size|<String>
|
|
|resolveMessage||Resolve Message|<String>
Enabled | Disabled
|resolveMessageVar||Resolve Message Var|<String>
Enabled | Disabled
**Syntax:** `LIST MACHINES`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
automate.austin.ibm.com testmachine1
**Syntax:** `LIST MACHINE automate.austin.ibm.com`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 34 20040910-16:29:03 30 36 20040910-16:29:13 148 37 20040910-16:29:19 97 68 20040911-16:00:32 43
**Syntax:** `LIST MACHINE testmachine1`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Date-Time Size ------ ----------------- ---- 20 20041022-17:43:05 25
**Syntax:** `LIST MACHINE automate.austin.ibm.com NAMES`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Name Date-Time Size ----------------- ----------------- ---- ActiveXYZRequests 20061205-13:50:06 39 test1 20061205-13:54:14 25
**Syntax:** `LIST SETTINGS`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Max Record Size : 512 Resolve Message : Enabled Resolve Message Var: Disabled
DELETE [BEFORE <Timestamp> | MACHINE <Machine> NAME <Name>] CONFIRM
`BEFORE` specifies that you only want to delete monitor data
recorded prior to the specified timestamp. If `BEFORE` is not
specified, all handle/name monitor data will be removed. The keyword **
can be used for TODAY** `MACHINE` is the machine nickname for the named monitor to be
deleted.
`NAME` is the named monitor to be deleted.
`CONFIRM` confirms you really want to delete the monitor
data.
This command requires trust level 4.
All return codes from DELETE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a DELETE command.
**Syntax:** `DELETE BEFORE TODAY CONFIRM`
**Syntax:** `DELETE BEFORE 20070101 CONFIRM`
**Syntax:** `DELETE CONFIRM`
**Syntax:** `DELETE MACHINE automate.austin.ibm.com NAME ActiveXYZRequests CONFIRM`
SET [RESOLVEMESSAGE | NORESOLVEMESSAGE] [MAXRECORDSIZE <Size>] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
`RESOLVEMESSAGE` causes the MONITOR service to call the STAF
variable service to resolve any variables in Monitor Log messages before being
written.
`NORESOLVEMESSAGE` causes the MONITOR service to not call the STAF
variable service to resolve any variables in Monitor Log messages before being
written. This is the default.
`MAXRECORDSIZE <Size>` sets the Maximum record size for Monitor
data. The default is 1024 bytes.
`ENABLERESOLVEMESSAGEVAR` causes STAF/Service/<Name>/ResolveMessage
variable to be queried for every Monitor Log command, to determine if variables
in the Monitor Log command should be resolved.
`DISABLERESOLVEMESSAGEVAR` causes STAF/Service/<Name>/ResolveMessage
variable to not be queried for every Monitor Log command. This is the default.
The highest priority in defining whether variables in a Monitor Log command
are to be resolved will be the
`RESOLVEMESSAGE/NORESOLVEMESSAGE` specified directly in the
Log command. If the Monitor Log command contains neither option, then if
`ENABLERESOLVEMESSAGEVAR` is set, the variable
STAF/Service/<Name>/ResolveMessage will be examined to determine whether to
resolve the message. If `DISABLERESOLVEMESSAGEVAR` is set, then the
`RESOLVEMESSAGE/NORESOLVEMESSAGE` option (set via the PARMS options or
by use of the `SET RESOLVEMESSAGE/NORESOLVEMESSAGE` Monitor command)
will be honored.
This command requires trust level 5.
All return codes from SET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE) 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"](#HDRRETCODE).
The result buffer will contain PONG on a successful return from a PING command.
The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.).
**Syntax and Results:**
C:\>STAF local PING PING Response -------- PONG
**Syntax and Results:**
C:\>STAF host1.company.com PING PING Response -------- PONG
If STAFProc is not running on machine host1.company.com or you cannot communicate via STAF to that machine, you would get an RC 16 (No path to endpoint) and an error message. For example:
C:\>STAF host1.company.com PING PING Error submitting request, RC: 16 Additional info --------------- STAFConnectionProviderConnect: Timed out connecting to endpoint: select() timeou t: 22, Endpoint: tcp://host1.company.com
Note that you can get more information on return code 16 (and other STAF return codes) by using the Help service. For example:
C:\>STAF local HELP ERROR 16 Response -------- Description: No path to endpoint Details : This indicates that STAFProc was not able to submit the request to the requested endpoint (i.e. machine). This error usually indicates that STAF i s not running on the target machine, or that the requested endpoint is not valid , or that the network interface or port for the requested endpoint is not suppor ted, or that a firewall is blocking communication via the port for the requested endpoint, or that a secure network interface is being used to communicate to a machine that doesn't have a secure network interface configured with the same ce rtificate. Alternatively, you may need to increase your CONNECTTIMEOUT value fo r the network interface and/or increase your CONNECTATTEMPTS value in your STAF. cfg file.
**Syntax and Results:**
C:\>STAF host1.company.com PING PING MACHINE host2.company.com Response -------- PONG
**Syntax and Results:**
C:\>STAF host1.company.com PING PING MACHINE host2.company.com@6501 Response -------- PONG
The PROCESS service is one of the internal STAF services. It provides the following commands
START allows you to start a process. Processes may be started synchronously or asynchronously. You may also specify to which workload they belong, parameters to pass to them, their working directory, any process specific STAF variables to set for them, as well as any environment variables they may need.
START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>] [VAR <Variable=Value>]... [ENV <Variable=Value>]... [USEPROCESSVARS] [WORKLOAD <Name>] [TITLE <Title>] [WAIT [<Number>[s|m|h|d|w]] | ASYNC] [STOPUSING <Method>] [STATICHANDLENAME <Name>] [NEWCONSOLE | SAMECONSOLE] [FOCUS <Background | Foreground | Minimized>] [USERNAME <User name> [PASSWORD <Password>]] [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>] [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT] [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]... [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>] [MACHINE <Machine>] [PRIORITY <Priority>] [KEY <Key>]]
`WORKLOAD` allows you to specify the name of the workload for which this
process is a member. This may be useful in conjunction with other PROCESS
commands. The default is no workload name. This option will resolve variables using the `IGNOREERRORS` option.
`TITLE` allows you to specify the program title of the process.
Unless overridden by the process, the `TITLE` will be the text that
is displayed on the title bar of the application. This option will resolve variables using the `IGNOREERRORS` option.
`COMMAND` specifies the actual command that you want to start. If
the path to the command is not specified, the system PATH will be searched
for the command. Only actual executable files, such as .EXEs, can be STARTed.
Rexx files cannot be STARTed directly.
On Windows systems, they need to be started through REXX.EXE.
This option will resolve variables using the `IGNOREERRORS` option. This option will handle private data.
`PARMS` specifies any parameters that you wish to pass to the
command. This option will resolve variables using the `IGNOREERRORS` option. This option will handle private data.
`SHELL` specifies that `COMMAND` should be started via a
separate shell. Using a separate shell allows complex commands involving
pipelines to be readily executed. This option will resolve variables using the `IGNOREERRORS` option.
Note, if `COMMAND` and `PARMS` are both specified they will be
concatenated with a space between them, and the resulting string is what will
be executed.
You may specify an optional shell, which overrides any defaults specified in the
STAF configuration file. See [4.7, "Operational parameters"](#HDROPPARMS) for more information on how
to specify the shell.
`WORKDIR` specifies the directory from which the command should be
executed. If you do not specify `WORKDIR`, the command will be
started from whatever directory STAFProc is currently in. This option will resolve variables using the `IGNOREERRORS` option.
`WAIT` specifies that the START request should not return until the
process has finished executing. You may specify an optional time duration,
after which the request should return. If no time duration is specified,
the request will wait indefinitely until the process has finished executing.
If the `WAIT` does not timeout, the process termination information
will not be saved after the process ends, and no FREE is necessary. This option will resolve variables.
The time duration may be expressed in milliseconds, seconds, minutes,
hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w],
where <Number> is an integer >= 0 and indicates milliseconds unless one
of the following case-insensitive suffixes is specified:
`ASYNC` specifies that the process should be started asynchronously,
and that the START request should return to the caller as soon as the process
has begun execution. In this case, the process termination will be saved after
the process ends, and will later need to be FREE'd. This is the default.
`VAR` allows you to specify variables that go into the process
specific variable pool.
`ENV` allows you to specify environment variables that will be set
for the process. Environment variables may be mixed case, however most
programs assume environment variable names will be uppercase, so, in most
cases, ensure that your environment variable names are all in uppercase.
This option will resolve variables using the `IGNOREERRORS` option.
`USEPROCESSVARS` specifies that variable references should try to
be resolved from the variable pool associated with the process being started
first. If the variable is not found in this pool, originating handle's pool,
originator's shared pool, and originator's system pool should be searched if
the request came from local, otherwise originator's handle's pool, originator's
shared pool, remote shared pool and remote system pool should be searched.
`STOPUSING` allows you to specify the method by which this process
will be STOPed, if not overridden on the STOP command. See [8.13.3, "STOP"](#HDRPSSTOP)
for more information. This option will resolve variables using the `IGNOREERRORS` option.
`NEWCONSOLE` specifies that the process should get a new console
window. So, if a process's stdout/stderr is not redirected, it will be
unavailable. This is the default for Windows systems.
`SAMECONSOLE` specifies that the process should share the STAFProc
console. So, if a process's stdout/stderr is not redirected, it will be
written to STAFProc's stdout/stderr. This is the default for Unix systems.
`FOCUS` specifies the focus that is to be given to new windows
opened when starting a process on a Windows system. The window(s) it effects
depends on whether you are using the default command mode or the shell command
mode. If the process is started using the default command mode (no
`SHELL` option), then the specified focus specified is given to any
new windows opened by the specified command. Otherwise, if the process is
started using the shell command mode, then the specified focus is given only
to the new shell command window opened, not to any windows opened by the
specified command. This option only has effect on Windows systems. This option will resolve variables using the `IGNOREERRORS` option.
This option was added in STAF V3.1.4. Recognized values are the following:
`USERNAME` specifies the username under which the process should be
started. This option will resolve variables using the `IGNOREERRORS` option.
**Note: **The PROCESSAUTHMODE operational parameter must be enabled in the STAF
configuration file on the system where the process is run under a different
username. See [4.7, "Operational parameters"](#HDROPPARMS) 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"](#HDRWINUSER) for more information.
`PASSWORD` specifies the password with which to authenticate the user
specified with `USERNAME`. This option will handle private data. This option will resolve variables.
`DISABLEDAUTHISERROR` specifies that an error should be returned if
a `USERNAME/PASSWORD` is specified but authentication has been
disabled. This option overrides any default specified in the STAF configuration
file.
`IGNOREDISABLEDAUTH` specifies that any `USERNAME/PASSWORD`
specified on the request is ignored if authentication is disabled. This option
overrides any default specified in the STAF configuration file.
`STATICHANDLENAME` specifies that a static handle should be created
for this process. The name specified for this option will be the registered
name of the static handle. Using this option will also cause the environment
variable STAF_STATIC_HANDLE to be set appropriately for the process.
See ["Using the STAF command from shell-scripts"](#HDRSTAFSHS) for more information on static handles. This option will resolve variables using the `IGNOREERRORS` option.
`STDIN` specifies the name of the file from which standard input
will be read. This option will resolve variables using the `IGNOREERRORS` option.
`STDOUT` specifies the name of the file to which standard output
will be redirected. If the file already exists, it will be replaced.
If the directory path specified for the file does not exist, it will be created.
This option will resolve variables using the `IGNOREERRORS` option.
`STDOUTAPPEND` specifies the name of the file to which standard
output will be redirected. If the file already exists, the process' standard
output will be appended to it. If the directory path specified for the file
does not exist, it will be created. This option will resolve variables using the `IGNOREERRORS` option.
`STDERR` specifies the name of the file to which standard error
will be redirected. If the file already exists, it will be replaced.
If the directory path specified for the file does not exist, it will be created.
This option will resolve variables using the `IGNOREERRORS` option.
`STDERRAPPEND` specifies the name of the file to which standard
error will be redirected. If the file already exists, the process' standard
error will be appended to it. If the directory path specified for the file
does not exist, it will be created. This option will resolve variables using the `IGNOREERRORS` option.
`STDERRTOSTDOUT` specifies that standard error should be redirected
to the same file to which standard output is being redirected. This option is
valid only if `STDOUT` or `STDOUTAPPEND` or `RETURNSTDOUT` is specified.
`RETURNSTDOUT` specifies that the contents of the file to which
standard output was redirected should be returned when the process completes.
If `STDOUT` is not specified, standard output will be redirected
to a temporary file.
If `STDERRTOSTDOUT` is specified, the file returned
will contain both standard output and standard error.
This information is only available if using the `WAIT` or
`NOTIFY` options.
`RETURNSTDERR` specifies that the contents of the file to which
standard error was redirected should be returned when the process completes.
If `STDERR` is not specified, standard error will be redirected
to a temporary file.
This information is only available if using the `WAIT` or
`NOTIFY` options.
`RETURNFILE` specifies that the contents of the specified file
should be returned when the process completes. This information is only
available if using the `WAIT` or `NOTIFY` options. This option will resolve variables using the `IGNOREERRORS` option.
`NOTIFY ONEND` specifies that you wish to send a notification
when this process ends. See [8.13.8, "NOTIFY REGISTER/UNREGISTER"](#HDRPROCREG) for the content of the
notification message.
`MACHINE` specifies the machine to which the notification should
be sent. The default is the machine submitting the request. This option will resolve variables using the `IGNOREERRORS` option.
`PRIORITY` specifies the priority of the notification message.
The default is 5. This option will resolve variables.
`KEY` specifies a key that will be included in the notification
message. This option will resolve variables using the `IGNOREERRORS` option.
`HANDLE` specifies the handle to which the notification should be
sent. The default is the handle of the process submitting the request.
This option will resolve variables.
`NAME` specifies the registered name of the process(es) to which
the notification should be sent. This option will resolve variables using the `IGNOREERRORS` option.
This command requires trust level 5.
All return codes from START are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The maps are defined as follows:
[Table 61. Definition of map class STAF/Service/Process/CompletionInfo]
Description: This map class represents completion information
for a process.
|Key Name||Display Name||Type||Format / Value|
|rc||Return Code|<String>
|
|
|key||Key|<String> | <None>
|
|
|fileList||Files|<List> of <Map:STAF/Service/Process/ReturnFileInfo>
|
|
Notes:
The "Files" value will contain a list of information about the files
requested to be returned, or an empty list if no files were requested
to be returned. Files will be returned in the order of standard output,
then standard error, then any files specified with the RETURNFILE
option.
[Table 62. Definition of map class STAF/Service/Process/ReturnFileInfo]
Description: This map class represents a file returned by the process.
|Key Name||Display Name||Type||Format / Value|
|rc||Return Code|<String>
|
|
|data||Data|<String>
|
|
Notes:
For each file, a standard STAF return code indicating the success or failure
of retrieving the file's contents is provided. If the file's return code
is 0, then the data contained in the file is also provided.
If the file's return code is 58 (Maximum Size Exceeded), that indicates
that the file size exceeded the maximum return file size.
For example, suppose a
`PROCESS START COMMAND "java TestA" WAIT`
request is submitted from the command line, and assume that the
process completed successfully and returned 0.
The result, in verbose format, could look like the following:
{ Return Code: 0 Key : <None> Files : [] }
For example, suppose a
`PROCESS START COMMAND "java TestA" RETURNSTDOUT RETURNSTDERR WAIT`
request is submitted from the command line, and assume that the
process completed successfully and returned 0, that the
standard output of the process was simply "Success !!!", and that the
standard error of the process was blank.
The result, in verbose format, could look like the following:
{ Return Code: 0 Key : <None> Files : [ { Return Code: 0 Data : Success !!! } { Return Code: 0 Data : } ] }
The following examples show the syntax, and results using the STAF command executable from a Windows command prompt. These STAF requests could also be submitted from a program (e.g. Java, C++, Perl, shell, etc.) or via a <process> element in a STAX job.
**Syntax and Results:**
C:\>STAF local PROCESS START SHELL COMMAND "java -version" Response -------- 35The result buffer contains the handle number of the process that was started (which in this case is 35). This is not the return code of the process as the process was started asynchronously (no
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
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 (
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
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
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
@echo off EXIT /B 99
**Syntax and Results:**
C:\>STAF client2 PROCESS START SHELL COMMAND "C:/test.bat & set PROCESSRC=%ERRORLEVEL% & exit %PROCESSRC%" WAIT Response -------- { Return Code: 99 Key : <None> Files : [] }
The following examples show the goal and the syntax of the request to submit to the
`PROCESS` service but not the results.
**Syntax:**
`START COMMAND tc1.exe TITLE "Testcase 1" WORKDIR d:/testcase ENV RUNMODE=Type1 ENV AUTO=1`
**Syntax:**
`START COMMAND tc2 WORKDIR d:/webtests VAR WebServer=testsrv1.test.austin.ibm.com VAR RunMode=1 WORKLOAD "Web Tests" WAIT`
**Syntax:**
`START COMMAND {WWWTestDir}/www1.exe WORKDIR {WWWTestDir} WAIT 30m`
**Syntax:**
`START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND`
**Syntax:**
`START COMMAND tc2.exe WORKDIR c:/testcase NOTIFY ONEND PRIORITY 1 MACHINE EventController NAME ProcessHandler KEY 9bt1az54fq`
**Syntax:**
`START COMMAND tc2.exe WORKDIR c:/testcase STOPUSING SIGINT`
**Syntax:**
`START COMMAND tc2.exe WORKDIR c:/testcase SAMECONSOLE`
**Syntax:**
`START COMMAND tc2 WORKDIR /testcases USERNAME testuser PASSWORD !!@tupass@!!`
**Syntax:**
`START COMMAND tc2 WORKDIR /testcase STDOUT /testcases/tc2/stdout.txt`
**Syntax:**
`START COMMAND tc3.sh STATICHANDLENAME "Test case 3"`
**Syntax:**
`START SHELL COMMAND "ps | grep test | wc >testcount.txt"`
**Syntax:**
`START SHELL COMMAND "grep 'Count = ' /tests/out | awk '{print $5}'" STDOUT /tests/awk.out STDERRTOSTDOUT`
**Note:** When using STAF V3.4.0 or later, you no longer have to use
a caret (^) as an escape character for "{" if it does not denote a variable
reference because the `IGNOREERRRORS` option is used when submitting a
VAR RESOLVE request to resolve variables in option values on a PROCESS START request.
**Syntax:**
`START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT`
**Syntax:**
`START COMMAND tc3.sh STDOUT /tmp/tc3.out STDERRTOSTDOUT WAIT RETURNSTDOUT RETURNFILE /tmp/tc3.results`
**Syntax:**
`START COMMAND tc3.sh STDERRTOSTDOUT WAIT RETURNSTDOUT`
**Syntax:**
`START SHELL "D:/Cygwin/bin/bash.exe -c %C" COMMAND "D:/tests/test1.sh machA" WORKDIR D:/tests`
**Syntax:**
`START SHELL "xterm -title %T -e /bin/sh -c %X" COMMAND "/tests/test1.sh machA" TITLE "Test 1" STDOUT /tests/test1.out`
**Syntax:**
`START SHELL "/bin/csh -c %C" COMMAND "/tests/test1.sh machA" WORKDIR /tests`
**Syntax:**
`START SHELL 'su - %u -c %C' COMMAND 'echo $HOME' USERNAME test WAIT STDOUT /temp/test.out STDERRTOSTDOUT RETURNSTDOUT`
To start a process under a different user name on a Windows system, the following requirements must be met:
There are operating system limitations on how many processes can run concurrently under a
different user in the same desktop. If you get RC 10 with OS RC 1816, and the user name
that the process is being run under is not a member of the Administrator group, then you
may want to give it the "Increase quotas" user right so that more processes can
run concurrently. See
["Changing User Rights Assignments"](#HDRWINUSERRIGHTS) for more information on how to change
user rights assignments.
If you are having problems starting a process under a different user name, use the Trace service
to enable error and warning trace points to see if you get more information.
This information is provided to help you change user rights assignments as needed to start a process under a different user name.
On Windows Vista systems, to view or modify user rights assignments in the local security policy, perform the following:
On Windows XP systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:
STOP allows you to stop a process that was started via STAF (e.g. a process that was started by submitting a START request to the PROCESS service). You may stop a single process, all processes that are part of a given workload, or all processes started by STAF.
STOP <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
`ALL` specifies that you want to stop all running processes that
STAF has STARTed. If you wish to do this, you must also specify the
`CONFIRM` option.
`WORKLOAD` specifies that you want to stop all processes that are
part of a given workload. This option will resolve variables.
`HANDLE` specifies that only the specified handle should be stopped. This option will resolve variables.
`USING` specifies the method used to stop the process. This option will resolve variables.
The following methods are supported:
This command requires trust level 4.
All return codes from STOP are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
[Table 63. Definition of map class STAF/Service/Process/StopInfo]
Description: This map class represents statistics for
stopped processes.
|Key Name||Display Name||Type||Format / Value|
|stoppedProcesses||Stopped Processes|<String>
|
|
|totalProcesses||Total Processes|<String>
|
|
Notes:
This map contains the number of processes actually stopped
and the total number of processes. These two numbers will be
different if some of the processes have already been stopped or
have already completed execution on their own.
**Syntax:** `STOP HANDLE 42`
**Syntax:** `STOP HANDLE 113 USING SIGTERM`
**Syntax:** `STOP HANDLE 17 USING SIGKILL`
**Syntax:** `STOP WORKLOAD "Web Tests"`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Stopped Processes: 5 Total Processes: 18
**Syntax:** `STOP ALL CONFIRM`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Stopped Processes: 16 Total Processes: 16
KILL allows you to kill any process (even a process not started by STAF), except for the STAFProc process. Instead, use the SHUTDOWN service to shut down the STAFProc process.
**Note:** If you want to kill a process that you started via STAF,
in most cases, you probably want to use the STOP request to kill the process
rather than using the KILL request.
**Warning:** Be very careful when using this command to specify
the correct pid for the process you want to kill so that you don't accidently
kill a process that you didn't intend to kill.
KILL PID <Pid> CONFIRM [USING <Method>]
`PID` specifies the process id (e.g. pid) of the process that
should be killed. This option will resolve variables.
`CONFIRM` confirms that you really want to kill this process.
`USING` specifies the method used to kill the process. This option will resolve variables.
The following methods are supported:
If the
`USING` option is not specified, it will use the default
stop method for the PROCESS service. You can list the settings
for the PROCESS service, including the default stop method by submitting
a `LIST SETTINGS` request to the PROCESS service.
This command requires trust level 5.
All return codes from KILL are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will be empty.
**Syntax:** `KILL PID 1884 CONFIRM`
**Syntax:** `KILL PID 1231 CONFIRM USING SIGKILL`
**Syntax:** `KILL PID 3340 CONFIRM USING WM_CLOSE`
LIST allows you to obtain information about all of the processes started
via STAF, or only those processes started via STAF that are currently
running, or only those processes started via STAF that have completed.
You may get information about any process started in
`WAIT` mode
that is still running and/or about any process started in `ASYNC`
mode that has not yet been freed.
You can also list the operational settings for the Process service.
LIST [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG]or
LIST SETTINGS
`HANDLES` specifies that you want information for process handles.
`RUNNING` specifies that you only want information for processes
that are currently running.
`COMPLETED` specifies that you only want information for processes
started in `ASYNC` mode that have completed, but have not yet been
freed.
`WORKLOAD` specifies that you want information for processes
that are part of a given workload. This option will resolve variables.
`LONG` specifies that you want to list more detailed information
for the processes.
`SETTINGS` specifies that you want to list the current
operational settings for the Process service.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return:
[Table 64. Definition of map class STAF/Service/Process/ProcessListInfo]
Description: This map class represents a process.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle
|
(H#)
<String>
|
|
|command||Command|<String>
|Private data will be masked.|
|startTimestamp||Start Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|endTimestamp||End Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|rc||Return Code
|
(RC)
<String> | <None>
|
|
Notes:
The value for "End Date-Time" and "Return Code" will be <None> if
the process is still running.
[Table 65. Definition of map class STAF/Service/Process/ProcessListLong]
Description: This map class represents detailed information for a process.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle
|
(H#)
<String>
|
|
|workload||Workload|<String> | <None>
|
|
|command||Command|<String>
|Private data will be masked.|
|pid||PID|<String>
|
|
|startTimestamp||Start Date-Time
|
(Start D-T)
<String>
<YYYYMMDD-HH:MM:SS>
|endTimestamp||End Date-Time
|
(End D-T)
<String> | <None>
<YYYYMMDD-HH:MM:SS>
|rc||Return Code
|
(RC)
<String> | <None>
|
|
Notes:
[Table 66. Definition of map class STAF/Service/Process/Settings]
Description: This map class represents the operational
settings for the Process service.
|Key Name||Display Name||Type||Format / Value|
|defaultStopUsing||Default Stop Using Method|<String>
|
|
|defaultConsoleMode||Default Console Mode|<String>
'New' | 'Same'
|defaultFocus||Default Focus|<String>
'Background' | 'Foreground' | 'Minimized'
|processAuthMode||Process Auth Mode|<String>
|
|
|defaultAuthUsername||Default Auth Username|<String> | <None>
|
|
|defaultAuthPassword||Default Auth Password|<String> | <None>
|Private data will be masked.|
|defaultAuthDisabledAction||Default Auth Disabled Action|<String>
'Ignore' | 'Error'
|defaultShell||Default Shell|<String> | <None>
|
|
|defaultNewConsoleShell||Default New Console Shell|<String> | <None>
|
|
|defaultSameConsoleShell||Default Same Console Shell|<String> | <None>
|
|
Notes:
**Syntax:** `LIST` (or `LIST HANDLES`)
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- ------ 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None> 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
**Syntax:** `LIST COMPLETED HANDLES`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ---------------------- ----------------- ----------------- -- 17 notepad.exe 20051205-11:33:14 20040912-11:37:55 0 25 java TestProcess 5 5 0 20051205-11:53:18 20040912-11:53:18 1 29 java TestA 20051205-12:01:05 20040912-12:05:23 0 56 C:/tests/tc1.exe 20051205-12:33:24 20040912-12:35:32 3
**Syntax:** `LIST RUNNING HANDLES`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
**Syntax:** `LIST LONG`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
H# Workload Command PID Start Date-Time End Date-Time RC -- -------- ---------------- ---- ----------------- ----------------- --------- 17 <None> notepad.exe 1444 20051205-11:33:14 20040912-11:37:55 0 25 <None> java TestProcess 2836 20051205-11:53:18 20040912-11:53:18 1 5 5 0 29 My Test java TestA 3376 20051205-12:01:05 20040912-12:05:23 0 43 My Test java TestB 2776 20051205-12:32:38 <None> <None> 47 My Test C:/tests/MyTest. 2448 20051205-12:32:56 <None> <None> exe 56 TC1 C:/tests/tc1.exe 2840 20040912-12:33:24 20040912-12:35:32 3
**Syntax:** `LIST WORKLOAD "My Test"`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Handle Command Start Date-Time End Date-Time RC ------ ------------------- ----------------- ------------- ------ 43 java TestB 20051205-12:32:38 <None> <None> 47 C:/tests/MyTest.exe 20051205-12:32:56 <None> <None>
**Syntax:** `LIST SETTINGS`
**Results:** If the request is submitted from the
command line, the result, in default format, could look like:
Default Stop Using Method : SigKillAll Default Console Mode : New Default Focus : Background Process Auth Mode : Disabled Default Auth Username : <None> Default Auth Password : <None> Default Auth Disabled Action: Ignore Default Shell : <None> Default New Console Shell : <None> Default Same Console Shell : <None>
QUERY allows you to obtain detailed information about a process with a specified handle that was started via STAF.
QUERY HANDLE <Handle>
`HANDLE` specifies the handle number of the process
you want information on. This option will resolve variables.
This command requires trust level 2.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain a marshalled
`Map:STAF/Service/Process/ProcessInfo>`, representing
information about the process specified to be queried.
The map is defined as follows:
[Table 67. Definition of map class STAF/Service/Process/ProcessInfo]
Description: This map class represents a process.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle|<String>
|
|
|handleName||Handle Name|<String> | <None>
|
|
|title||Title|<String> | <None>
|
|
|workload||Workload|<String> | <None>
|
|
|shell||Shell|<String> | <None>
<Default Shell> if no value is specified
|command||Command|<String>
|Private data will be masked.|
|parms||Parms|<String> | <None>
|Private data will be masked.|
|workdir||Workdir|<String> | <None>
|
|
|focus||Focus|<String>
'Background' | 'Foreground' | 'Minimized'
|userName||User Name|<String> | <None>
|
|
|key||Key|<String> | <None>
|
|
|pid||PID|<String>
|
|
|startMode||Start Mode|<String>
'Async' | 'Wait'
|startTimestamp||Start Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|endTimestamp||End Date-Time|<String> | <None>
<YYYYMMDD-HH:MM:SS>
|rc||Return Code|<String> | <None>
|
|
Notes:
**Syntax:** `QUERY HANDLE 17`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Handle : 17 Handle Name : <None> Title : Notepad Workload : MyWorkload Shell : <None> Command : notepad.exe Parms : <None> Workdir : <None> Focus : Background User Name : <None> Key : <None> PID : 3280 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : <None> Return Code : <None>
**Syntax:** `QUERY HANDLE 42`
**Results:** If the request was issued from the
command line, the result in default format, could look like:
Handle : 42 Handle Name : Web Tests Title : TestA Workload : <None> Shell : <None> Command : D:/Tests/TestA.exe Parms : <None> Workdir : D:/Tests Focus : Background User Name : <None> Key : <None> PID : 3285 Start Mode : Async Start Date-Time: 20051205-11:33:14 End Date-Time : 20051205-11:37:55 Return Code : 0
When processes are STARTed asynchronously, the termination timestamp and return code are stored by STAF for later retrieval. In order to free these values, you use the PROCESS FREE command. You may only free information for processes that are already stopped. You may free the termination information for a single process, all the stopped processes of a given workload, or all stopped processes that have been started by STAF.
FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>>
`ALL` specifies that you want to free the termination information
for all stopped processes.
`WORKLOAD` specifies that you want to free the termination
information for all processes that are part of a given workload. This option will resolve variables.
`HANDLE` specifies that only the termination information for the
specified handle should be freed. This option will resolve variables.
This command requires trust level 4.
All return codes from FREE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
[Table 68. Definition of map class STAF/Service/Process/FreeInfo]
Description: This map class represents statistics for
freed processes.
|Key Name||Display Name||Type||Format / Value|
|freedProcesses||Freed Processes|<String>
|
|
|totalProcesses||Total Processes|<String>
|
|
Notes:
This map contains the number of processes for which termination
information was actually freed and the total number of processes.
These two numbers will be different if some of the processes have
not yet been stopped or have not completed execution.
**Syntax:** `FREE HANDLE 42`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Freed Processes: 1 Total Processes: 10
**Syntax:** `FREE WORKLOAD "Web Tests"`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Freed Processes: 2 Total Processes: 17
**Syntax:** `FREE ALL`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Freed Processes: 15 Total Processes: 16
NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when a given process ends.
NOTIFY <REGISTER | UNREGISTER> ONENDOFHANDLE <Handle> [MACHINE <Machine>] [PRIORITY <Priority>] [HANDLE <Handle> | NAME <Name>]
`REGISTER` indicates you want to register for a notification
when a process ends. The queued message will have type "STAF/Process/End" and
its message will contain a marshalled `<Map>` which represents the
completion information for the process. See tables [Table 69](#TBLSTAFPROCESSENDTABLE)
and [Table 70](#TBLPROCESSRETURNEDFILETABLE) for the map definitions of a
process completion message.
`UNREGISTER` indicates you want to unregister a process end
notification.
`ONENDOFHANDLE` indicates the handle of the process for which you
wish to receive the notification. This option will resolve variables.
`MACHINE` specifies the machine to which the notification should
be sent. The default is the machine submitting the request. This option will resolve variables.
`PRIORITY` specifies the priority of the notification message.
The default is 5. This option will resolve variables.
`HANDLE` specifies the handle to which the notification should be
sent. The default is the handle of the process submitting the request.
This option will resolve variables.
`NAME` specifies the registered name of the process(es) to which
the notification should be sent. This option will resolve variables.
[Table 69. Definition of map for "STAF/Process/End" type message]
Description: This map represents process completion information.
|Key Name||Type||Format / Value|
|handle|<String>
|
|
|endTimestamp|<String>
<YYYYMMDD-HH:MM:SS>
|rc|<String>
|
|
|key|<String>
|
|
|fileList|<List> of <Map>. See |
|
Notes:
The value for "fileList" will contain a list of information about the files
requested to be returned. Files will be returned in the order of standard output,
then standard error, then any files specified with the RETURNFILE
option. The value for "fileList" will be empty if none of the options
RETURNSTDOUT, RETURNSTDERR, or RETURNFILE were
specified when the process was started.
[Table 70. Definition of map for returned files for a process]
Description: This map class represents a file returned by the process.
|Key Name||Type||Format / Value|
|rc|<String>
|
|
|data|<String>
|
|
Notes:
For each file, a standard STAF return code indicating the success or failure
of retrieving the file's contents is provided. If the file's return code
is 0, then the data contained in the file is also provided.
If the file's return code is 58 (Maximum Size Exceeded), that indicates
that the file size exceeded the maximum return file size.
For example, suppose a PROCESS START COMMAND "java TestA" request was submitted by handle 43, and assume that the process completed successfully at 20041019-17:03:48 and returned a process return code of 0. The queued STAF/PROCESS/END message will be a map that could look like the following:
{ handle : 43 endTimestamp: 20041019-17:03:48 rc : 0 key : <None> fileList : [] }
For example, suppose a
`PROCESS START COMMAND "java TestA" KEY 10 RETURNSTDOUT
RETURNSTDERR` request is submitted by handle 26 with key 10, and assume that
the process completed successfully at 20041029-09:30:16 and returned a process
return code of 3 and that the standard output of the process was simply
"Success !!!", and that the standard error of the process was blank.
The queued STAF/PROCESS/END message will be a map that could look like
the following:
{ handle : 26 endTimestamp: 20041029-09:30:16 rc : 3 key : 10 fileList : [ { rc : 0 data: Success !!! } { rc : 0 data: } ] }
These commands require trust level 3.
All return codes from NOTIFY REGISTER/UNREGISTER are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
The result buffer will contain a marshalled
` <List> of <Map:STAF/Service/Process/Notifiee>`,
representing the registered notifiees.
The map is defined as follows:
[Table 71. Definition of map class STAF/Service/Process/Notifiee]
Description: This map class represents a registered notifiee.
|Key Name||Display Name||Type||Format / Value|
|priority||Priority
|
(P)
<String>
|
|
|machine||Machine|<String>
|
|
|notifyBy||Notify By|<String>
'Name' | 'Handle'
|notifiee||Notifiee|<String>
|
|
Notes:
If the "Notify By" value is 'Name', the "Notifiee" value will be
the handle name. Otherwise, if the "Notify By" value is 'Handle', the
"Notifiee" value will be the handle number.
**Syntax:** `NOTIFY LIST ONENDOFHANDLE 57`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- -------------------- --------- --------- 5 automate.austin.ibm.com Handle 48 1 dyno.austin.ibm.com Handle 51 3 automate.austin.ibm.com Name Web Tests
Note that to make these settings permanent (e.g. if you want these changes to apply once STAF is stopped and restarted), you'll need to update the STAF configuration file with these new settings.
SET [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>] [DEFAULTFOCUS <Background | Foreground | Minimized>] [PROCESSAUTHMODE <Auth Mode>] [DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>] [DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>] [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
See section
[4.7, "Operational parameters"](#HDROPPARMS) 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"](#HDRRETCODE).
The result buffer will contain no data on return from a successful SET command.
**Syntax:** `SET DEFAULTSTOPUSING WM_Close`
**Syntax:** `SET PROCESSAUTHMODE Windows
DEFAULTAUTHUSERNAME user1 DEFAULTAUTHPASSWORD !!@secret@!!`
The QUEUE service is one of the internal STAF services. It provides the following commands to manipulate the contents of a handle's queue:
QUEUE allows you to queue a message to a given process handle or to any process registered with a given name.
QUEUE MESSAGE <Message> [HANDLE <Handle> | NAME <Name>] [PRIORITY <Priority>] [TYPE <Type>]
`MESSAGE` specifies the message to be queued.
This option will not resolve variables.
`HANDLE` specifies the process handle to which the message should
be queued. If the request is made locally, the default is the handle which
originated the request. This option will resolve variables.
`NAME` specifies the registered name of the process(es) to which
the message should be queued. This option will resolve variables.
**Note: **If the request is made to a remote machine then you must specify either
`HANDLE` or `NAME`.
`PRIORITY` specifies the priority of the message to be queued. The
default is 5. This option will resolve variables.
`TYPE` specifies the type for the message to be queued. The
default is no type. This option will resolve variables.
This command requires trust level 3.
All return codes from QUEUE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If a message is attempted to be queued to a handle whose queue already contains the maximum number of messages allowed, the message will not be queued to that handle and return code 28 (Queue Full) will be returned.
On successful return:
If unsuccessful due to attempting to queue a message to a handle whose queue already contains the maximum number of messages allowed, the message will not be sent to that handle's queue and return code 28 (Queue full) will be returned and the result buffer will be set as follows:
[Table 72. Definition of map class STAF/Service/Queue/Error]
Description: This map class represents error information when a
message is attempted to be sent to all handles with a specified name and at
least one handle's queue is full.
|Key Name||Display Name||Type||Format / Value|
|numberQueued||Number Queued|<String>
|
|
|fullQueueList||Handles with Full Queues||<List> of <Map:STAF/Service/Queue/FullInfo>||
|
Notes:
The "Handles with Full Queues" value will contain a list of information
about the handles whose queues are full.
[Table 73. Definition of map class STAF/Service/Queue/FullInfo]
Description: This map class represents error information
for a handle whose queue is full.
|Key Name||Display Name||Type||Format / Value|
|handle||Handle|<String>
|
|
|queueSize||Queue Size|<String>
|
|
Notes:
The "Handle" value will contain the handle number of a handle whose
queue is full and the "Queue Size" value will contain the number of messages
that the handle's queue contains.
**Syntax:** `QUEUE MESSAGE "Hello World"`
**Syntax:** `QUEUE HANDLE 50 PRIORITY 1 MESSAGE "CONTROL/STAGE2"`
**Syntax:** `QUEUE HANDLE 17 TYPE "Build/Complete" MESSAGE "Success"`
**Syntax:**
`STAF test1.company.com QUEUE QUEUE NAME "MyProduct/Test" MESSAGE "Success"`
**Results**
{ Number Queued : 0 Handles with Full Queues: [ { Handle : 37 Queue Size: 100 } ] }
{ Number Queued : 1 Handles with Full Queues: [ { Handle : 37 Queue Size: 100 } { Handle : 41 Queue Size: 100 } ] }
GET allows you to retrieve and remove one or more elements from the queue of the handle submitting the GET request to the QUEUE service.
PEEK allows you to retrieve one or more elements from the queue of the handle submitting the PEEK request without removing the element(s) from the queue.
By default, only one element will be retrieved/removed from the queue if you don't
specify the
`ALL` or `FIRST` option.
For security reasons, you are only allowed to retrieve messages from your own handle's queue, not from any other handle's queue. So, a GET/PEEK request only retrieves messages from the queue of the handle that submitted the GET/PEEK request to the QUEUE service. Note that you can use the LIST request to list messages that are in another handle's queue.
GET [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]... [FIRST <Number> | ALL] [WAIT [<Number>[s|m|h|d|w]] ] PEEK [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]... [FIRST <Number> | ALL] [WAIT [<Number>[s|m|h|d|w]] ]
`PRIORITY` specifies that you want to retrieve/remove message(s)
with the given priority. The default is the highest priority message (i.e.,
the one with the lowest priority number). You may specify this option multiple
times. This option will resolve variables.
`MACHINE` specifies that you want to retrieve/remove message(s)
originating from the given machine's endpoint. The default is any machine. You may
specify this option multiple times. This option will resolve variables.
The format for a machine's endpoint is:
<Interface>://<System Identifier>[@<Port>]where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".
`NAME` specifies that you want to retrieve/remove message(s)
originating from a process with the given registered name. The default is any
name. You may specify this option multiple times. This option will resolve variables.
Note that this option does not specify the handle name for the handle whose
queue you want to retrieve messages from as you can only retrieve messages
from the queue of the handle that submitted the GET/PEEK request to the
QUEUE service.
`HANDLE` specifies that you want to retrieve/remove message(s)
originating from a process with the given handle number. The default is any handle.
You may specify this option multiple times. This option will resolve variables.
Note that this option does not specify the handle number for the handle whose
queue you want to retrieve messages from as you can only retrieve messages
from the queue of the handle that submitted the GET/PEEK request to the
QUEUE service.
`USER` specifies that you want to retrieve/remove a message
originating from a process with a handle that has been authenticated
with the specified user. The format for <User> is:
<Authenticator>://<User Identifier>where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the User Identifier. The default is any user. You may specify this option multiple times. This option will resolve variables.
`TYPE` specifies that you want to retrieve/remove message(s)
with the given type. The match is case insensitive.
You may specify this option multiple times. This option will resolve variables.
`CONTAINS` specifies that you want to retrieve/remove message(s)
containing the given string. The search is case sensitive. The default is any
message. You may specify this option multiple times. This option will resolve variables.
`ICONTAINS` specifies that you want to retrieve/remove message(s)
containing the given string. The search is case insensitive. The default is any
message. You may specify this option multiple times. This option will resolve variables.
`ALL` specifies that you want to retrieve/remove all appropriate
messages that meet the specified criteria.
If you don't specify the `ALL` or `FIRST` option,
the default is to retrieve/remove one appropriate message.
`FIRST` specifies that you want to retrieve/remove the first <Number>
of appropriate messages that meet the specified criteria, where <Number>
must be an integer greater than 0.
If there are fewer appropriate messages on the queue that meet the
specified criteria than the number you specified for the `FIRST` option,
then fewer messages will be returned than the number you specified.
If you don't specify the `ALL` or `FIRST` option,
the default is to retrieve/remove one appropriate message. This option will resolve variables.
`WAIT` specifies that the request should not return until an
appropriate message is available. You may specify an optional time duration
after which the request should return. If no time duration is specified,
the request will wait indefinitely until an appropriate message is available.
This option will resolve variables.
The time duration may be expressed in milliseconds, seconds, minutes,
hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w],
where <Number> is an integer >= 0 and indicates milliseconds unless one
of the following case-insensitive suffixes is specified:
These commands are only valid with respect to the submitting process' queue and if submitted to the local machine.
All return codes from GET/PEEK are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
For example:
[Table 74. Definition of map class STAF/Service/Queue/Entry]
Description: This map class represents an entry from the queue.
|Key Name||Display Name||Type||Format / Value|
|priority||Priority
|
(P)
<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|machine||Machine|<String>
|
|
|handleName||Handle Name
|
(Name)
<String> | <None>
|
|
|handle||Handle
|
(H#)
<String>
|
|
|type||Type|<String> | <None>
|
|
|message||Message||<Any>||
|
For example, if a
`GET` or `PEEK` request
is submitted from the command line (without the `ALL` or
`FIRST` option), the result, in default format,
could look like the following:
Priority : 3 Date-Time : 20040912-16:49:11 Machine : tcp://client2.austin.ibm.com@6500 Handle Name: STAF_Process Handle : 17 User : none://anonymous Type : STAF/Start Message :
For example, if a
`GET ALL` or `PEEK ALL` request
is submitted from the comand line using a static handle and that
handle's queue contains 5 elements, the result would contain a list of
all 5 elements, and, in default format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous A This is message #1 15:48:55 5 20090324- local://local MyHandle 150 none://anonymous A This is message #2 15:48:56 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59 5 20090324- local://local MyHandle 150 none://anonymous A This is message #4 15:49:05 5 20090324- local://local MyHandle 150 none://anonymous B This is message #5 15:49:11
For example, if a
`GET FIRST 3` or `PEEK FIRST 3` request
is submitted from the comand line using a static handle and that
handle's queue contains 5 elements, the result would contain a list of the
first 3 elements, and, in default format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous A This is message #1 15:48:55 5 20090324- local://local MyHandle 150 none://anonymous A This is message #2 15:48:56 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59
For example, if a
`GET TYPE B FIRST 2` or `PEEK TYPE B FIRST 2`
request is submitted from the comand line using a static handle and that
handle's queue contains the 5 elements from the first example, the result would
contain a list of the first 2 elements with type B, and, in default format,
could look like the following:
P Date-Time Machine Name H# User Type Message - --------- ------------- -------- --- ---------------- ---- ------------------ 5 20090324- local://local MyHandle 150 none://anonymous B This is message #3 15:48:59 5 20090324- local://local MyHandle 150 none://anonymous B This is message #5 15:49:11
**Syntax:** `GET WAIT`
**Syntax:** `PEEK WAIT MACHINE "tcp://server1.company.com@6500"`
**Syntax:** `GET WAIT 30s TYPE STAF/Start`
**Syntax:** `PEEK PRIORITY 3 MACHINE "*://client3.company.com*" NAME JavaTest1 CONTAINS {TestString}`
**Syntax:** `GET WAIT TYPE STAF/Start TYPE STAF/Shutdown MACHINE tcp://client1.company.com@6500 MACHINE tcp://client2.company.com@6500`
**Syntax:** `GET WAIT CONTAINS CONTROL CONTAINS "Hi there"`
**Syntax:** `GET WAIT 1m TYPE "MyProduct/Build/Complete" CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"`
**Syntax:** `PEEK ALL`
**Syntax:** `GET ALL`
**Syntax:** `GET FIRST 5 WAIT`
**Syntax:** `GET ALL WAIT`
**Syntax:** `GET ALL TYPE "STAF/Process/Complete" WAIT`
DELETE allows you to delete a set of messages from a queue.
DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]...
`PRIORITY` specifies that you want to delete messages with the
given priority. The default is any priority. You may specify this option
multiple times. This option will resolve variables.
`MACHINE` specifies that you want to delete messages originating
from the given machine's endpoint. The default is any machine. You may
specify this option multiple times. This option will resolve variables.
The format for a machine's endpoint is:
<Interface>://<System Identifier>[@<Port>]where a case-insensitive match is performed. You can specify match patterns (e.g. wild cards) for a machine's endpoint. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match). For example, if you want to match on messages from a machine with system identifier client1.mycompany.com, no matter what interface or port is in the machine's endpoint, you could specify "*://client1.mycompany.com*" which would match machines such as "tcp://client1.mycompany.com@6500" and "tcp2://client1.mycompany.com".
`NAME` specifies that you want to delete messages originating from
a process with the given registered name. The default is any name. You may
specify this option multiple times. This option will resolve variables.
`HANDLE` specifies that you want to delete messages originating
from a process with the given handle. The default is any handle. You may
specify this option multiple times. This option will resolve variables.
`USER` specifies that you want to delete messages originating
from a process with a handle that has been authenticated
with the specified user. The format for <User> is:
<Authenticator>://<User Identifier>where a case-insensitive match is performed on the <Authenticator> value and a case-sensitive match is performed on the <User Identifier> value. The default is any user. You may specify this option multiple times. This option will resolve variables.
`TYPE` specifies that you want to delete messages
with the given type. The match is case insensitive.
You may specify this option multiple times. This option will resolve variables.
`CONTAINS` specifies that you want to delete messages containing
the given string. The search is case sensitive. The default is any
message. You may specify this option multiple times. This option will resolve variables.
`ICONTAINS` specifies that you want to delete messages containing
the given string. The search is case insensitive. The default is any
message. You may specify this option multiple times. This option will resolve variables.
This command is only valid with respect to the submitting process' queue and if submitted to the local machine.
All return codes from DELETE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain the number of messages deleted.
**Syntax:** `DELETE MACHINE "local://local"`
**Syntax:** `DELETE PRIORITY 3 NAME JavaTest1`
**Syntax:** `DELETE PRIORITY 3 PRIORITY 4 MACHINE {Mach1} MACHINE {Mach2} CONTAINS Stage2 CONTAINS {StringTest1}`
**Syntax:** `DELETE TYPE "MyProduct/Build/Complete"
CONTAINS "Version=1.2.0" MACHINE "*://buildserver.company.com*"`
**Syntax:** `DELETE`
LIST allows you to retrieve the contents of the queue of a given handle.
LIST [HANDLE <Handle>]
`HANDLE` specifies the handle of the process for which you want
the queue contents. The default is the handle of the submitting process. This
option will only default if the request was submitted locally. This option will resolve variables.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a marshalled
`<List> of <Map:STAF/Service/Queue/Entry>`, representing
the queued messages, sorted in ascending order by priority.
The map is defined as follows:
[Table 75. Definition of map class STAF/Service/Queue/Entry]
Description: This map class represents a queued message.
|Key Name||Display Name||Type||Format / Value|
|priority||Priority|<String>
|
|
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|machine||Machine|<String>
|
|
|handleName||Handle Name|<String> | <None>
|
|
|handle||Handle|<String>
|
|
|type||Type|<String> | <None>
|
|
|message||Message||<Any>||Private data will be masked.|
**Syntax:** `LIST`
**Result:** If the request is submitted from the
command line, the result, in table format, could look like the following:
P Date-Time Machine Name H# User Type Message - --------- -------------- ------ -- -------- ---------- ------------------------ 1 20040912- tcp://client1. STAF_P 1 none://a STAF/Start 13:56:10 austin.ibm.com rocess nonymous @6500 3 20040912- tcp://client3. JavaTe 36 none://a FVTTest CONTROL/STAGE2 14:01:52 austin.ibm.com st1 nonymous 3 20040912- tcp://client2. STAF_P 1 none://a STAF/Start 14:02:17 austin.ibm.com rocess nonymous @6500 5 20040912- tcp://client3. JavaTe 36 none://a <None> This is a test message f 13:57:36 austin.ibm.com st1 nonymous rom Test1. Phase 2 has @6500 completed.
**Syntax:** `LIST HANDLE 37`
**Result:** If the request is issued from the command line, the result,
in verbose format, could look like:
[ { Priority : 5 Date-Time : 20050222-16:50:12 Machine : tcp://client1.austin.ibm.com@6500 Handle Name: STAF_Process Handle : 1 User : none://anonymous Type : STAF/Process/End Message : { endTimestamp: 20050222-16:50:12 fileList : [] handle : 30 key : rc : 0 } } ]
SERVICE <Name> LIBRARY STAFPool [PARMS <Parameters>]
`<Name>` is the name by which the Resource Pool service will be
known on this machine.
`<Parameters>` are valid Resource Pool parameters
described below.
service respool library STAFPool service respool library STAFPool parms "Directory {STAF/Config/BootDrive}/STAF/ResPool"
The Resource Pool service accepts a parameter string in the following format:
[DIRECTORY <Resource Pool Directory Root>]
`DIRECTORY` specifies the root directory under which resource pool
files are stored. The default is `{STAF/DataDir}/service/<Service Name (lower-case)>`.
**Note: **Previously, in STAF 2.x, the default root directory was
`{STAF/Config/STAFRoot}/data/<Service Name (lower-case)>`.
So, if you want to continue to use the STAF 2.x resource pools with the
current version of STAF, move the resource pool files to the new default root
directory or specify the old root directory for the `DIRECTORY` parameter.
LIST displays a list of resource pools and their descriptions.
LIST [POOLS | SETTINGS]
`POOLS` indicates to list the resource pools.
This is the default.
`SETTINGS` indicates to list the operational settings for
the Resource Pool service.
This command requires trust level 2.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
LIST also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
[Table 76. Definition of map class STAF/Service/ResPool/Pool]
Description: This map class represents a resource pool.
|Key Name||Display Name||Type||Format / Value|
|poolName||Pool Name|<String>
|
|
|description||Description|<String>
|
|
[Table 77. Definition of map class STAF/Service/ResPool/Service]
Description: This map class represents the settings for the service.
|Key Name||Display Name||Type||Format / Value|
|directory||Directory|<String>
|
|
**Syntax:** `LIST` or `LIST POOLS`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Pool Name Description ------------------- ------------------------------------------ AUSVMR UserIDs and Passwords for VM System AUSVMR AutoTester_Licenses License numbers for AutoTester
**Syntax:** `LIST SETTINGS`
**Results:** If the request is submitted from the
command line, the result could look like:
Directory: C:\STAF\data\STAF\service\respool
Creates a resource pool.
CREATE POOL <PoolName> DESCRIPTION <Description>
`POOL` specifies the name of the resource pool you want to create. This option will resolve variables.
Note that the pool name will be used in the name of a file that will be
created in the resource pool directory root, (e.g.
`<ResourcePoolDirectoryRoot>/<PoolName>.rpl`).
So, avoid specifying a character that the file system doesn't allow in a file
name such as the following characters: `< > : " / \ | ? *`
`DESCRIPTION` specifies the description of the resource pool. This option will resolve variables.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
CREATE also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer will contain no data upon return from a CREATE command.
**Syntax:** `CREATE POOL AUSVMR DESCRIPTION "UserIDs and Passwords for VM System AUSVMR"`
Deletes a resource pool and all its entries.
DELETE POOL <PoolName> CONFIRM [FORCE]
`POOL` specifies the name of the resource pool you want to delete. This option will resolve variables.
`CONFIRM` confirms you really want to delete the resource pool.
`FORCE` allows you to force the deletion of the resource pool, even
if there are pending requests. If this option is not specified, you will
receive an error if you try to delete a resource pool which has pending
requests.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
DELETE also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer will contain no data upon return from a DELETE command.
**Syntax:** `DELETE POOL AUSVMR CONFIRM`
**Syntax:** `DELETE POOL AUSVM1 CONFIRM FORCE`
ADD allows you to add a resource entry to an existing resource pool. You may add multiple entries to a resource pool with a single request. Note, a resource pool may not contain duplicate entries. If one or more duplicate entries are specified with a single request, none of the entries specified are added.
ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
`POOL` specifies the name of the resource pool to which you
want to add a resource entry. This option will resolve variables.
`ENTRY` specifies the actual entry to be added to the resource
pool.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
ADD also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer will contain no data upon return from the ADD command.
**Syntax:** `ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2"`
**Syntax:** `ADD POOL AutoTester_Licenses ENTRY 1047923`
REMOVE removes a resource entry from an existing resource pool. The resource entry may only be removed if the resource is not in use or if the FORCE option is specified. Note, you may remove multiple entries from a resource pool with a single request. If one or more invalid entries are specified with a single request, none of the entries specified are removed.
REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
`POOL` specifies the name of the resource pool from which you
want to remove an entry. This option will resolve variables.
`ENTRY` specifies the actual entry to be removed.
`CONFIRM` confirms you really want to remove the resource entry.
`FORCE` allows you to force the removal of a resource entry which
is currently owned. By default, you may only remove a resource entry if it is
not currently owned.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
REMOVE also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer will contain no data upon return from the REMOVE command.
**Syntax:**
`REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM`
**Syntax:**
`REMOVE POOL AutoTester_Licenses ENTRY 1137849 ENTRY 107523 CONFIRM FORCE`
Allows you to get information on a resource pool, including a list of entries in the pool and the status of each entry, as well as a list of the pending requests for entries in the resource pool. The pending requests will shown in ascending order by priority, and within the same priority by the request timestamp.
QUERY POOL <PoolName>
`POOL` specifies the name of the resource pool you want to query. This option will resolve variables.
This command requires trust level 2.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
QUERY also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer for a
`QUERY` request will contain a marshalled
`<Map:STAF/Service/ResPool/PoolInfo>`, representing
information about the specified resource pool.
The maps used in representing a resource pool are defined as follows:
[Table 78. Definition of map class STAF/Service/ResPool/PoolInfo]
Description: This map class represents a resource pool.
|Key Name||Display Name||Type||Format / Value|
|description||Description|<String>
|
|
|requestList||Pending Requests|<List> of <Map:STAF/Service/ResPool/Request>
|
|
|resourceList||Resources|<List> of <Map:STAF/Service/ResPool/Resource>
|
|
Notes:
For each pending request in the request list for the pool, information
about the priority, the requested timestamp, the requested entry
(if any), and the originator of the pending request is provided.
For each entry in the resource list for the pool, the resource entry
and owner information is provided.
[Table 79. Definition of map class STAF/Service/ResPool/Request]
Description: This map class represents a pending request for a resource in a resource pool
|Key Name||Display Name||Type||Format / Value|
|priority||Priority|<String> | <None>
'1' - '99'
|requestedTimestamp||Date-Time Requested|<String>
<YYYYMMDD-HH:MM:SS>
|requestedEntry||Requested Entry|<String> | <None>
|
|
|machine||Machine|<String>
|
|
|handleName||Handle Name|<String>
|
|
|handle||Handle|<String>
|
|
|user||User|<String>
<Authenticator>://<User ID>
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|gc||Perform Garbage Collection|<String>
'Yes' | 'No'
Notes:
[Table 80. Definition of map class STAF/Service/ResPool/Resource]
Description: This map class represents a resource in the pool
|Key Name||Display Name||Type||Format / Value|
|entry||Entry|<String>
|
|
|owner||Owner|<None> |
<Map:STAF/Service/ResPool/ResourceOwner>
|
|
Notes:
If the resource entry is not owned, the owner will be <None>.
[Table 81. Definition of map class STAF/Service/ResPool/ResourceOwner]
Description: This map class represents a owner of a resource
|Key Name||Display Name||Type||Format / Value|
|machine||Machine|<String>
|
|
|handleName||Handle Name|<String>
|
|
|handle||Handle|<String>
|
|
|user||User|<String>
<Authenticator>://<User ID>
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|requestedTimestamp||Date-Time Requested|<String>
<YYYYMMDD-HH:MM:SS>
|acquiredTimestamp||Date-Time Acquired|<String>
<YYYYMMDD-HH:MM:SS>
|gc||Perform Garbage Collection|<String>
'Yes' | 'No'
**Syntax:** `QUERY POOL AUSVMR`
**Results:** If the request is submitted from the
command line, the result, in verbose format, could look like
the following if the resource pool contained three
entries (where each entry consisted of a user id and a password)
and two of the entries were currently owned.
{ Description : UserIDs and Passwords for VM System AUSVMR Pending Requests: [] Resources : [ { Entry: USER1 PASSWORD1 Owner: { Machine : client3.austin.ibm.com Handle Name : CM2_Test Handle : 19 User : none://anonymous Endpoint : tcp://client3.austin.ibm.com@6500 Date-Time Requested : 20070430-15:58:30 Date-Time Acquired : 20070430-15:58:30 Perform Garbage Collection: Yes } } { Entry: USER2 PASSWORD2 Owner: { Machine : client1.austin.ibm.com Handle Name : My Test Handle : 23 User : none://anonymous Endpoint : tcp://client1.austin.ibm.com@6500 Date-Time Requested : 20070430-15:58:19 Date-Time Acquired : 20070430-15:58:19 Perform Garbage Collection: No } } { Entry: USER3 PASSWORD3 Owner: <None> } ] }
**Syntax:** `QUERY POOL AUSVMR`
**Results:** If the request is submitted from the
command line, the result, in verbose format, could look like
the following if the resource pool contained two
entries (where each entry consisted of a user id and a password) and
all of the entries were currently owned, with three pending requests.
{ Description : UserIDs and Passwords for VM System AUSVMR Pending Requests: [ { Priority : 1 Date-Time Requested : 20100230-16:56:55 Requested Entry : USER1 PASSWORD1 Machine : client1.austin.ibm.com Handle Name : My Test Handle : 23 User : none://anonymous Endpoint : tcp://client1.austin.ibm.com@6500 Perform Garbage Collection: No } { Priority : 50 Date-Time Requested : 20100230-16:54:58 Requested Entry : <None> Machine : client2.austin.ibm.com Handle Name : User Access Test Handle : 28 User : none://anonymous Endpoint : tcp://client2.austin.ibm.com@6500 Perform Garbage Collection: Yes } { Priority : 50 Date-Time Requested : 20100230-16:55:02 Requested Entry : <None> Machine : client3.austin.ibm.com Handle Name : CM3_Test Handle : 21 User : none://anonymous Endpoint : tcp://client3.austin.ibm.com@6500 Perform Garbage Collection: Yes } ] Resources : [ { Entry: USER1 PASSWORD1 Owner: { Machine : client3.austin.ibm.com Handle Name : CM2_Test Handle : 19 User : none://anonymous Endpoint : tcp://client3.austin.ibm.com@6500 Date-Time Requested : 20100230-15:58:30 Date-Time Acquired : 20100230-15:58:30 Perform Garbage Collection: Yes } } { Entry: USER2 PASSWORD2 Owner: { Machine : client1.austin.ibm.com Handle Name : My Test Handle : 23 User : none://anonymous Endpoint : tcp://client1.austin.ibm.com@6500 Date-Time Requested : 20100230-15:58:19 Date-Time Acquired : 20100230-15:58:19 Perform Garbage Collection: No } } ] }
Obtains exclusive access to an entry from the resource pool.
If an entry is available that meets the specified criteria in the request, then the entry will become owned by the STAF handle on the machine that submitted the REQUEST POOL request to the RESPOOL service. If an entry is not currently available that meets the specified criteria in the request, the request will be added to the "Pending Requests" list in ascending order by "priority" and then by the timestamp when the request was submitted.
The STAF handle on the machine that submitted a REQUEST POOL request to the RESPOOL service will be the "owner" of the resource pool entry. Note that when a STAF handle that requested a resource is deleted, STAF performs garbage collection for the handle by default, unless you specified not to perform garbage collection when requesting a resource. Performing garbage collection means when a handle that requested a resource is deleted, the RESPOOL service will be notified, and it will release any resource pool entries that handle owns and will remove any pending requests for resources submitted by that handle.
If you submit a REQUEST POOL request to the RESPOOL service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:
So, when using the STAF command executable to submit a REQUEST POOL
request to the RESPOOL service, in order to retain ownership of the
resource pool entry (due to garbage collection), you either need to
specify not to perform garbage collection or you need to use a static
handle when submitting the request.
See
["Command Line Example"](#HDRRESSRVCMDEX) for examples of how to do this.
REQUEST POOL <PoolName> [FIRST | RANDOM | ENTRY <Value> [RELEASE]] [PRIORITY <Number>] [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
`POOL` specifies the name of the resource pool from which you
are requesting a resource. This option will resolve variables.
`TIMEOUT` specifies a timeout duration indicating the longest
you are willing to wait for a resource to become available.
If this option is not specified, the request will wait indefinitely
until a resource is available. This option will resolve variables.
The time duration may be expressed in milliseconds, seconds, minutes,
hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w],
where <Number> is an integer >= 0 and indicates milliseconds unless one
of the following case-insensitive suffixes is specified:
`FIRST` specifies that the first available entry in the resource
list should be returned.
`RANDOM` specifies that a random available entry should be
returned. This is the default.
`ENTRY` specifies a particular entry in the resource list that
should be returned.
`RELEASE` specifies to release the entry after requesting it
(i.e. performs an atomic release and request). This option can only be
specified when requesting an entry that is already owned by the handle
submitting the request. This can be useful when you want to re-gain
ownership of the entry before any lesser-priority pending requests.
`PRIORITY` specifies the priority of the request. It must be
a number from 1 to 99, where 1 indicates the highest priority. The
default is 50.
If an entry is not currently available that meets the specified
criteria in the request, the request will be added to the "Pending
Requests" list in ascending order by "priority" and then by
the timestamp when the request was submitted.
Pending requests with priority 1 will be satisfied first if
possible, followed by pending requests with priority 2, and so on.
This option will resolve variables.
`GARBAGECOLLECT` specifies whether to perform garbage collection
when the STAF handle that requested a resource is deleted. Valid values are
`Yes` and `No`, not case-sensitive.
The default is `Yes` which means that garbage collection will be
performed for the handle that requested the resource. This option will resolve variables.
For example, if you need a resource to be owned for a long period of time and the STAF handle that you're going to use to submit the request may not exist for that period of time, then you must specify not to perform garbage collection when requesting a resource. This ensures that the resource will not be released until a RELEASE ENTRY request for that resource pool entry is submitted.
This command requires trust level 3.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
REQUEST also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
On successful return, the result buffer will contain the entry given to the process.
**Syntax:** `REQUEST POOL AUSVMR FIRST`
**Syntax:** `REQUEST POOL AutoTester_Licenses TIMEOUT 5m`
**Syntax:** `REQUEST POOL MachinePool GARBAGECOLLECT No`
**Syntax:** `REQUEST POOL MachinePool ENTRY machine1`
**Syntax:** `REQUEST POOL MachinePool ENTRY machine2 TIMEOUT 1h`
**Syntax:** `REQUEST POOL MachinePool PRIORITY 1`
**Syntax:** `REQUEST POOL MachinePool ENTRY machine1 PRIORITY 1`
**Syntax:** `REQUEST POOL MachinePool ENTRY machine1 RELEASE PRIORITY 30`
Say you had a resource pool named MachinePool that contained two entries and you submit a REQUEST POOL request to the RESPOOL service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't specify not to perform garbage collection and if you didn't use a static handle, the resource entry obtained by the REQUEST POOL request would show up as available (Unowned) when submitting a QUERY POOL request to the RESPOOL service because when the STAF command deleted the handle it created to submit the REQUEST POOL request, that triggered garbage collection to be performed.
C:\>STAF local RESPOOL REQUEST POOL MachinePool Response -------- machine1 C:\>STAF local RESPOOL QUERY POOL MachinePool Response -------- { Description : Test Machine Pool Pending Requests: [] Resources : [ { Entry: machine1 Owner: <None> } { Entry: machine2 Owner: <None> } ] }
Instead, you need to specify not to perform garbage collection when submitting the REQUEST POOL request to the RESPOOL service using the STAF command. Here's an example shown using the STAF command from a Windows command prompt:
C:\>STAF local RESPOOL REQUEST POOL MachinePool GARBAGECOLLECT No Response -------- machine1 C:\>STAF local RESPOOL QUERY POOL MachinePool Response -------- { Description : Test Machine Pool Pending Requests: [] Resources : [ { Entry: machine1 Owner: { Machine : client1.company.com Handle Name : STAF/Client Handle : 49 User : none://anonymous Endpoint : local://local Date-Time Requested : 20070430-14:11:18 Date-Time Acquired : 20070430-14:11:18 Perform Garbage Collection: Yes } } { Entry: machine2 Owner: <None> } ] }
Or, you need to first create a static handle and set environment
variable STAF_STATIC_HANDLE to the static handle's number before
submitting a REQUEST POOL request to the RESPOOL service using the
STAF command so that the static handle can retain ownership of the
resource entry until it releases the entry (or until you delete the
static handle). See
["Using the STAF command from shell-scripts"](#HDRSTAFSHS) for more information on
special environment variable STAF_STATIC_HANDLE.
Here's an example shown using the STAF command from a Windows
command prompt:
C:\>STAF local HANDLE CREATE HANDLE NAME ResourcePoolHandle Response -------- 51 C:\>set STAF_STATIC_HANDLE=51 C:\>STAF local RESPOOL REQUEST POOL MachinePool Response -------- machine1 C:\>STAF local RESPOOL QUERY POOL MachinePool Response -------- { Description : Test Machine Pool Pending Requests: [] Resources : [ { Entry: machine1 Owner: { Machine : client1.company.com Handle Name : ResourcePoolHandle Handle : 51 User : none://anonymous Endpoint : local://local Date-Time Requested : 20070430-14:15:18 Date-Time Acquired : 20070430-14:15:18 Perform Garbage Collection: Yes } } { Entry: machine2 Owner: <None> } ] }
RELEASE allows you to release exclusive access of a resource entry in a resource pool.
RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
`POOL` specifies the name of the resource pool to which you are
releasing exclusive access of an entry. This option will resolve variables.
`ENTRY` specifies the actual entry to which you are releasing
exclusive access.
`FORCE` allows you to force the release of the resource entry.
By default, only the owner of the resource entry (e.g. the handle on
the machine that submitted the `REQUEST POOL` request) may
`RELEASE` the entry.
Command
`RELEASE` requires trust level 3.
Command
`RELEASE FORCE` requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
RELEASE also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
The result buffer will contain no data upon return from the RELEASE command.
**Syntax:** `RELEASE POOL AUSVMR ENTRY "User2 Password2"`
**Syntax:** `RELEASE POOL AutoTester_Licenses ENTRY 1137849 FORCE`
Cancels a pending request for a resource pool entry. By default, it cancels the last pending request in the Pending Requests list (which is sorted in ascending order by priority, and then by the request timestamp) that was submitted by the same handle/machine submitting the CANCEL request. You may specify additional selection criteria (such as machine, handle number or name, entry, priority, or first) to specify to cancel a different pending request.
CANCEL POOL <PoolName> [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]] [ENTRY <Value>] [PRIORITY <Number>] [FIRST | LAST]
`POOL` specifies the name of the resource pool from which you
want to cancel a request in its Pending Requests list. This option will resolve variables.
`FORCE` allows you to force cancelling the pending request.
By default, only the requester (e.g. the handle on the machine
that submitted the REQUEST POOL request) may CANCEL the pending
request unless the `FORCE` option is specified, along with
the `MACHINE` and/or `HANDLE`/ `NAME` options.
`MACHINE` specifies the machine that submitted a
request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the machine submitting the
CANCEL request. This option will resolve variables.
`HANDLE` specifies the handle number that submitted
a request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the number of the handle
submitting the CANCEL request. This option will resolve variables.
`NAME` specifies the name of a handle that submitted
a request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the name of the handle
submitting the CANCEL request. This option will resolve variables.
`ENTRY` specifies a resource entry that matches the
"Requested Entry" field in the Pending Requests list for the
request that you want to cancel. It can be specified only
if a particular resource entry was specified by the REQUEST
request that you want to cancel.
`PRIORITY` specifies the priority of the request you
want to cancel. It must be a number from 1 to 99, where 1
indicates the highest priority. This option will resolve variables.
`FIRST` specifies to cancel the first entry in the Pending
Requests list (which is sorted in ascending order by priority and
then by the request timestamp) that matches the selection criteria.
`LAST` specifies to cancel the last entry in the Pending
Requests list (which is sorted in ascending order by priority and
then by the request timestamp) that matches the selection criteria.
This is the default.
Command CANCEL requires trust level 3.
Command CANCEL FORCE requires trust level 4 if you are not the requester (e.g. the handle on the machine that submitted the REQUEST POOL request that you are trying to cancel).
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
CANCEL also returns the return codes documented in
[8.15.13, "Resource Pool Error Code Reference"](#HDRRPRCODE).
On successful return, the result buffer will contain no data.
**Syntax:** `CANCEL POOL TestMachines`
**Syntax:** `CANCEL POOL TestMachines FORCE NAME STAX/Job/3 FIRST`
**Syntax:** `CANCEL POOL MachinePool FORCE MACHINE client1.company.com HANDLE 43 ENTRY system1 PRIORITY 30`
In addition to STAF return codes (see
[Appendix A, "API Return Codes"](#HDRRETCODE) for additional
information), the following Resource Pool return codes are defined:
[Table 82. Resource Pool Service Return Codes]
|Error Code||Meaning||Comment|
4005
|Not entry owner||You are not the owner of the entry you are trying to RELEASE. Use the FORCE option if you are sure that the correct entry is specified.|
4006
|Pool has pending requests||The resource pool you are trying to DELETE has pending requests. If necessary, use the FORCE option.|
4007
|No entries available||The resource pool has no entries.|
4008
|Create pool path error||The directory specified by the |DIRECTORY parameter when
registering the service or the default directory could not be created.
4009
|Invalid pool file format||An error occurred reading the resource pool file due to an error in the file format. If you are using the latest version of the Resource Pool service, contact the STAF authors.|
4010
|Entry is owned||A resource pool entry you specified to REMOVE is owned. Use the FORCE option if you are sure that the correct entry is specified.|
4011
|Not pending requester||You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.|
The SEM service is one of the internal STAF services that allows you to manipulate and manage two kinds of semaphores:
The SEM service provides the following commands:
REQUEST allows you to request exclusive access of a mutex semaphore.
Your request is blocked until all prior pending
`REQUEST`s
have been `RELEASE`d. You may specify a timeout, in milliseconds,
indicating the longest you are willing to wait to gain access to the semaphore.
If no timeout is specified, the request will block indefinitely. The semaphore
is created if it does not exist.
The STAF handle on the machine that submitted the REQUEST MUTEX request to the SEM service will be the "owner" of the mutex semaphore. Note that when a STAF handle that requested a mutex semaphore is deleted, STAF performs garbage collection for the handle by default, unless you specified not to perform garbage collection when requesting a mutex semaphore. Performing garbage collection means when a handle that requested a mutex semaphore is deleted, the SEM service will be notified, and it will release any mutex semaphores that handle owns and will remove any pending requests for mutex semaphores submitted by the handle.
If you submit a REQUEST MUTEX request to the SEM service using the STAF command executable (e.g. from a command prompt or from a shell script), it's important to understand that a STAF command does the following:
REQUEST MUTEX <Name> [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>]
`MUTEX` specifies the name of the mutex semaphore which you
want to request. The semaphore is created if it does not exist. This option will resolve variables.
`TIMEOUT` specifies a timeout duration indicating the longest
you are willing to wait to gain access to the semaphore.
If this option is not specified, the request will wait indefinitely until
the semaphore is available. This option will resolve variables.
The time duration may be expressed in milliseconds, seconds, minutes,
hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w],
where <Number> is an integer >= 0 and indicates milliseconds unless one
of the following case-insensitive suffixes is specified:
`GARBAGECOLLECT` specifies whether to perform garbage collection
when the STAF handle that requested a mutex semaphore is deleted.
Valid values are `Yes` and `No`, not case-sensitive.
The default is `Yes` which means that garbage collection will be
performed for the handle that requested the mutex semaphore. This option will resolve variables.
For example, if you need a mutex semaphore to be owned for a long period of time and the STAF handle that you're going to use to submit the request may not exist for that period of time, then you must specify not to perform garbage collection when requesting a mutex semaphore. This ensures that the mutex semaphore will not be released until a RELEASE MUTEX request for that semaphore is submitted.
This command requires trust level 3.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on a successful return from a REQUEST command.
**Syntax:** `REQUEST MUTEX Printers/Printer1`
**Syntax:** `REQUEST MUTEX DataSource1 TIMEOUT 30s`
**Syntax:** `REQUEST MUTEX Tests/LongLivedSem GARBAGECOLLECT No`
Say you submitted a REQUEST MUTEX request to the SEM service using the STAF command (instead of submitting the request via a Java program, etc). If you didn't specify not to perform garbage collection and if you didn't use a static handle, the mutex semaphore would show up as available (Unowned) when submitting a QUERY MUTEX request to the SEM service because when the STAF command deleted the handle it created to submit the REQUEST MUTEX request, that triggered garbage collection to be performed.
C:\>STAF local SEM REQUEST MUTEX Mutex1 Response -------- C:\>STAF local SEM QUERY MUTEX Mutex1 Response -------- { State : Unowned Owner : <None> Pending Requests: [] }
Instead, you need to specify not to perform garbage collection when submitting the REQUEST MUTEX request to the SEM service using the STAF command. Here's an example shown using the STAF command from a Windows command prompt:
C:\>STAF local SEM REQUEST MUTEX Mutex1 GARBAGECOLLECT No Response -------- C:\>STAF local SEM QUERY MUTEX Mutex1 Response -------- { State : Owned Owner : { Machine : client1.company.com Handle Name : STAF/Client Handle : 80 User : none://anonymous Endpoint : local://local Date-Time Requested : 20070430-15:31:24 Date-Time Acquired : 20070430-15:31:24 Perform Garbage Collection: No } Pending Requests: [] }
Or, you need to first create a static handle and set environment
variable STAF_STATIC_HANDLE to the static handle's number before
submitting a REQUEST MUTEX request to the SEM service using the
STAF command so that the static handle can retain ownership of the
mutex semaphore until it releases the mutex semaphore (or until you
delete the static handle). See
["Using the STAF command from shell-scripts"](#HDRSTAFSHS) for more
information on special environment variable STAF_STATIC_HANDLE.
Here's an example shown using the STAF command from a Windows
command prompt:
C:\>STAF local HANDLE CREATE HANDLE NAME MyHandle Response -------- 82 C:\>set STAF_STATIC_HANDLE=82 C:\>STAF local SEM REQUEST MUTEX Mutex1 Response -------- C:\>STAF local SEM QUERY MUTEX Mutex1 Response -------- { State : Owned Owner : { Machine : client1.company.com Handle Name : MyHandle Handle : 82 User : none://anonymous Endpoint : local://local Date-Time Requested : 20070430-15:32:34 Date-Time Acquired : 20070430-15:32:34 Perform Garbage Collection: Yes } Pending Requests: [] }
RELEASE allows you to release exclusive access to a mutex semaphore.
Normally, only the owning handle may release the mutex semaphore.
Specifying
`FORCE` allows you to force the release of the semaphore.
**Note: **Any thread in the owning handle's process may `RELEASE` the semaphore.
This is in contrast to other semaphore systems, where only the
`REQUEST`ing 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"](#HDRRETCODE).
The result buffer will contain no data on a successful return from a RELEASE command.
**Syntax:** `RELEASE MUTEX Printers/Printer1`
**Syntax:** `RELEASE MUTEX TestABC FORCE`
CANCEL allows you to cancel a pending request for a mutex semaphore. By default, it cancels the last pending request in the Pending Requests list (which is sorted in ascending order by the request timestamp) that was submitted by the same handle/machine submitting the CANCEL request. You may specify additional selection criteria (such as machine, handle number or name, or first) to specify to cancel a different pending request.
CANCEL MUTEX <Name> [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]] [FIRST | LAST]
`MUTEX` specifies the name of the mutex semaphore for which you
want to cancel a request in its Pending Requests list. This option will resolve variables.
`FORCE` allows you to force canceling the pending request for
the semaphore. By default, only the requester (e.g. the handle on the
machine that submitted the REQUEST MUTEX request) may CANCEL the pending
request unless the `FORCE` option is specified, along with the
`MACHINE` and/or `HANDLE`/ `NAME` options.
`MACHINE` specifies the machine that submitted a
request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the machine submitting the
CANCEL request. This option will resolve variables.
`HANDLE` specifies the handle number that submitted
a request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the number of the handle
submitting the CANCEL request. This option will resolve variables.
`NAME` specifies the name of a handle that submitted
a request in the Pending Requests list that you want to cancel.
If not specified, it defaults to the name of the handle
submitting the CANCEL request. This option will resolve variables.
`FIRST` specifies to cancel the first entry in the Pending
Requests list (which is sorted in ascending order by the request
timestamp) that matches the selection criteria.
`LAST` specifies to cancel the last entry in the Pending
Requests list (which is sorted in ascending order by the request
timestamp) that matches the selection criteria. This is the default.
Command CANCEL requires trust level 3.
Command CANCEL FORCE requires trust level 4 if you are not the requester (e.g. the handle on the machine that submitted the REQUEST MUTEX request that you are trying to cancel).
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain no data.
**Syntax:**
`CANCEL MUTEX Printers/Printer1`
or
`CANCEL MUTEX Printers/Printer1 LAST`
**Syntax:**
`CANCEL MUTEX Mutex1 FORCE NAME STAX/Job/3 FIRST`
**Syntax:**
`CANCEL MUTEX Mutex1 FORCE MACHINE client1.company.com HANDLE 43`
POST allows you to post an event semaphore to signal that an event has happened. It is valid to post an event semaphore that is already posted.
POST EVENT <Name>
`EVENT` specifies the name of the event semaphore which you
want to post. The semaphore is created if it does not exist. This option will resolve variables.
This command requires trust level 3.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
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"](#HDRRETCODE).
The result buffer will contain no data on a successful return from a PULSE command.
**Syntax:** `PULSE EVENT Race/StartLap`
WAIT allows you to wait for an event semaphore. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait for an event semaphore. If no timeout is specified, the request will block indefinitely.
WAIT EVENT <Name> [TIMEOUT <Number>[s|m|h|d|w]]
`EVENT` specifies the name of the event semaphore which you
want to wait for. The semaphore is created if it does not exist. This option will resolve variables.
`TIMEOUT` specifies a timeout duration indicating the longest
you are willing to wait for the semaphore.
If this option is not specified, the request will wait indefinitely for
the semaphore. This option will resolve variables.
The time duration may be expressed in milliseconds, seconds, minutes,
hours, days, weeks, or years. Its format is <Number>[s|m|h|d|w],
where <Number> is an integer >= 0 and indicates milliseconds unless one
of the following case-insensitive suffixes is specified:
This command requires trust level 3.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on a successful return from a WAIT command.
**Syntax:** `WAIT EVENT Server1/LAN_Started`
**Syntax:** `WAIT EVENT Coffee/Ready TIMEOUT 20s`
DELETE allows you to delete a mutex or event semaphore.
DELETE MUTEX <Name> | EVENT <Name>
`MUTEX` specifies the name of the mutex semaphore which you
want to delete. A mutex semaphore may only be deleted if there are no pending
`REQUEST`s. 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
`WAIT`ing for it. This option will resolve variables.
This command requires trust level 4.
All return codes are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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
`REQUESTS`s. 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"](#HDRRETCODE).
On successful return, the result buffer will contain information about the specified mutex or event semaphore:
[Table 83. Definition of map class STAF/Service/Sem/QueryMutex]
Description: This map class represents a mutex semaphore.
|Key Name||Display Name||Type||Format / Value|
|state||State|<String>
'Unowned' | 'Owned'
|owner||Owner|<None> | <Map:STAF/Service/Sem/MutexOwner>
|
|
|requestList||Pending Requests|<List> of <Map:STAF/Service/Sem/PendingRequest>
|
|
Notes:
[Table 84. Definition of map class STAF/Service/Sem/MutexOwner]
Description: This map class represents the owner of a mutex semaphore.
|Key Name||Display Name||Type||Format / Value|
|machine||Machine|<String>
|
|
|handleName||handle|<String>
|
|
|handle||Handle|<String>
|
|
|user||User|<String>
<Authenticator>://<User ID>
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|requestTimestamp||Date-Time Requested|<String>
<YYYYMMDD-HH:MM:SS>
|acquireTimestamp||Date-Time Acquired|<String>
<YYYYMMDD-HH:MM:SS>
|gc||Perform Garbage Collection|<String>
'Yes' | 'No'
[Table 85. Definition of map class STAF/Service/Sem/PendingRequest]
Description: This map class represents a pending request which is
waiting to acquire a mutex semaphore.
|Key Name||Display Name||Type||Format / Value|
|machine||Machine|<String>
|
|
|handleName||handle|<String>
|
|
|handle||Handle|<String>
|
|
|user||User|<String>
<Authenticator>://<User ID>
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|requestTimestamp||Date-Time Requested|<String>
<YYYYMMDD-HH:MM:SS>
|gc||Perform Garbage Collection|<String>
'Yes' | 'No'
[Table 86. Definition of map class STAF/Service/Sem/QueryEvent]
Description: This map class represents an event semaphore.
|Key Name||Display Name||Type||Format / Value|
|state||State|<String>
'Posted' | 'Reset'
|lastPosted||Last Posted|<Map:STAF/Service/Sem/EventRequester>
|
|
|lastReset||Last Reset|<Map:STAF/Service/Sem/EventRequester>
|
|
|waiterList||Waiters|<List> of <Map:STAF/Service/Sem/EventRequester>
|
|
Notes:
If the event semaphore is currently in a reset state,
"Waiters" will contain a list of requests waiting for the semaphore, if any.
[Table 87. Definition of map class STAF/Service/Sem/EventRequester]
Description: This map class represents a request for a event semaphore.
|Key Name||Display Name||Type||Format / Value|
|machine||Machine|<String>
|
|
|handleName||handle|<String>
|
|
|handle||Handle|<String>
|
|
|user||User|<String>
<Authenticator>://<User ID>
|endpoint||Endpoint|<String>
<Interface>://<System Identifier>[@<Port>]
|timestamp||Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
**Syntax:** `QUERY MUTEX DataSource1`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
State : Unowned Owner : <None> Pending Requests: []
**Syntax:** `QUERY MUTEX DataSource1`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
{ State : Owned Owner : { Machine : machine1.austin.ibm.com Handle Name : STAX/Job/1 Handle : 17 User : none://anonymous Endpoint : tcp://machine1.austin.ibm.com@6500 Date-Time Requested : 20070430-23:54:41 Date-Time Acquired : 20070430-23:54:41 Perform Garbage Collection: Yes } Pending Requests: [] }
**Syntax:** `QUERY MUTEX DataSource1`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
{ State : Owned Owner : { Machine : machine1.austin.ibm.com Handle Name : STAX/Job/1 Handle : 17 User : none://anonymous Endpoint : tcp://machine1.austin.ibm.com@6500 Date-Time Requested : 20070430-23:54:41 Date-Time Acquired : 20070430-23:54:41 Perform Garbage Collection: Yes } Pending Requests: [ { Machine : machine2.austin.ibm.com Handle Name : STAF/Client Handle : 32 User : none://anonymous Endpoint : tcp://machine2.austin.ibm.com@6500 Date-Time Requested : 20070430-23:56:16 Perform Garbage Collection: No } { Machine : server1.austin.ibm.com Handle Name : semTest Handle : 49 User : IBM://Tester1@us.ibm.com Endpoint : tcp://server1.austin.ibm.com@6500 Date-Time Requested : 20070430-23:56:31 Perform Garbage Collection: Yes } ] }
**Syntax:** `QUERY EVENT Server1/LAN_Started`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
{ State : Posted Last Posted: { Machine : machine1.austin.ibm.com Handle Name: STAF/Client Handle : 20 User : none://anonymous Endpoint : tcp://machine1.austin.ibm.com@6500 Date-Time : 20041026-23:59:51 } Last Reset : { Machine : server2.austin.ibm.com Handle Name: myHandle Handle : 17 User : IBM://Tester1@us.ibm.com Endpoint : tcp://server2.austin.ibm.com@6500 Date-Time : 20041026-23:59:15 } Waiters : [] }
**Syntax:** `QUERY EVENT Server1/LAN_Started`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
{ State : Reset Last Posted: { Machine : machine1.austin.ibm.com Handle Name: STAF/Client Handle : 20 User : none://anonymous Endpoint : tcp://machine1.austin.ibm.com@6500 Date-Time : 20041026-23:59:51 } Last Reset : { Machine : server2.austin.ibm.com Handle Name: myHandle Handle : 17 User : IBM://Test1@us.ibm.com Endpoint : tcp://server2.austin.ibm.com@6500 Date-Time : 20041027-00:02:12 } Waiters : [ { Machine : server2.austin.ibm.com Handle Name: myHandle Handle : 17 User : IBM://Tester1@us.ibm.com Endpoint : tcp://server2.austin.ibm.com@6500 Date-Time : 20041027-00:02:18 } { Machine : machine1.austin.ibm.com Handle Name: STAF/Client Handle : 22 User : none://anonymous Endpoint : tcp://machine1.austin.ibm.com@6500 Date-Time : 20041027-00:02:15 } ] }
LIST allows you to obtain a list of the mutex or event semaphores.
LIST <MUTEX | EVENT>
`MUTEX` specifies that you want a list of the mutex semaphores.
`EVENT` specifies that you want a list of the event semaphores.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain a list of the desired mutex or event semaphores:
[Table 88. Definition of map class STAF/Service/Sem/MutexInfo]
Description: This map class represents a mutex semaphore.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|state||State|<String>
'Unowned' | 'Owned'
|pendingRequests||Pending Requests|<String>
|
|
Notes:
"Pending Requests" is the number of requests waiting to acquire the mutex.
[Table 89. Definition of map class STAF/Service/Sem/EventInfo]
Description: This map class represents an event semaphore.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|state||State|<String>
'Posted' | 'Reset'
|waiters||Waiters|<String>
|
|
Notes:
"Waiters" is the number of waiters waiting on the event semaphore.
**Syntax:** `LIST MUTEX`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Name State Pending Requests ----------------- ------- ---------------- DataSource1 Unowned 0 Printers/Printer1 Owned 2
**Syntax:** `LIST EVENT`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Name State Waiters ------------------- ------ ------- Coffee/Ready Posted 0 Server1/LAN_Started Reset 5 Shutdown_The_Lab Reset 0
The SERVICE service is one of the internal STAF services. It provides the following commands.
LIST will display information about the services, service loaders, or authenticators available on the machine, or requests that have been submitted on the machine.
LIST [ SERVICES | SERVICELOADERS | AUTHENTICATORS | REQUESTS <[PENDING] [COMPLETE] [LONG]> | [SUMMARY] ]
`SERVICES` specifies that you want a list of services that are registered.
`SERVICELOADERS` specifies that you want a list of the service loaders
that are registered.
`AUTHENTICATORS` specifies that you want a list of the authenticators
that are registered.
`REQUESTS` specifies that you want a list of requests.
`PENDING` specifies that the request list should include pending
requests, i.e. requests which are still being processed.
`COMPLETE` specifies that the request list should include completed
requests which have not yet been `FREE`d.
`LONG` specifies that the request list should include more detailed
information about each request.
If neither
`PENDING` nor `COMPLETE` is specified the default
is `PENDING`.
`SUMMARY` specifies that you want summary information about requests
such as the number of active requests, the total number of requests that have
been submitted since STAFProc was started, the number of times the request number
has been reset, the request number range, and the maximum number of active requests.
This command requires trust level 2.
All return codes from LIST are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain information about the request based on the options specified:
[Table 90. Definition of map class STAF/Service/Service/ServiceInfo]
Description: This map class represents a service, serviceloader,
or authenticator.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|library||Library|<String>
'<Internal>', '<Delegated>' or library name if external service
|executable||Executable|<String> | <None>
|
|
Notes:
[Table 91. Definition of map class STAF/Service/Service/RequestInfo]
Description: This map class represents information
about a request that has been submitted.
|Key Name||Display Name||Type||Format / Value|
|requestNumber||Request#
|
(Req#)
<String>
|
|
|state|3
|Status|<String>
'Pending' | 'Complete'
|sourceMachine|1
|Source Machine
|
(Source)
<String>
|
|
|sourceHandleName|1
|Source Handle Name
|
(Handle Name)
<String>
|
|
|sourceHandle|1
|Source Handle
|
(H#)
<String>
|
|
|startTimestamp||Start Date-Time
|
(Date-Time)
<String>
<YYYYMMDD-HH:MM:SS>
|targetMachine|1
|Target Machine
|
(Target)
<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|Private data will be masked.|
|rc|2
|Return Code
|
(RC)
<String> | <None>
|
|
|result|2
|Result|<String> | <None>
|
|
Notes:
[Table 92. Definition of map class STAF/Service/Service/RequestSummary]
Description: This map class represents summary information
about requests.
|Key Name||Display Name||Type||Format / Value|
|activeRequests||Active Requests|<String>
|
|
|totalRequests||Total Requests|<String>
|
|
|resetCount||Reset Count|<String>
|
|
|requestNumberRange||Request Number Range|<String>
|<Minimum - Maximum>|
|maxActiveRequests||Maximum Active Requests|<String>
|
|
Notes:
**Syntax:** `LIST SERVICES`
**Results:** If the request is issued from the
command line, the result, in table format, could look like:
Name Library Executable -------- ---------- ------------------------------------- CRON JSTAF C:\STAF\services\STAFCron.jar DELAY <Internal> <None> DIAG <Internal> <None> ECHO <Internal> <None> EM JSTAF C:\STAF\services\STAFEventManager.jar EMAIL JSTAF C:\STAF\services\STAFEmail.jar EVENT JSTAF C:\STAF\services\STAFEvent.jar FS <Internal> <None> HANDLE <Internal> <None> HELP <Internal> <None> LOG STAFLog <None> MISC <Internal> <None> MONITOR STAFMon <None> NC JSTAF C:\STAF\services\STAFNamedCounter.jar PING <Internal> <None> PROCESS <Internal> <None> QUEUE <Internal> <None> RESPOOL STAFPool <None> SEM <Internal> <None> SERVICE <Internal> <None> SHUTDOWN <Internal> <None> STAX JSTAF C:\STAF\services\STAX.jar TIMER JSTAF C:\STAF\services\STAFTimer.jar TRACE <Internal> <None> TRUST <Internal> <None> VAR <Internal> <None>
**Syntax:** `LIST SERVICELOADERS`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Name Library Executable ------------------ -------- ---------------------------------------- STAFSERVICELOADER1 STAFDSLS <None> STAFSERVICELOADER2 JSTAF C:\STAF\services\CustomServiceLoader.jar
**Syntax:** `LIST AUTHENTICATORS`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Name Library Executable ---------- ------- -------------------------------------------------------- AUTHSAMPLE JSTAF C:\STAF\services\AuthSample.jar IBM JSTAF C:\STAF\services\STAFIBMIntraAuth.jar
**Syntax:** `LIST REQUESTS`
**Results:** If the request is issued from the
command line, the result, in table format, could look like:
Request# Start Date-Time Service Request -------- ----------------- ------- ------------------------------------------ 39 20050321-16:33:03 QUEUE GET WAIT 63 20050321-16:33:03 QUEUE GET WAIT 10000 102 20050321-16:34:42 QUEUE GET WAIT 120000 TYPE ProductA/Test2/Status 165 20050321-16:34:52 DELAY DELAY 60000 106 20050321-16:34:58 SERVICE LIST REQUESTS
**Syntax:** `LIST REQUESTS LONG`
**Results:** If the request is issued from the
command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request ---- ------- ------------ -- --------- ---------- ------- --------------------- 39 local:/ STAF/SERVICE 11 20050321- client1.co QUEUE GET WAIT /local /eM 14:25:04 mpany.com 63 local:/ STAF/Service 16 20050321- client1.co QUEUE GET WAIT 10000 /local /TimeR/Watch 14:25:04 mpany.com 102 local:/ ProductA/Tes 21 20050321- client1.co QUEUE GET WAIT 120000 TYPE /local t2 16:34:42 mpany.com ProductA/Test2/Status 165 local:/ STAF/Client 27 20050321- client2 DELAY DELAY 60000 /local 16:34:52 180 local:/ STAF/Client 34 20050321- client1.co SERVICE LIST REQUESTS LONG /local 14:39:04 mpany.com
**Syntax:** `LIST REQUESTS PENDING COMPLETE LONG`
**Results:** If the request is issued from the
command line, the result, in table format, could look like:
Req# State Source Handle Name H# Date-Time Target Service Request RC Result ---- ------- ------- ----------- -- --------- ------ ------- -------- -- ------ 39 Pending local:/ STAF/SERVIC 11 20050321- client QUEUE GET WAIT <N <None> /local E/eM 14:25:04 1.comp on any.co e> m 63 Pending local:/ STAF/Servic 16 20050321- client QUEUE GET WAIT <N <None> /local e/TimeR/Wat 14:25:04 1.comp 10000 on ch any.co e> m 102 Pending local:/ ProductA/Te 21 20050321- client QUEUE GET WAIT <N <None> /local st2 16:34:42 1.comp 120000 T on any.co YPE Prod e> m uctA/Tes t2/Statu s 165 Pending local:/ STAF/Client 27 20050321- client DELAY DELAY 60 <N <None> /local 16:34:52 2 000 on e> 176 Complet local:/ TestA 36 20050321- client MISC VERSION 0 3.0.0 e /local 13:30:14 1.comp any.co m 180 Pending local:/ STAF/Client 38 20050321- client SERVICE LIST REQ <N <None> /local 13:30:16 1.comp UESTS PE on any.co NDING CO e> m MPLETE L ONG
**Syntax:** `LIST REQUESTS COMPLETE LONG`
**Results:** If the request is issued from the
command line, the result, in table format, could look like:
Req# Source Handle Name H# Date-Time Target Service Request RC Result ---- ------- ----------- -- --------- ---------- ------- -------- -- ------ 176 local:/ TestA 36 20050321- client1.co MISC VERSION 0 3.0.0 /local 13:30:14 mpany.com
**Syntax:** `LIST REQUESTS SUMMARY`
**Results:** If the request is issued from the
command line, the result, in default form, could look like:
Active Requests : 12 Total Requests : 24127 Reset Count : 0 Request Number Range : 1 - 2147483647 Maximum Active Requests: 2147483647
QUERY will display information about a service, authenticator, or service loader available on the machine, or about a request that has been submitted on the machine.
QUERY SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> | AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number>
`SERVICE` specifies the name of the service to be queried.
`SERVICELOADER` specifies the name of the service loader
to be queried.
`AUTHENTICATOR` specifies the name of the authenticator service
to be queried.
`REQUEST` specifies the number of the request to be queried.
This command requires trust level 2.
All return codes from QUERY are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If successful, the result buffer will contain the following based on the request:
[Table 93. Definition of map class STAF/Service/Service/QueryService]
Description: This map class represents a service, service
loader, or authenticator.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|
|
|library||Library|<String>
'<Internal>', '<Delegated>' or library name if external service
|executable||Executable|<String> | <None>
|
|
|options||Options||List of |<String>
|
|
|parameters||Parameters|<String> | <None>
|
|
Notes:
[Table 94. Definition of map class STAF/Service/Service/QueryRequest]
Description: This map class represents a request that has been submitted.
|Key Name||Display Name||Type||Format / Value|
|requestNumber||Request#|<String>
|
|
|state||Request Status|<String>
'Pending' | 'Complete'
|sourceMachine||Source Machine|<String>
|
|
|sourceHandleName||Source Handle Name|<String>
|
|
|sourceHandle||Source Handle|<String>
|
|
|startTimestamp||Start Date-Time|<String>
<YYYYMMDD-HH:MM:SS>
|targetMachine||Target Machine|<String>
|
|
|service||Service|<String>
|
|
|request||Request|<String>
|
|
|rc||Return Code|<String> | <None>
|
|
|result||Result|<String> | <None>
|
|
Notes:
**Syntax:** `QUERY SERVICE LOG`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Name : LOG Library : STAFLog Executable: <None> Options : [] Parameters: DEFAULTMAXQUERYRECORDS 50 }
**Syntax:** `QUERY SERVICE STAX`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Name : STAX Library : JSTAF Executable: C:\STAF\services\stax\STAX.jar Options : [ JVMName=STAX J2=-Xmx512m ] Parameters: EXTENSIONXMLFILE C:/STAF/services/stax/extensions.xml }
**Syntax:** `QUERY AUTHENTICATOR AuthSample`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Name : AUTHSAMPLE Library : JSTAF Executable: C:\STAF\authenticators\AuthSample.jar Options : [ JVMName=Auth ] Parameters: USERPROPERTIESFILE C:/STAF/authenticators/authsample.properties }
**Syntax:** `QUERY SERVICELOADER STAFServiceLoader1`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
{ Name : STAFSERVICELOADER1 Library : STAFDSLS Executable: <None> Options : [] Parameters: <None> }
**Syntax:** `QUERY REQUEST 34`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Request Number : 34 Request Status : Pending Source Machine : local://local Source Handle Name: STAF/SERVICE/EM Source Handle : 10 Start Date-Time : 20050321-19:02:28 Target Machine : server1.company.com Service : QUEUE Request : GET WAIT Return Code : <None> Result : <None>
ADD will add (register and initialize) the specified external service and make it available on the machine.
ADD SERVICE <Service Name> LIBRARY <Library Name> [EXECUTE <Executable>] [OPTION <Name[=Value]>]... [PARMS <Parameters>]
`SERVICE` specifies the name by which this service will be known on this machine.
`LIBRARY` specifies the name of the shared library / DLL which implements the
service or acts as a proxy for the service. See the information for each
external service to determine the appropriate value for this option.
`EXECUTE` is used by service proxy libraries / DLLs to specify what the proxy
library should execute. For example, this might be the name of the Java jar file
which actually implements the service. This option has no significance for non-proxy service
libraries. See section [4.4.2, "JSTAF service proxy library"](#HDRJVMCFG) 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"](#HDRJVMCFG) 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"](#HDRRETCODE).
On successful return, the result buffer will contain nothing.
**Syntax:** `ADD SERVICE Monitor LIBRARY STAFMon`
**Syntax:** `ADD SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar PARMS "NUMTHREADS 8"`
REMOVE will remove (unregister and terminate) the specified external service, making it no longer available on the machine.
**Note: **If pending requests for the service exist, it may take up to a minute
or so after the REMOVE request has completed in order for the service to
complete its termination process. This can be especially true for a service
that is registered using a service proxy library such as JSTAF which is used
when registering Java services as it may take another minute or so for the JVM
that this service was running in to be terminated (assuming that the Java
service being removed is the only Java service running in this JVM).
REMOVE SERVICE <Service Name>
`SERVICE` specifies the name of the service to remove.
This command requires trust level 5.
All return codes from REMOVE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRAPISS2) 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"](#HDRRETCODE).
If successful, the result buffer for a
`FREE` request will contain
a marshalled `<Map:STAF/Service/Service/FreeRequestInfo>`
representing the results of the completed request.
The map is defined as follows:
[Table 95. Definition of map class STAF/Service/Service/QueryRequest]
Description: This map class represents the results of a completed request.
|Key Name||Display Name||Type||Format / Value|
|rc||Return Code|<String>
|
|
|result||Result|<String>
|
|
Notes:
**Syntax:** `FREE REQUEST 16`
**Results:** If the request is issued from the command line,
the result, in default format, could look like:
Return Code: 0 Result : 3.0.0
The SHUTDOWN service is an internal STAF service. It provides the following commands.
SHUTDOWN, as the name implies, submits a request to shut down the STAFProc program.
**Note: **A SHUTDOWN request returns before STAFProc completes shutting down.
It may take up to a minute or so after a SHUTDOWN request has returned for
STAFProc to finish shutting down all of its registered services.
SHUTDOWN
This command requires trust level 5.
All return codes from SHUTDOWN are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a SHUTDOWN command.
Goal: Shutdown STAFProc on the local system.
STAF local SHUTDOWN SHUTDOWN
NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when the STAF Process is SHUTDOWN.
NOTIFY <REGISTER | UNREGISTER> [MACHINE <Machine>] [PRIORITY <Priority>] [HANDLE <Handle> | NAME <Name>]
`REGISTER` indicates you want to register a shutdown notification.
The type of the notification message will be `STAF/Shutdown` with a blank message.
`UNREGISTER` indicates you want to unregister a shutdown
notification
`MACHINE` specifies the machine to which the notification should
be sent. The default is the machine submitting the request. This option will resolve variables.
`PRIORITY` specifies the priority of the notification message.
The default is 5. This option will resolve variables.
`HANDLE` specifies the handle to which the notification should be
sent. The default is the handle of the process submitting the request.
This option will resolve variables.
`NAME` specifies the registered name of the process(es) to which
the notification should be sent. This option will resolve variables.
These commands require trust level 3.
All return codes from NOTIFY REGISTER/UNREGISTER are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
On successful return, the result buffer for a
`NOTIFY LIST`
request will contain a marshalled
`<List> of <Map:STAF/Service/Shutdown/Notifiee>`
representing a list of all the registered notifiees.
The map is defined as follows:
[Table 96. Definition of map class STAF/Service/Shutdown/Notifiee]
Description: This map class represents a registered shutdown notifiee.
|Key Name||Display Name||Type||Format / Value|
|priority||Priority|<String>
'Stdout' | 'Stderr' or a file name
|machine||Machine|<String>
'Enabled' | 'Disabled'
|notifyBy||Notify By|<String>
'Name' | 'Handle'
|notifiee||Notifiee|<String>
Notes:
If the "Notify By" value is 'Name', the notifiee will be notified by handle name
and the "Notifiee" value will be the handle name.
Otherwise, if the "Notify By" value is 'Handle', the notifiee will be
notified by handle and the "Notifiee" value will be the handle number.
**Request:** `NOTIFY LIST`
**Results:** If the request is issued from the command line,
the result, in table format, could look like:
Priority Machine Notify By Notifiee -------- ---------------------- --------- --------------- 5 server1.austin.ibm.com Name ShutdownCatcher 3 client2.austin.ibm.com Handle 18
The TRACE service is one of the internal STAF services. It provides the following trace commands.
The purpose of the Trace service is to allow you to control the trace messages recorded for STAF services. For example, if you are experiencing a problem with a STAF service or a request to a STAF service, you can specify various STAF trace points and/or STAF service(s) to be enabled for tracing to record additional trace messages which can help you resolve the problem.
**Note: **If you enable one or more of the "service" tracepoints (e.g. ServiceRequest,
ServiceResult, ServiceError, ServiceAccessDenied, or RemoteRequests), these trace
messages will only be reported for the services you have enabled for tracing.
The format of each trace message is the following
<Timestamp>;<Thread>;<Trace Point>;<Message>
where:
`<Timestamp>` is the date/time of the message.
`<Thread>` is the thread on which the message originated.
`<Trace Point>` is the hexadecimal representation of the message's
trace point. See table [8.19.2, "Trace Points Reference"](#HDRTRACEPOINTREF) for a list of trace points.
`<Message>` is the actual trace message. Private data will be masked.
Here's an example of a
`ServiceManagement` trace message:
20050811-16:20:50;1;00000010;Service HELP: Initializing
Here's an example of a
`Warning` trace message:
20050811-10:10:50;4836;00000400;STAFConnectionManager::makeConnection - Attempt #1 of 2 (Delay 41 milliseconds), RC: 16, Result: STAFConnectionProviderConnect: Timed out connecting to endpoint: select() timeout: 22, Endpoint: client1
Here's an example of
`ServiceRequest` and `ServiceResult` trace messages:
20050811-10:33:54;4836;00000001;PROCESS Service Request - Client: local://local, Handle: 30, Process: STAF/Client, Request: start command date returnstdout wait 20050811-10:33:54;4836;00000002;PROCESS Service Result (0) - Client: local://loc al, Handle: 30, Process: STAF/Client, Request: start command date returnstdout w ait, Result: { Return Code: 0 Key : <None> Files : [ { Return Code: 0 Data : Thu Aug 11 10:33:54 CDT 2005 } ] }
The following are the valid trace points along with their hexadecimal representation
and their descriptions.
The hexadecimal representation of a trace point is logged in each trace message.
Trace points are not case sensitive.
[Table 97. Trace point hexadecimal representation]
|Hex||Trace point||Description|
|00000001|ServiceRequest
|The trace point which causes a trace message to be generated for every incoming service request before it is processed by the service.|
|00000002|ServiceResult
|The trace point which causes a trace message to be generated for every
incoming service request after it is processed by the service.
Note that the trace message will include the return code and result for the
service request.
This tracepoint overrides the |ServiceComplete,
ServiceError and ServiceAccessDenied tracepoints.
|00000004|ServiceError
|The trace point which causes a trace message to
be generated for every incoming service request which results in a non-zero
error code. Note that the trace message will include the return code and
result for the service request.
This tracepoint overrides the |ServiceAccessDenied tracepoint.
|00000008|ServiceAccessDenied
|The trace point which causes a trace message to be generated for every incoming service request which results in an "Insufficient Trust Level" (aka "Access Denied") error code.|
|00000010|ServiceManagement
|The trace point which causes a trace message to be generated for service management operations such as service initialization and termination.|
|00000020|RemoteRequests
|The trace point which enables trace message to be generated for requests destined for other machines.|
|00000100|Error
|The trace point which causes a trace message to be generated for error
conditions that STAF detects, such as broken communication connections and
fatal STAF Service errors. The |Error trace point is turned on
by default.
|00000200|Registration
|The trace point which causes a trace message to be generated for every registration or unregistration done by a process.|
|00000400|Warning
|The trace point which causes a trace message to be generated for warning conditions that STAF detects.|
|00000800|Info
|The trace point which causes a trace message to be generated for information conditions that STAF detects.|
|00001000|Deprecated
|The trace point which causes a trace message to be generated for
deprecated options that STAF detects.
A deprecated option is not recommended for use, generally due to improvements,
and a replacement option is usually given. Deprecated options may be removed in
future implementations. The |Deprecated trace point is turned on by default.
|00002000|Debug
|The trace point which causes a trace message to be generated for debug conditions that STAF detects.|
|00004000|ServiceComplete
|The trace point which causes a trace message to be generated for every
incoming service request after it is processed by the service.
Note that the trace message will include the return code and result length
for the service request, but not the result data.
This tracepoint overrides the |ServiceError and
ServiceAccessDenied tracepoints.
ENABLE allows you to enable trace points and STAF services for tracing.
See table
[8.19.2, "Trace Points Reference"](#HDRTRACEPOINTREF) 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"](#HDRRETCODE).
For
`ENABLE` the result buffer will be empty if there are no errors
**Syntax:** `ENABLE TRACEPOINTS "ServiceRequest ServiceResult ServiceManagement"`
**Syntax:** `ENABLE TRACEPOINTS "Error Warning"`
**Syntax:** `ENABLE ALL TRACEPOINTS`
**Syntax:** `ENABLE TRACEPOINT RemoteRequests`
**Syntax:** `ENABLE SERVICES "PROCESS QUEUE"`
**Syntax:** `ENABLE ALL SERVICES`
**Syntax:** `ENABLE ALL`
**Syntax:** `ENABLE SERVICE VAR`
**Syntax:** `ENABLE SERVICE :7:SERVICE`
DISABLE allows you to disable trace points and STAF services for tracing.
See table
[8.19.2, "Trace Points Reference"](#HDRTRACEPOINTREF) 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"](#HDRRETCODE).
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"](#HDRRETCODE).
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"](#HDRRETCODE).
On successful return, the result buffer for a
`LIST`
request will contain a marshalled
`<Map:STAF/Service/Trace/TraceInfo>`
representing the current trace settings.
The maps are defined as follows:
[Table 98. Definition of map class STAF/Service/Trace/TraceInfo]
Description: This map class represents the current trace settings.
|Key Name||Display Name||Type||Format / Value|
|tracingTo||Tracing To|<String> | <List> of <String>
|
|
|fileMode||File Mode|<String> | <None>
'Replace' | 'Append'
|defaultServiceState||Default Service State|<String>
'Enabled' | 'Disabled'
|maxServiceResultSize||Maximum Service Result Size|<String>
|
|
|tracePoints||Trace Points|<Map:STAF/Service/Trace/Tracepoint>
|
|
|services||Services|<Map:STAF/Service/Trace/Service>
|
|
Notes:
[Table 99. Definition of map class STAF/Service/Trace/Tracepoint]
Description: This map class represents the tracepoints and their
trace states.
|Key Name||Display Name||Type||Format / Value|
|INFO||Info|<String>
'Enabled' | 'Disabled'
|WARNING||Warning|<String>
'Enabled' | 'Disabled'
|ERROR||Error|<String>
'Enabled' | 'Disabled'
|SERVICEREQUEST||ServiceRequest|<String>
'Enabled' | 'Disabled'
|SERVICERESULT||ServiceResult|<String>
'Enabled' | 'Disabled'
|SERVICEERROR||ServiceError|<String>
'Enabled' | 'Disabled'
|SERVICEACCESSDENIED||ServiceAccessDenied|<String>
'Enabled' | 'Disabled'
|REMOTEREQUESTS||RemoteRequests|<String>
'Enabled' | 'Disabled'
|REGISTRATION||Registration|<String>
'Enabled' | 'Disabled'
|DEPRECATED||Deprecated|<String>
'Enabled' | 'Disabled'
|DEBUG||Debug|<String>
'Enabled' | 'Disabled'
[Table 100. Definition of map class STAF/Service/Trace/Service]
Description: This map class represents the services and their
trace states.
|Key Name||Display Name||Type||Format / Value|
<ServiceName>
<ServiceName>
<String>
'Enabled' | 'Disabled'
Notes:
This map is dynamically generated at the time of the LIST request
based on the services in the trace status list at that time. It's keys
will be the names of the internal services plus any external services that
have been registered and any other services for which tracing has been
explicitly set.
**Syntax:** `LIST` or `LIST SETTINGS`
**Results:** If the request is issued from the command line,
the result, in verbose format, could look like:
{ Tracing To : Stdout File Mode : <None> Default Service State : Enabled Maximum Service Result Size: 0 Trace Points : { Info : Disabled Warning : Enabled Error : Enabled ServiceRequest : Disabled ServiceResult : Disabled ServiceError : Disabled ServiceAccessDenied: Disabled RemoteRequests : Disabled Registration : Disabled Deprecated : Enabled Debug : Disabled } Services : { DELAY : Enabled DIAG : Disabled ECHO : Enabled EMAIL : Enabled EVENT : Enabled FS : Enabled HANDLE : Enabled HELP : Disabled LOG : Enabled MONITOR : Enabled MISC : Enabled PING : Enabled PROCESS : Enabled QUEUE : Enabled SEM : Enabled SERVICE : Enabled SHUTDOWN: Enabled STAX : Enabled TRACE : Enabled TRUST : Enabled VAR : Enabled } }
Allows you to set the destination for the tracing information, the default tracing state for new services, or the maximum size (in characters) of the service result string to write to the trace output when the ServiceResult tracepoint is enabled.
SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] > SET DEFAULTSERVICESTATE < Enabled | Disabled > SET MAXSERVICERESULTSIZE <Number>[k|m]
`DESTINATION TO` indicates to set the destination for the tracing
information. Note that you must specify at least one of `STDOUT`,
`STDERR`, or `FILE`. You can specify both
`STDOUT` and `FILE` or both `STDERR` and
`FILE`.
`STDOUT` indicates that trace messages should be sent to the
standard output device (Stdout). Note that you can specify that trace
messages should be sent to both Stdout and a file.
`STDERR` indicates that trace messages should be sent to the
standard error device (Stderr). Note that you can specify that trace
messages should be sent to both Stderr and a file.
`FILE` indicates that trace messages should be sent to the
indicated file. Note that the path to the file must already exist. This option will resolve variables.
`APPEND` indicates that destination trace file will be appended
to if it exists. If this option is not specified, the destination trace file
will be replaced if it exists. This option can only be specified if the
`FILE` option was specified.
`DEFAULTSERVICESTATE` sets the default tracing state for services that have not yet
registered with STAF. The default tracing state for services is enabled. This option will resolve variables.
`MAXSERVICERESULTSIZE` specifies the maximum size (in characters)
of the service result string to write to the trace output when
the ServiceResult tracepoint is enabled. If not specified, the
default is 0 (which indicates to write the entire service result
string to the trace output). This value may be expressed in bytes, kilobytes,
or megabytes. Its format is <Number>[k|m] where <Number> is an integer >= 0 and
indicates bytes unless one of the following case-insensitive suffixes is
specified: k (for kilobytes) or m (for megabytes). The calculated value cannot
exceed 4294967295 bytes. Examples of valid values include 100000, 500k, or 5m.
This command requires trust level 5.
All return codes from SET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
For
`SET` the result buffer will be empty
**Syntax:** `SET DESTINATION TO STDERR`
**Syntax:** `SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc`
**Syntax:** `SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc APPEND`
**Syntax:** `SET DESTINATION TO STDOUT FILE {STAF/Config/STAFRoot}/bin/STAF.trc`
**Syntax:** `SET DEFAULTSERVICESTATE Enabled`
**Syntax:** `SET MAXSERVICERESULTSIZE 5k`
The TRUST Service is one of the internal STAF services. It allows you to query and set the trust entries. It provides the following commands.
SET will set the default trust level or the trust level for a specific machine or user.
SET <MACHINE <Machine> | USER <User> | DEFAULT> LEVEL <Level>
`MACHINE` indicates a machine for which to set a trust level.
This option will resolve variables.
The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).
Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.
Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)
`USER` indicates a user for which to set a trust level.
This option will resolve variables.
The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
`DEFAULT` specifies that you want to set the default trust level.
`LEVEL` specifies the level of trust you wish to set.
This option will resolve variables.
This command requires trust level 5.
All return codes from SET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a SET command.
**Syntax:** `SET MACHINE local://local LEVEL 5`
**Syntax:** `SET DEFAULT LEVEL 1`
**Syntax:** `SET MACHINE client1.austin.ibm.com LEVEL 5`
**Syntax:** `SET MACHINE 9.3.224.16 LEVEL 5`
**Syntax:** `SET MACHINE tcp://mysystem.site.com LEVEL 4`
**Syntax:** `SET MACHINE badguy.austin.ibm.com LEVEL 0`
**Syntax:** `SET MACHINE tcp2://9.3.224.* LEVEL 3`
**Syntax:** `SET MACHINE *.austin.ibm.com LEVEL 2`
**Syntax:** `SET MACHINE tcp*://*.site.com LEVEL 2`
**Syntax:** `SET USER John@company.com LEVEL 5`
**Syntax:** `SET USER badguy@company.com LEVEL 0`
**Syntax:** `SET USER *@company.com LEVEL 3`
**Syntax:** `SET USER SampleAuth://*@company.com LEVEL 4`
**Syntax:** `SET USER *://* LEVEL 1`
GET will return the effective trust level of a specific machine and, optionally, for a specific user.
GET MACHINE <Machine> [USER <User>]
`MACHINE` specifies the machine for which to return the
effective trust level.
This option will resolve variables.
The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Wildcard patterns, '*' and '?', should not be specified. If a port is included (e.g. @6500) at the end of the machine value, it will be removed.
If the machine has a matching
`MACHINE` trust entry,
the effective trust level is the level specified in the
`MACHINE` trust entry. Otherwise, the effective trust
level is the default trust level.
`USER` specifies the user for which to return the effective
trust level.
This option will resolve variables.
The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Wildcard patterns, '*' and '?', cannot be specified.
If the user has a matching
`USER` trust entry,
the effective trust level is the level specified in the
`USER` trust entry. Otherwise, if the machine has a
matching `MACHINE` trust entry, the effective trust
level is the level specified in the `MACHINE` trust
entry. Otherwise, the effective trust level is the default
trust level.
This command requires trust level 2.
All return codes from GET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
The result buffer will contain a marshalled
`<List> of <Map:STAF/Service/Trust/Entry>`, representing
all the trust entries. The first trust entry in the list will be for
the default trust entry, followed by trust entries for machines,
and then followed by trust entries for users.
The map is defined as follows:
[Table 101. Definition of map class STAF/Service/Trust/Entry]
Description: This map class represents a trust entry.
|Key Name||Display Name||Type||Format / Value|
|type||Type|<String>
'Default' | 'Machine' | 'User'
|entry||Entry|<String> | <None>
<Machine Spec> | <User Spec)
|trustLevel||Trust Level|<String>
'0' - '5'
Notes:
**Syntax:** `LIST`
**Result:** If the request is submitted from the command line,
the result, in table format, could look like:
Type Entry Trust Level ------- ----------------------------- ----------- Default <None> 1 Machine *://*.austin.ibm.com 2 Machine *://9.31.73.14* 3 Machine *://9.31.73.147 5 Machine *://client1.austin.ibm.com 5 Machine *://client3.austin.ibm.com 3 Machine local://local 5 Machine tcp://client2.austin.ibm.com 0 User SampleAuth://*@company.com 3 User SampleAuth://Jane@company.com 4 User SampleAuth://John@company.com 5
DELETE will remove the explicit trust entry for the specified machine or user.
DELETE MACHINE <Machine> | USER <User>
`MACHINE` specifies the machine for which you wish to delete the
specific trust entry.
This option will resolve variables.
The format for <Machine> is:
[<Interface>://]<System Identifier>where:
If a port is included (e.g. @6500) at the end of the machine value, it will be removed.
`USER` specifies the user for which you wish to delete the
specific trust entry.
This option will resolve variables.
The format for <User> is:
[<Authenticator>://]<User Identifier>where:
This command requires trust level 5.
All return codes from DELETE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
The result buffer will contain no data on return from a DELETE command.
**Syntax:** `DELETE MACHINE client1.austin.ibm.com`
**Syntax:** `DELETE MACHINE tcp://mysystem.site.com`
**Syntax:** `DELETE MACHINE 9.3.224.82`
**Syntax:** `DELETE MACHINE *.austin.ibm.com`
**Syntax:** `DELETE USER John@company.com`
**Syntax:** `DELETE USER *@company.com`
**Syntax:** `DELETE USER Auth2://Mary`
**Syntax:** `DELETE USER *://*`
The Variable Service, called VAR, is one of the internal STAF services. It allows you to manage the system, shared, and per-process variable pools. It provides the following commands.
SET will set a variable to a certain value. The variable is created if it does not exist.
Note that you may SET multiple variables with a single request.
SET [SYSTEM | SHARED | HANDLE <Handle>] [FAILIFEXISTS] VAR <Name=Value> [VAR <Name=Value>]...
`SYSTEM` specifies that you want to set the value of the variable
in the system variable pool.
`SHARED` specifies that you want to set the value of the variable
in the shared variable pool.
`HANDLE` indicates that you want to set the value of the variable
in the variable pool associated with the specified handle.
If options
`SYSTEM`, `SHARED`, and `HANDLE` are
not specified, the variable will be set in the variable pool associated with the
handle of the process that submitted the request unless the request came from another
machine, in which case the variable will be set in the system variable pool.
`FAILIFEXISTS` specifies that the set request should fail with
return code 49 (Already Exists) if the variable already exists in the specified
variable pool and its current value will be returned in the result.
If this option is not specified and the variable already exists, the variable's
value will be updated.
`VAR` specifies the name of a variable and the value to which it
should be set. Its format must be Name=Value. You can specify this option
multiple times to set multiple variables.
This command requires trust level 3.
All return codes from SET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If multiple variables are set via a single SET request and all variables were set successfully, the return code will be 0. If one or more variables were not set successfully, the return code will be set to the return code of the first variable that could not be set successfully. Note that all variables specified will be attempted to be set.
If successful, the result buffer will contain no data.
If the request failed, the result buffer's contents are based on whether
the
`VAR` option was specified once or multiple times as follows:
[Table 102. Definition of map class STAF/Service/Var/ErrorInfo]
Description: This map class represents information on whether
a variable was successfully set.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|rc||RC|<String>
|
|
|result||Result|<String>
|
|
Notes:
If a variable is set successfully, its "RC" value will be '0' and its
"Result" will be blank. If a variable is not set successfully because the
GET will retrieve the value of a variable.
**Note: **You almost never want to use the GET command. Instead, you should use
RESOLVE to retrieve the value of a variable.
GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name>
`SYSTEM` specifies that you want to get the value of the variable
from the system variable pool.
`SHARED` specifies that you want to get the value of the variable
from the shared variable pool.
`HANDLE` indicates that you want to get the value of the variable
from the variable pool associated with the specified handle.
If options
`SYSTEM`, `SHARED`, and `HANDLE` are
not specified, the value of the variable will be retrieved from the variable
pool associated with the handle of the process that submitted the request
unless the request came from another machine, in which case the variable will
be retrieved from the system variable pool.
`VAR` specifies the name of the variable whose value you want to get.
This command requires trust level 2.
All return codes from GET are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
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"](#HDRRETCODE).
The result buffer will contain a marshalled
`<Map:STAF/Service/Var/VarInfo>` with an entry for each variable.
The map is defined as follows:
[Table 103. Definition of map class STAF/Service/Var/VarInfo]
Description: This map class represents the variables.
|Key Name||Display Name||Type||Format / Value|
|<Variable Name>||<Variable Name>|<String>
|
|
Notes:
This map is dynamically generated with the key being a variable name and the
value being the value for the variable.
If the request is submitted from the command line, the result, in default format, could look like:
Bad String : SYS3175 Good String : Command completed successfully STAF/Config/BootDrive : C: STAF/Config/CodePage : IBM-437 STAF/Config/ConfigFile : C:\staf\bin\STAF.cfg STAF/Config/DefaultAuthenticator: AuthSample STAF/Config/DefaultInterface : tcp STAF/Config/InstanceName : STAF STAF/Config/Machine : client1.company.com STAF/Config/MachineNickname : client1 STAF/Config/Mem/Physical/Bytes : 804175872 STAF/Config/Mem/Physical/KB : 785328 STAF/Config/Mem/Physical/MB : 766 STAF/Config/OS/MajorVersion : 5 STAF/Config/OS/MinorVersion : 0 STAF/Config/OS/Name : Win2000 STAF/Config/OS/Revision : 2195 STAF/Config/Processor/NumAvail : 1 STAF/Config/Sep/Command : & STAF/Config/Sep/File : \ STAF/Config/Sep/Line : STAF/Config/Sep/Path : ; STAF/Config/STAFRoot : C:\STAF STAF/Config/StartupTime : 20080421-14:15:37 STAF/DataDir : C:\STAF\data\STAF STAF/Env/ALLUSERSPROFILE : C:\Documents and Settings\All Users STAF/Env/APPDATA : C:\Documents and Settings\Administrator\Application Data STAF/Env/CLASSPATH : .;C:\STAF\lib\JSTAF.jar STAF/Env/CommonProgramFiles : C:\Program Files\Common Files STAF/Env/COMPUTERNAME : CLIENT1 STAF/Env/ComSpec : C:\WINNT\system32\cmd.exe STAF/Env/CVS_RSH : ssh STAF/Env/HOMEDRIVE : C: STAF/Env/HOMEPATH : \Documents and Settings\Administrator STAF/Env/INCLUDE : C:\Program Files\ObjREXX\API STAF/Env/LIB : C:\Program Files\ObjREXX\API STAF/Env/LOGONSERVER : \\CLIENT1 STAF/Env/NUMBER_OF_PROCESSORS : 1 STAF/Env/OS : Windows_NT STAF/Env/Os2LibPath : C:\WINNT\system32\os2\dll; STAF/Env/Path : C:\ibmjdk1.4.2\bin;C:\STAF\bin;C:\WINNT\system32;C:\WINNT;C:\WINNT\System32\Wbem;C:\cygwin\bin; STAF/Env/PATHEXT : .COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.RB;.RBW STAF/Env/PD_SOCKET : 6874 STAF/Env/PDBASE : C:\PROGRA~1\IBM\INFOPR~1 STAF/Env/PDHOST : STAF/Env/PROCESSOR_ARCHITECTURE : x86 STAF/Env/PROCESSOR_IDENTIFIER : x86 Family 15 Model 2 Stepping 7, GenuineIntel STAF/Env/PROCESSOR_LEVEL : 15 STAF/Env/PROCESSOR_REVISION : 0207 STAF/Env/ProgramFiles : C:\Program Files STAF/Env/PROMPT : $P$G STAF/Env/SOUNDPATH : C:\WINNT STAF/Env/SystemDrive : C: STAF/Env/SystemRoot : C:\WINNT STAF/Env/TEMP : C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp STAF/Env/TMP : C:\DOCUME~1\ADMINI~1\LOCALS~1\Temp STAF/Env/USERDOMAIN : CLIENT1 STAF/Env/USERNAME : Administrator STAF/Env/USERPROFILE : C:\Documents and Settings\Administrator STAF/Env/windir : C:\WINNT STAF/Service/NC/Persist : True STAF/Version : 3.3.0 WebServer : testsrv1.test.austin.ibm.com
RESOLVE allows you to have all variable references in a string resolved to their values. A variable reference is denoted by surrounding the variable in curly braces, for example, {WebServer}. Recursive and compound variable references are allowed (see the examples).
Note that you may RESOLVE multiple strings with a single request.
Because of this special significance of "{", if you do not want variable substitution performed, use a caret, "^", as an escape character for "{" and "^", or specify the IGNOREERRORS option. Note that a caret cannot be used as an escape character within a variable reference (see the examples).
RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] STRING <String> [STRING <String>]... [IGNOREERRORS]
`SYSTEM` specifies that only variables from the system variable
pool should be used to resolve a variable reference.
`SHARED` specifies that only variables from the shared variable
pool should be used to resolve a variable reference.
`HANDLE` specifies that only variables from the handle variable
pool should be used to resolve a variable reference.
`ASHANDLE` indicates the variable reference should try to be resolved from
the specified handle's variable pool, its system's shared variable pool, and its
system's system variable pool. Variables in a pool earlier in the list override
variables in a pool later in the list.
`REQUEST` with a request number indicates the variable reference
should try to be resolved from the originating handle's pool associated with
the specified request number, the originating system's shared pool, the local
system's shared pool, and the local system's system pool if the request came from
remote; otherwise, will use the originating handle's pool associated with the
specified request number, the local system's shared pool, and the local system's
system pool if the request came from local. Variables in a pool earlier in the list
override variables in a pool later in the list.
If the
`REQUEST` option is specified without specifying a request number,
variable resolution is done in the context of the RESOLVE request itself.
Also, if you don't specify the `SYSTEM`, `SHARED`, `HANDLE`,
`ASHANDLE`, or `REQUEST` option, the behavior will be the
same as when you specify the `REQUEST` option without specifiying a
request number.
`STRING` specifies a string that may contain one or more variable
references.
`IGNOREERRORS` specifies to not assume that every "{" in the
string being resolved denotes a reference to a STAF variable.
When using this option, you will not get a RC 13 (Variable Does Not Exist) or
RC 15 (Invalid Resolve String) error because:
This command requires trust level 2.
All return codes from RESOLVE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
On successful return, the result buffer will contain results based on whether
the
`STRING` option was specified once or multiple times:
[Table 104. Definition of map class STAF/Service/Var/ResolveString]
Description: This map class represents a string with all variable references resolved.
|Key Name||Display Name||Type||Format / Value|
|rc||RC|<String>
|
|
|result||Result|<String>
|
|
Notes:
If all variables in the string are resolved successfully, the "RC" value will be '0' and the "Result" will contain the string with all variable references resolved. Otherwise, if an error occurred resolving a string, the "RC" value will contain the error return code and the result will contain additional information on the error, such as the name of a variable that could not be resolved.
For the following examples, assume the following variables are in System1's system variable pool
a=Partridge b=Doves c=Hens d=Birds e=Ringsthe following variables are in System1's shared variable pool
a=Happy b=Sleepythe following variables are in System1's originating handle variable pool
a=Onethe following variables are in System2's system variable pool
a=Geese b=Swans c=Maids d=Ladies e=Lordsthe following variables are in System2's shared variable pool
d=Grumpy e=Dopeyand the following variables are in the System1's variable pool associated with handle 71
a=Dogs b=CatsLet's assume the following requests are done from System1:
The following examples show the use of a caret (^) as an escape character for "{" and "^". Assume the following variables are in the system variable pool for these examples:
h=Hi Hi=HI ^Hi=Hello
Note that {^{h}} shows that a caret cannot be used as an escape character within a variable reference.
Here's an example of resolving multiple strings in a single RESOLVE request.
RC Result -- ---------------------------------------------------------------------------- 0 3.4.1 13 Variable resolution failed for string: {aaa} You are trying to resolve a va riable that does not exist: aaa 0 C:
Here's an example of using the IGNOREERRORS option on a VAR RESOLVE request:
PythonMap = {'x': 1, 'osName': 'Linux'}
If you did not use the IGNOREERRORS option, RC 13 (Variable Does Not Exist) would have been returned as follows:
Error submitting request, RC: 13 Additional info --------------- Variable resolution failed for string: PythonMap = {'x': 1, 'osName': '{STAF/Config/OS/Name}'} You are trying to resolve a variable that does not exist: 'x': 1, 'osName': 'Linux'
DELETE will remove the given variable from the appropriate variable pool.
Note that you may DELETE multiple variables with a single request.
DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]...
`SYSTEM` specifies that you want to delete the variable from the
system variable pool.
`SHARED` specifies that you want to delete the variable from the
shared variable pool.
`HANDLE` indicates that you want to delete the variable from the
variable pool associated with the specified handle.
If options
`SYSTEM`, `SHARED`, and `HANDLE` are
not specified, the variable will be deleted from the variable pool associated
with the handle of the process that submitted the request unless the request
came from another machine, in which case the variable will be deleted from the
system variable pool.
`VAR` specifies the name of the variable you want to delete.
This command requires trust level 3.
All return codes from DELETE are documented in
[Appendix A, "API Return Codes"](#HDRRETCODE).
If multiple variables are deleted via a single DELETE request and all variables were deleted successfully, the return code will be 0. If one or more variables were not deleted successfully, the return code will be set to the return code of the first variable that could not be deleted successfully. Note that all variables specified will be attempted to be deleted.
If successful, the result buffer will contain no data.
If the request failed, the result buffer's contents are based on whether
the
`VAR` option was specified once or multiple times as follows:
[Table 105. Definition of map class STAF/Service/Var/ErrorInfo]
Description: This map class represents information on whether
a variable was successfully deleted.
|Key Name||Display Name||Type||Format / Value|
|name||Name|<String>
|rc||RC|<String>
|
|
|result||Result|<String>
|
|
Notes:
If a variable is deleted successfully, its "RC" value will be '0' and its "Result" will be blank. If an error occurred deleting a variable, its "RC" value will contain the error return code and its "Result" may contain additional information about the error,
The purpose of the Zip service is to allow a test case to easily work with Zip archives.
By using of Zlib compression library, the Zip service can create, extract, delete and manage PKZip, WinZip and Jar compatible archives.
The Zip service supports the following features: create / extract PKZip,
WinZip, and Jar compatible archives; save / restore owner, group and permission information
on files and directories; delete file(s) from a Zip archive; list content of a
Zip archive, append file / directory to an existing Zip archive, etc.
SERVICE
<Name>LIBRARY STAFZip `<Name>` is the name by which the Zip service will be known on this
machine. The recommended name of the Zip service is "ZIP".
service ZIP library STAFZip
Extract all entries (or specified files and/or directories) from a Zip archive to a specified directory.
UNZIP ZIPFILE <Name> TODIRECTORY <Name> [FILE <Name>]... [DIRECTORY <Name>]... [RESTOREPERMISSION] [REPLACE]
`ZIPFILE` contains the fully qualified ZIP archive name.
`TODIRECTORY` contains the fully qualified output directory name.
`FILE` contains the fully qualified file name in the ZIP archive to be unzipped.
`DIRECTORY` contains the fully qualified directory name in the ZIP archive to be unzipped.
Subdirectories in the directory are recursively unzipped.
`RESTOREPERMISSION` indicates that the owner, group and permission
attributes of the file will be restored.
`REPLACE` indicates that the files/directories will be over written
they already exist in the specified output directory.
**Note: **If you specify multiple `FILE` and/or `DIRECTORY` options,
the files specified will be unzipped, followed by the directories specified.
If an error occurs while unzipping a file or directory, the unzip request will
not continue unzipping any remaining files/directories and will return an error.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
UNZIP also returns codes documented in [8.22.7, "Zip Error Code Reference"](#HDRZIPERR).
On a successful return, the result buffer will contain no data on return from a UNZIP command.
**Syntax:** `UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY D:/mydata/`
**Syntax:** `UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY /usr/lpp/mydata/ FILE myjava/Hello.java RESTOREPERMISSION REPLACE`
**Syntax:** `UNZIP ZIPFILE C:/temp/STAXV302.zip TODIRECTORY {STAF/Config/STAFRoot}/services DIRECTORY stax/docs`
**Syntax:** `UNZIP ZIPFILE C:/temp/STAXV302.zip TODIRECTORY C:/STAF/services FILE stax/STAX.jar FILE stax/STAFEvent.jar DIRECTORY stax/libraries DIRECTORY stax/samples REPLACE`
ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] > [RELATIVETO <Directory>]or
ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] > [RELATIVETO <Directory>]
An
`ADD` request performs the same function as a `ZIP` request.
An `ADD` request is preferred. The `ZIP` request is deprecated
and will generate a trace message with a Deprecated tracepoint.
`ZIPFILE` contains the fully qualified name of a Zip archive file.
If the Zip archive file does not exist, it will be created, but the directory
path specified for it must already exist.
`FILE` contains the fully qualified file name you want to add into
the ZIP archive.
`DIRECTORY` contains the fully qualified directory name you want to
add 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"](#HDRRETCODE),
Zip also returns codes documented in [8.22.7, "Zip Error Code Reference"](#HDRZIPERR).
On a successful return, the result buffer will contain no data on return from a ZIP command.
**Syntax:** `ADD ZIPFILE D:/myzip.zip FILE C:/file.txt`
**Syntax:** `ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RELATIVETO /opt`
**Syntax:** `ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RECURSE RELATIVETO /opt`
DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
`ZIPFILE` contains the fully qualified ZIP archive name.
`FILE` contains the fully qualified file name to be deleted from the zip archive.
`CONFIRM` confirms you really want to delete the file from zip
archive.
This command requires trust level 4.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
Delete also returns codes documented in [8.22.7, "Zip Error Code Reference"](#HDRZIPERR).
On a successful return, the result buffer will contain no data on return from a DELETE command.
**Syntax:** `DELETE ZIPFILE D:/myzip.zip FILE myjava/Hello.java CONFIRM`
**Syntax:** `DELETE ZIPFILE /opt/myzip.zip FILE myjava/Hello.java FILE bin/run CONFIRM`
LIST ZIPFILE <Name>
`ZIPFILE` contains the fully qualified ZIP archive name.
This command requires trust level 3.
In addition to the return codes documented in
[Appendix A, "API Return Codes"](#HDRRETCODE),
LIST also returns codes documented in [8.22.7, "Zip Error Code Reference"](#HDRZIPERR)
On successful return, the result buffer will contain a marshalled
`<List> of <Map:STAF/Service/Zip/ZipInfo>` representing
content of the Zip archive. The map is defined as follows:
[Table 106. Definition of map class STAF/Service/Zip/ZipInfo]
Description: This map class represents an entry in Zip archive.
|Key Name||Display Name||Type||Format / Value|
|length||Length|<String>
|
|
|method||Method|<String>
|
|
|size||Size|<String>
|
|
|ratio||Ratio|<String>
|
|
|date||Date|<String>
|
|
|time||Time|<String>
|
|
|crc-32||CRC-32|<String>
|
|
|name||Name|<String>
|
|
Notes:
**Syntax:** `LIST ZIPFILE /usr/local/staf/services/STAXV301.zip`
**Results:** If the request is submitted from the
command line, the result, in table format, could look like:
Length Method Size Ratio Date Time CRC-32 Name ------- ------ ------- ----- -------- ----- -------- -------------------------- 0 Stored 0 0% 07-28-05 03:44 00000000 stax/ 0 Stored 0 0% 07-28-05 03:44 00000000 stax/docs/ 42748 Defl:N 13022 30% 07-28-05 03:44 f72affac stax/docs/History 86379 Defl:N 58971 68% 07-28-05 03:44 aeb290ca stax/docs/STAXDoc.pdf 926998 Defl:N 711411 76% 07-28-05 03:44 92496663 stax/docs/staxgs.pdf 921917 Defl:N 653042 70% 07-28-05 03:44 e4e64a11 stax/docs/staxug.pdf 0 Stored 0 0% 07-28-05 03:44 00000000 stax/ext/ 2029 Defl:N 572 28% 07-28-05 03:44 b9c0e581 stax/ext/stax-extensions.d td 0 Stored 0 0% 07-28-05 03:44 00000000 stax/libraries/ 57120 Defl:N 10726 18% 07-28-05 03:44 03e1c2d9 stax/libraries/STAXUtil.ht ml 77766 Defl:N 14909 19% 07-28-05 03:44 2cfa2ce7 stax/libraries/STAXUtil.xm l 2118 Defl:N 938 44% 07-28-05 03:44 f15cb878 stax/readme.1st 0 Stored 0 0% 07-28-05 03:44 00000000 stax/samples/ 5274 Defl:N 826 15% 07-28-05 03:44 277d4fb7 stax/samples/FunctionList. xsl 10528 Defl:N 2830 26% 07-28-05 03:44 b6dfa3ee stax/samples/sample1.xml 30281 Defl:N 27699 91% 07-28-05 03:44 837e1ab4 stax/STAFEvent.jar 2607441 Defl:N 2541497 97% 07-28-05 03:44 0b9b43aa stax/STAX.jar 25619 Defl:N 22208 86% 07-28-05 03:44 8104f5b9 stax/STAXDoc.jar 189539 Defl:N 177191 93% 07-28-05 03:44 bd0c4288 stax/STAXMon.jar
In addition to the common STAF return codes (see
[Appendix A, "API Return Codes"](#HDRRETCODE) for
additional information), the following Zip return codes are defined:
[Table 107. Zip Service Return Codes]
|Error Code||Meaning||Comment|
4001
|General zip error||A general error occurred, additional error message can be found in result buffer.|
4002
|Not enough memory||There is not enough memory in the system.|
4003
|Change file size error: <file>||Error changing the file size.|
4004
|Error creating directory: <dir>||Error creating directory in the file system.|
4005
|Invalid zip file: <file>||Invalid zip file format.|
4006
|Bad CRC||Bad CRC in the zip archive.|
4007
|Invalid owner group||Invalid owner / group on the system when restore permission.|
4008
|Invalid file mode||Invalid file mode.|
Some utilities are provided to assist in viewing and formatting STAF
log files and the JVM Log files.
This Java class can be run as an application via the command line or can be run via another Java program.
[
For more information on how to use the STAFLogViewer class, see section
"3.6.1 Class STAFLogViewer" in the
] [STAF Java User's Guide](http://staf.sourceforge.net/current/STAFJava.htm#Header_STAFLogViewer).
The
`STAFJVMLogViewer` class provides a Java GUI that can display a
JVM Log for any STAF Java service that is currently registered.
Each Java service that is registered with STAF runs in a JVM (Java Virtual Machine).
A JVM Log is a text log file that is associated with each JVM created by STAF.
Note that more than one Java service may use the same JVM (and thus share the same
JVM Log file) depending on the options used when registering the service.
Section [4.4, "Service Registration"](#HDRSERVICEREGCFG) provides more information on registering
STAF Java services using the JSTAF library.
A JVM Log file contains JVM start information such as the date/time when the JVM
was created, the JVM executable, and the J2 options used to start the JVM.
It also any other information logged by the JVM. This includes any
errors that may have occurred while the JVM was running and any debug information
output by a Java service. Also, the JVM Log for the STAX service contains the
output from any print statements that are used within a
`<script>` element
in a STAX xml job file which is useful when debugging Python code contained in
a `<script>` element. When a problem occurs with a STAF Java service,
you should always check it's JVM Log as it may contain information to help debug
the problem.
STAF stores JVM Log files in the
`{STAF/DataDir}/lang/java/jvm/<JVMName>`
directory. STAF retains a configurable number of JVM Logs (five by default) for each
JVM. The current JVM log file is named `JVMLog.1` and older saved JVM log
files, if any, are named `JVMLog.2` to `JVMLog.<MAXLOGS>`.
When a JVM is started, if the size of the `JVMLog.1` file exceeds the
maximum configurable size (1M by default), the `JVMLog.1` file is copied
to `JVMLog.2` and so on for any older JVM Logs, and a new `JVMLog.1`
file will be created.
When using the
`STAFJVMLogViewer`, you can specify the machine where the
STAF JVM log resides (e.g. where the Java service is registered) and you can
specify/select the name of the STAF service whose JVM Log you want to display.
This Java class submits requests to STAF, so STAF has to be running.
This Java class can be run as an application via the command line or can be
run via another Java program.
Note that the STAX Monitor Java application uses the
`STAFJVMLogViewer`
class to display the JVM log for the STAX service and for other services.
[
For more information on how to use the STAFJVMLogViewer class, see section
"3.6.2 Class STAFJVMLogViewer" in the
] [STAF Java User's Guide](http://staf.sourceforge.net/current/STAFJava.htm#Header_STAFJVMLogViewer).
This Java class can be run as an application via the command line or can be run via another Java program. When run as an application, it submits the specified Log query request to query a STAF log on any machine currently running STAF and then formats the output as either html or text. Or, when run via a Java program that has already submitted a LOG QUERY request, you can use the STAFLogFormatter class to format the log query result as either html or text. You can specify various options including whether you want the formatted output written to a file.
[
For more detailed information on using the STAFLogFormatter class,
see section "3.6.3 Class STAFLogFormatter" in the
] [STAF Java User's Guide](http://staf.sourceforge.net/current/STAFJava.htm#Header_STAFLogFormatter).
FmtLog FORMAT LOGFILE <Logfile> NEWFILE <Newfile> [LEVELBITSTRING] [FIELDSEP <Char>]
`LOGFILE` contains the name of the log you want to read. This must
be the complete path and filename.
`NEWFILE` contains the name of the output file where you want to
write the results. This must be the complete path and filename.
`LEVELBITSTRING` displays the selected records with the level
displayed as the 32 byte binary bit string, e.g.
00000000000000000000000000000001 instead of the standard level text e.g. Error.
See [8.9.11, "Logging Levels Reference"](#HDRLOGLEV) for a complete list of logging levels.
`FIELDSEP` is the character that separates each record field, the
default is "|".
C:\STAF\data\STAF\service\log\ <-Global Top C:\STAF\data\STAF\service\log\GLOBAL\ <--Global Dir STRESSTST.LOG <---Global Log SUITE100.LOG <---Global Log C:\STAF\data\STAF\service\log\MACHINE\ <-Machine Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\ <--clieot1 Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\GLOBAL\ <---client1 Global Top TESTLOG1.LOG <----client1 Global Logs C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\ <--client1 Handle Top C:\STAF\data\STAF\service\log\MACHINE\client1.company.com\HANDLE\100\ <---Handle 100 Top TESTLOG2.LOG <---Handle 100 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\ <--AUTOMATE Top C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\GLOBAL\ <---AUTOMATE Global Top AUTOGLOB.LOG <----AUTOMATE Global Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\ <---AUTOMATE Handle Top C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\42\ <----Handle 42 Top HANDLOG1.log <-----Handle 42 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\43\ <----Handle 43 Top HANDLOG2.log <-----Handle 43 Log HANDLOG3.log <-----Handle 43 Log C:\STAF\data\STAF\service\log\MACHINE\AUTOMATE\HANDLE\44\ <----Handle 44 Top HANDLOG4.log <-----Handle 44 Log C:\STAF\data\STAF\service\log\MACHINE\automate\HANDLE\45\ <----Handle 45 Top HANDLOG5.log <-----Handle 45 Log
Date-Time|Machine|Handle|Handle Name|User|Endpoint|Level|Message
C:\>FmtLog FORMAT LOGFILE C:/STAF/data/STAF/service/LOG/MACHINE/client1/GLOBAL/STAX_Job_4_User.log NEWFILE C:/myLog.txt Formatted 10 record(s) to C:/myLog.txt
The contents of C:/myLog.txt could look like the following:
20041029-15:42:03|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|TestMachines=['client1.company.com'] 20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|JobHandle=78 20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAXMachineNickname=client1 20041029-15:42:04|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAXMachine=client1.company.com 20041029-15:42:08|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|Test machine: client1.company.com OS type: Win2000 STAFRoot: C:\STAF 20041029-15:42:08|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing started on machine client1.company.com 20041029-15:44:28|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing completed on machine client1.company.com 20041029-15:44:28|client1.company.com|78|STAX/Job/4|none://anonymous|tcp://client1.company.com|Info|STAF Testing completed in 146 seconds 20041104-18:27:07|client1.company.com|50|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT 20041105-11:22:51|client1.company.com|89|STAX/Job/4|none://anonymous|local://local|Info|STAF local PROCESS START SHELL COMMAND "dir C:d*." RETURNSTDOUT STDERRTOSTDOUT WAIT
**Note: **In some shell environments, return codes above 255 may be returned modulo
256. This can, in particular, cause service return codes (which range from
4000 upward) to be mistaken for (possibly) non-existent common STAF return
codes. For example, if a service returned the return code 4010, this might
appear to be the return code 170 (4010 modulo 256) in a shell
environment.
[Table 108. STAF API Return Codes]
|Error Code||Meaning||Comment|
0
|No error||
|
1
|Invalid API||This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors.|
2
|Unknown Service||You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service.|
3
|Invalid Handle||You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF.|
4
|Handle already exists||This indicates that you are trying to register a process with one name when
that process has already been registered with a different name. If you
register the same process multiple times, ensure that you use the same name
on each registration call.
|
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.
|
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.
|
10
|Base OS Error||This indicates that a base operating system error was encountered.
|
11
|Process Already Complete||You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification.|
12
|Process Not Complete||You are trying to free process information for a process that is still executing.|
13
|Variable Does Not Exist||You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call.|
14
|UnResolvable String||You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions.|
15
|Invalid Resolve String||The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces.|
16
|No Path To Endpoint||This indicates that STAFProc was not able to submit the request to
the requested endpoint (i.e. target machine). This error usually indicates
one or more of the following:
|
17
|File Open Error||This indicates that there was an error opening the requested file.
Some possible explanations are that the file/path does not exist, contains
invalid characters, or is locked.
|
18
|File Read Error||This indicates that there was an error while trying to read data from a file.
|
19
|File Write Error||This indicates that there was an error while trying to write data to a file.
|
20
|File Delete Error||This indicates that there was an error while trying to delete a file or
directory.
|
21
|STAF Not Running||This indicates that STAFProc is not running on the local machine with the
same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix machine).
|
22
|Communication Error||This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request. This can also indicate that the requested endpoint is not valid (e.g. it has an invalid network interface and port combination such as a non-secure tcp interface with the port for a secure ssl interface).|
23
|Trustee Does Not Exist||You have requested to delete a trustee, and the trustee does not exist. Verify that you have specified the correct trustee.|
24
|Invalid Trust Level||You have attempted to set a machine or default trust level to an invalid level. The valid trust levels are from zero to five.|
25
|Insufficient Trust Level||You have submitted a request for which you do not have the required
trust level to perform the request.
|
26
|STAF Registration Error||This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured.|
27
|Service Configuration Error||This indicates an error with the configuration of an external service. One
possible explanation is that the LIBRARY you specified when configuring the
service does not exist. Or, if you specified the EXECUTE option, verify that
the executable exists and has the execute permission. Or, if you specified the
PARMS option, verify that all of the service configuration are valid. Consult
the appropriate documentation for the service to verify whether you have
configured the service properly, or contact the service provider.
|
28
|Queue Full||This indicates that you are trying to queue a message to a handle's queue, but the queue is full. The maximum queue size can be increased by using the MAXQUEUESIZE statement in the STAF Configuration File.|
29
|No Queue Element||This indicates that you tried to GET or PEEK a particular element in a queue, but no such element exists, or the queue is empty.|
30
|Notifiee Does Not Exist||This indicates that you are trying to remove a message notification for a machine/process/priority combination which does not exist in the notification list.|
31
|Invalid API Level||This indicates that a process has tried to call an invalid level of an internal STAF API. If this error occurs, report it to the authors.|
32
|Service Not Unregisterable||This indicates that you are trying to unregister a service that is not unregisterable. Note that internal services are not unregisterable.|
33
|Service Not Available||This indicates that the service you requested is not currently able to accept requests. The service may be in the process of initializing or terminating.|
34
|Semaphore Does Not Exist||This indicates that you are trying to release, query, or delete a semaphore that does not exist.|
35
|Not Semaphore Owner||This indicates that you are trying to release a semaphore for which your process is not the current owner.|
36
|Semaphore Has Pending Requests||This indicates that you are trying to delete either a mutex semaphore that is currently owned or an event semaphore that has waiting processes.|
37
|Timeout||This indicates that you submitted a request with a timeout value and the request did not complete within the requested time.|
38
|Java Error||This indicates an error performing a Java native method call. A description of the error will be returned in the result passed back from the submit call.|
39
|Converter Error||This indicates an error performing a codepage conversion. The most likely cause of this error is that STAF was not properly installed. However, it is possible that you are currently using a codepage that was not present or specified during STAF installation.|
40
|Move Error||This indicates that there was an error while trying to move a file or
directory.
|
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.
|
48
|Does Not Exist||This indicates that the item you specified does not exist.
|
49
|Already Exists||This indicates that the item you specified already exists.
|
50
|Directory Not Empty||This indicates that you have tried to delete a directory, but that directory
is not empty.
|
51
|Directory Copy Error||This indicates that you have tried to copy a directory, but errors occurred
during the copy.
|
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.
|
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.
|
57
|Create Thread Error||This indicates that a problem occurred creating a new thread. One possible
explanation is that there's not enough memory available to create a new
thread.
|
58
|Maximum Size Exceeded||This indicates that the size of a file exceeded the maximum size allowed
(e.g. per the MAXRETURNFILESIZE operational parameter or per the
MAXRETURNFILESIZE setting for the STAX service).
A maximum file size is usually set to prevent the creation of result strings
that require more memory than is available which can cause errors or crashes.
|
59
|Maximum Handles Exceeded||This indicates that a new handle could not be created/registered because the maximum number of active handles allowed by STAF has been exceeded. You need to delete one or more handles that are no longer being used. The Handle service's LIST HANDLES SUMMARY request provides information on the maximum number of active STAF handles and this may be helpful in better understanding why this error occurred.|
60
|Not Pending Requester||You cannot cancel a pending request your handle did not submit unless you specify the FORCE option.|
4000+
|Service Defined||Error codes of 4000 and beyond are service specific error codes. Either see the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.|[Table 109. STAF Service Command Reference]
|Command||Syntax|
CONFIG
|Provides a way to save the current STAF configuration to a file,
reflecting any changes made since STAFProc was started
|
SAVE [FILE <Name>] [VARS <Current | Startup>] HELP
DELAY
|Delay (or sleep) for a specified amount of time.
|
DELAY <Number>[s|m|h|d|w] HELP
DIAG
|Allows diagnostics to be recorded, listed, enabled, disabled, and reset.
|
RECORD TRIGGER <Trigger> SOURCE <Source> LIST < [TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES] [SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE] > | SETTINGS RESET FORCE ENABLE DISABLE HELP
ECHO
|Echo a return string from other STAF clients.
|
ECHO <Message> HELP
FS
|Allows you to manipulate files and directories and get information about file system entries.
|
COPY FILE <Name> [TOFILE <Name> | TODIRECTORY <Name>] [TOMACHINE <Machine>] [TEXT [FORMAT <Format>]] [FAILIFEXISTS | FAILIFNEW] COPY DIRECTORY <Name> [TODIRECTORY <Name>] [TOMACHINE <Machine>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] [TEXTEXT <Pattern>... [FORMAT <Format>]] [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]] [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW] MOVE FILE <Name> <TOFILE <Name> | TODIRECTORY <Name>> MOVE DIRECTORY <Name> TODIRECTORY <Name> GET FILE <Name> [[TEXT | BINARY] [FORMAT <Format>]] GET ENTRY <Name> <TYPE | SIZE | MODTIME | LINKTARGET | CHECKSUM [<Algorithm>]> QUERY ENTRY <Name> CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS] LIST DIRECTORY <Name> [RECURSE] [LONG [DETAILS] | SUMMARY] [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME] LIST COPYREQUESTS [LONG] [INBOUND] [OUTBOUND] [FILE [[BINARY] [TEXT]]] [DIRECTORY] LIST SETTINGS DELETE ENTRY <Name> CONFIRM [RECURSE] [IGNOREERRORS] [ CHILDREN [TYPE <Types>] [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE] ] SET STRICTFSCOPYTRUST <Enabled | Disabled> HELP
HANDLE
|Allows you to query information on various process handles and to manage static handles.
|
CREATE HANDLE NAME <Handle Name> DELETE HANDLE <Number> QUERY HANDLE <Handle> LIST [ HANDLES <[NAME <Handle Name>] [LONG] [PENDING] [REGISTERED] [INPROCESS] [STATIC]> | [SUMMARY] ] LIST NOTIFICATIONS [HANDLE <Handle> | MACHINE <Machine>] [LONG] AUTHENTICATE USER <User Identifier> CREDENTIALS <Credentials> [AUTHENTICATOR <Authenticator Name>] UNAUTHENTICATE HELP
HELP
|List and query STAF return codes. Allows services to register their own
return codes.
|
REGISTER SERVICE <Name> ERROR <Number> INFO <String> DESCRIPTION <String> UNREGISTER SERVICE <Name> ERROR <Number> [SERVICE <Name>] ERROR <Number> LIST SERVICES | [SERVICE <Name>] ERRORS HELP
LIFECYCLE
|Allows STAF service requests to be submitted automatically when STAFProc starts
up or shuts down. Also, allows managing registration of the STAF service requests
to be submitted.
|
REGISTER PHASE <Startup | Shutdown> MACHINE <Machine> SERVICE <Service> REQUEST <Request> [ONCE] [PRIORITY <Priority>] [DESCRIPTION <Description>] UNREGISTER ID <Registration ID> UPDATE ID <Registration ID> [PRIORITY <Priority>] [ONCE <True | False>] [MACHINE <Machine>] [SERVICE <Service>] [REQUEST <Request>] [PHASE <Startup | Shutdown>] [DESCRIPTION <Description>] LIST [PHASE <Startup | Shutdown>] [LONG] QUERY ID <Registration ID> TRIGGER <ID <Registration ID> | PHASE <Startup | Shutdown>> CONFIRM ENABLE ID <Registration ID> DISABLE ID <Registration ID> HELP
LOG
|Allows for robust data-logging and log file querying and manipulation.
|
LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level> MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE] QUERY <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]... [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]... [CONTAINS <String>]... [CSCONTAINS <String>]... [STARTSWITH <String>]... [CSSTARTSWITH <String>]... [FROM <Timestamp> | AFTER <Timestamp>] [BEFORE <Timestamp> | TO <Timestamp>] [FROMRECORD <Num>] [TORECORD <Num>] [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS | LONG] [LEVELBITSTRING] LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLE <Handle> | HANDLES] | SETTINGS DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> CONFIRM PURGE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> CONFIRM | CONFIRMALL [LEVELMASK <Mask>] [QMACHINE <Machine>]... [QHANDLE <Handle>]... [NAME <Name>]... [USER <User>]... [ENDPOINT <Endpoint>]... [CONTAINS <String>]... [CSCONTAINS <String>]... [STARTSWITH <String>]... [CSSTARTSWITH <String>]... [FROM <Timestamp> | AFTER <Timestamp>] [BEFORE <Timestamp> | TO <Timestamp>] [FROMRECORD <Num>] [TORECORD <Num>] [FIRST <Num> | LAST <Num>] SET [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR] [RESOLVEMESSAGE | NORESOLVEMESSAGE] VERSION HELP
MISC
|Provides miscellaneous services such as VERSION, WHOAMI, and WHOAREYOU
information, allows for listing and querying enabled interfaces, allows
you to set operational parameters for STAF and show their settings,
and allows you to list and purge the endpoint cache used by automatic
interface cycling.
|
VERSION WHOAMI WHOAREYOU LIST INTERFACES | SETTINGS | ENDPOINTCACHE QUERY INTERFACE <Name> SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>[s|m|h|d|w]] [MAXQUEUESIZE <Number>] [HANDLEGCINTERVAL <Number>[s|m|h|d]] [INTERFACECYCLING <Enabled | Disabled>] [DEFAULTINTERFACE <Name>] [DEFAULTAUTHENTICATOR <Name>] [RESULTCOMPATIBILITYMODE <Verbose | None>] PURGE ENDPOINTCACHE <ENDPOINT <Endpoint>... | CONFIRM> HELP
MONITOR
|Allows test cases the ability to log and query status messages.
|
LOG MESSAGE <Message> [NAME <Name>] [RESOLVEMESSAGE | NORESOLVEMESSAGE] QUERY MACHINE <Machine> < HANDLE <Handle> | NAME <Name> > LIST <MACHINES | MACHINE <Machine> [NAMES] | SETTINGS> DELETE [BEFORE <Timestamp>] CONFIRM SET [RESOLVEMESSAGE | NORESOLVEMESSAGE] [OLDRETURNCODES | NEWRETURNCODES] [MAXRECORDSIZE <Size>] [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR] VERSION HELP
PING
|Allows you to ping other STAF clients.
|
PING [MACHINE <Machine>] HELP
PROCESS
|Allows you to start, stop, and manage processes.
|
START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>] [VAR <Variable>=<Value>]... [ENV <Variable>=<Value>]... [USEPROCESSVARS] [WORKLOAD <Name>] [TITLE <Title>] [WAIT [<Number>[s|m|h|d|w]] | ASYNC] [STOPUSING <Method>] [STATICHANDLENAME <Name>] [NEWCONSOLE | SAMECONSOLE] [FOCUS <Background | Foreground | Minimized>] [USERNAME <User name> [PASSWORD <Password>]] [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>] [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT] [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]... [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>] [MACHINE <Machine>] [PRIORITY <Priority>] [KEY <Key>]] STOP <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>] KILL PID <Pid> CONFIRM [USING <Method>] LIST [HANDLES] [RUNNING] [COMPLETED] [WORKLOAD <Name>] [LONG] LIST SETTINGS QUERY HANDLE <Handle>> FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>> NOTIFY REGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>] [MACHINE <Machine>] [PRIORITY <Priority>] NOTIFY UNREGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>] [MACHINE <Machine>] [PRIORITY <Priority>] NOTIFY LIST ONENDOFHANDLE <Handle> SET [DEFAULTSTOPUSING <Method>] [DEFAULTCONSOLE <New | Same>] [DEFAULTFOCUS <Background | Foreground | Minimized>] [PROCESSAUTHMODE <Auth Mode>] [DEFAULTAUTHUSERNAME <User Name>] [DEFAULTAUTHPASSWORD <Password>] [DEFAULTAUTHDISABLEDACTION <Error | Ignore>] [DEFAULTSHELL <Shell>] [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>] HELP
QUEUE
|Allows you to manipulate and manage queues.
|
QUEUE MESSAGE <Message> [HANDLE <Handle>] | [NAME <Name>] [PRIORITY <Priority>] [TYPE <Type>] GET [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]... [FIRST <Number> | ALL] [WAIT [<Number>[s|m|h|d|w]]] PEEK [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]... [FIRST <Number> | ALL] [WAIT [<Number>[s|m|h|d|w]]] DELETE [PRIORITY <Priority>]... [MACHINE <Endpoint>]... [NAME <Name>]... [HANDLE <Handle>]... [USER <User>]... [TYPE <Type>]... [CONTAINS <String>]... [ICONTAINS <String>]... LIST [HANDLE <Handle>] HELP
RESPOOL
|Allows you to manage exclusive access to entries within resource pools.
|
CREATE POOL <PoolName> DESCRIPTION <Pooltext> DELETE POOL <PoolName> CONFIRM [FORCE] QUERY POOL <PoolName> REQUEST POOL <PoolName> [FIRST | RANDOM | ENTRY <Value> [RELEASE]] [PRIORITY <Number>] [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>] RELEASE POOL <PoolName> ENTRY <Value> [FORCE] CANCEL POOL <PoolName> [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]] [ENTRY <Entry>] [PRIORITY <Number>] [FIRST | LAST] ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE] LIST [POOLS | SETTINGS] VERSION HELP
SEM
|Allows you to manipulate and manage mutex and event semaphores.
|
REQUEST MUTEX <Name> [TIMEOUT <Number>[s|m|h|d|w]] [GARBAGECOLLECT <Yes | No>] RELEASE MUTEX <Name> [FORCE] CANCEL MUTEX <Name> [FORCE [MACHINE <Machine>] [HANDLE <Handle #> | NAME <Handle Name>]] [FIRST | LAST] POST EVENT <Name> RESET EVENT <Name> PULSE EVENT <Name> WAIT EVENT <Name> [TIMEOUT <Number>[s|m|h|d|w]] DELETE MUTEX <Name> | EVENT <Name> QUERY MUTEX <Name> | EVENT <Name> LIST MUTEX | EVENT HELP
SERVICE
|Allows you to manage STAF services and requests.
|
LIST [ SERVICES | SERVICELOADERS | AUTHENTICATORS | REQUESTS <[PENDING] [COMPLETE] [LONG]> | [SUMMARY] ] QUERY SERVICE <Service Name> | SERVICELOADER <ServiceLoader Name> | AUTHENTICATOR <Authenticator Name> | REQUEST <Request Number> ADD SERVICE <Service Name> LIBRARY <Library Name> [EXECUTE <Executable>] [OPTION <Name=[=Value]>]... [PARMS <Parameters>] REMOVE SERVICE <Service Name> FREE REQUEST <Request Number> [FORCE] HELP
SHUTDOWN
|Allows you to manage the STAFProc daemon process.
|
SHUTDOWN NOTIFY REGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>] [PRIORITY <Priority>] NOTIFY UNREGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>] [PRIORITY <Priority>] NOTIFY LIST HELP
TRACE
|Allows you to turn tracing on and off at the service and tracepoint level.
|
ENABLE ALL [ TRACEPOINTS | SERVICES ] ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... ENABLE SERVICE <Service> [SERVICE <Service>]... DISABLE ALL [ TRACEPOINTS | SERVICES ] DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list> DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]... DISABLE SERVICE <Service> [SERVICE <Service>]... SET DESTINATION TO < [STDOUT | STDERR] [FILE <File name> [APPEND]] > SET DEFAULTSERVICESTATE < Enabled | Disabled > LIST [SETTINGS] PURGE HELP
TRUST
|Allows you to manipulate and manage trust levels (security).
|
SET < MACHINE <Machine> | USER <User> | DEFAULT > LEVEL <Level> GET MACHINE <Machine> [USER <User>] DELETE MACHINE <Machine> | USER <User> LIST HELP
VAR
|Allows you to manipulate and manage system, shared and process specific variable pools.
|
SET [SYSTEM | SHARED | HANDLE <Handle>] [FAILIFEXISTS] VAR <Name=Value> [VAR <Name=Value>]... GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]... LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> | REQUEST [<Number>]] STRING <String> [STRING <String>]... HELP
ZIP
|Allows for unzipping, listing, and adding/deleting entries in Zip archives which are
PKZip, WinZip and Jar compatible.
|
UNZIP ZIPFILE <Name> TODIRECTORY <Name> [FILE <Name>]... [DIRECTORY <Name>]... [RESTOREPERMISSION] [REPLACE] ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] > [RELATIVETO <Directory>] DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM LIST ZIPFILE <Name> VERSION HELP
|Name||Description||Comments|
/*****************************************************************************/ /* Software Testing Automation Framework (STAF) */ /* (C) Copyright IBM Corp. 2001 */ /* */ /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ /*****************************************************************************/ //=========================================================================== // JPing - A multi-threaded STAF PING test //=========================================================================== // Accepts: Where to PING // Optionally, the number of threads to use (default = 5) // Optionally, the number of loops per thread (default = 10000) // Optionally, the display modulus (default = 250) // // Returns: 0 , on success // >0, if an error is encountered //=========================================================================== // Date Who Comment // ---------- ------------ ------------------------------------------ // 04/25/1998 C. Rankin File Created //=========================================================================== import com.ibm.staf.*; import java.util.Date; import java.util.Calendar; import java.text.DateFormat; public class JPing implements Runnable { // Constructor public JPing(int numLoops, int displayModulus, int myThreadNum) { loopCount = numLoops; modulus = displayModulus; threadNum = myThreadNum; errors = 0; } // This is the main command line entry point public static void main(String [] argv) { // Verify the command line arguments if ((argv.length < 1) || (argv.length > 4)) { System.out.println(); System.out.println("Usage: java JPing <Where> [# Threads] " + "[# Loops per thread] [Display Modulus]"); System.out.println(); System.out.println("Defaults:"); System.out.println(); System.out.println(" # Threads = 5"); System.out.println(" # Loops per thread = 10000"); System.out.println(" Display Modulus = 250"); System.out.println(); System.out.println("Examples:"); System.out.println(); System.out.println("java JPing local"); System.out.println("java JPing SomeServer 3 1000 100"); System.exit(1); } // Register with STAF try { handle = new STAFHandle("Java_Ping_Test"); } catch (STAFException e) { System.out.println("Error registering with STAF, RC: " + e.rc); System.exit(1); } // Initialize variables timeFormatter = DateFormat.getTimeInstance(DateFormat.MEDIUM); where = argv[0]; int numThreads = 5; int numLoops = 10000; int displayModulus = 250; if (argv.length > 1) numThreads = Integer.parseInt(argv[1]); if (argv.length > 2) numLoops = Integer.parseInt(argv[2]); if (argv.length > 3) displayModulus = Integer.parseInt(argv[3]); JPing [] pingers = new JPing[numThreads]; Thread [] threads = new Thread[numThreads]; System.out.println("(0)" + timeFormatter.format(new Date()) + " - Started"); long startSecs = (new Date()).getTime(); // Start the threads for(int i = 0; i < numThreads; ++i) { pingers[i] = new JPing(numLoops, displayModulus, i + 1); threads[i] = new Thread(pingers[i]); threads[i].start(); } // Wait for all the threads to finish for(int i = 0; i < numThreads; ++i) { try { threads[i].join(); } catch (Exception e) { System.out.println("Exception: " + e); System.out.println(e.getMessage()); } } // Output final pings/sec long stopSecs = (new Date()).getTime(); System.out.println("(0)" + timeFormatter.format(new Date()) + " - Ended"); System.out.println("Average: " + ((numLoops * numThreads * 1000) / (stopSecs - startSecs)) + " pings/sec"); // Unregister with STAF try { handle.unRegister(); } catch (STAFException e) { System.out.println("Error unregistering with STAF, RC: " + e.rc); System.exit(1); } } // This is the method called when each thread starts public void run() { for(int i = 1; i <= loopCount; ++i) { STAFResult result = handle.submit2(where, "PING", "PING"); // If we get a non-zero return code, or a response of something // other than "PONG", display an error if (result.rc != 0) { System.out.println("(" + threadNum + ")" + timeFormatter.format(new Date()) + " - Loop #" + i + ", Error #" + ++errors + ", RC: " + result.rc); } else if (result.result.compareTo("PONG") != 0) { System.out.println("(" + threadNum + ")" + timeFormatter.format(new Date()) + " - Loop #" + i + ", Error #" + ++errors + ", RESULT = " + result.result); } // If we are at our display modulus display a status message if ((i % modulus) == 0) { System.out.println("(" + threadNum + ")" + timeFormatter.format(new Date()) + " - Ended Loop #" + i + ", Errors = " + errors); } } } private static STAFHandle handle; private static String where; private static DateFormat timeFormatter; private int loopCount; private int modulus; private int threadNum; private int errors; }
/*****************************************************************************/ /* Software Testing Automation Framework (STAF) */ /* (C) Copyright IBM Corp. 2001 */ /* */ /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ /*****************************************************************************/ /*********************************************************************/ /* Sample1.cmd - Rexx sample program using STAF */ /*********************************************************************/ /* This sample loads the STAF Functions, registers to STAF, queries */ /* a global variable from STAF, inititates a synchronous process */ /* which is a chkdsk of the boot drive, then unregisters. */ /* */ /* Returns: 0, on success */ /* >0, if an error is encountered */ /*********************************************************************/ /* Date Who Comment */ /* ---------- ------------ --------------------------------------- */ /* 02/01/1998 D. Randall File Created */ /*********************************************************************/ SIGNAL ON HALT NAME STAFAbort /* Load STAF functions */ call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs" call STAFLoadFuncs /* Register to STAF */ call STAFRegister "STAF_REXX_Sample1" if RESULT \= 0 then do say "Error registering to STAF:" RESULT RETURN RESULT end /* Query STAF for a variable */ STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/BootDrive}") if STAFRC = 0 then bootdrive = STAFResult else do say "Unable to determine boot drive!" call STAFUnRegister RETURN STAFRC end /* Build the process start request with a work load name of STAFSample */ request = "START WAIT COMMAND chkdsk.com WORKLOAD STAFSample" /* Pass the boot drive parameter to chkdsk */ parms = "PARMS" bootdrive /* Query STAF for a variable */ STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/Sep/File}") if STAFRC = 0 then filesep = STAFResult else do say "Unable to determine file seperator!" call STAFUnRegister RETURN STAFRC end /* Set the working directory */ workdir = "WORKDIR" bootdrive||filesep /* Submit the request to STAF */ say "Attempting to CHKDSK bootdrive" bootdrive STAFRC = STAFSubmit("local", "process", request parms workdir) say "Submit Return Code="STAFRC ", Result="STAFResult /* Unregister */ call STAFUnRegister RETURN 0 /*********************************************************************/ /* STAFAbort - If user aborts, make sure STAF unregister occurs. */ /*********************************************************************/ STAFAbort: call STAFUnRegister EXIT 1
/*****************************************************************************/ /* Software Testing Automation Framework (STAF) */ /* (C) Copyright IBM Corp. 2001 */ /* */ /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ /*****************************************************************************/ /*********************************************************************/ /* Sample2.cmd - Rexx sample program using STAF */ /*********************************************************************/ /* This sample loads REXX and STAF Functions, registers to STAF, */ /* inititates an asynchronous PMSEEK process, queries, stops, */ /* queries again then frees the process, then unregisters. */ /* */ /* Note that this example explictly uses STAFHandle in all calls */ /* and additional error checking is needed. */ /* */ /* Returns: 0, on success */ /* >0, if an error is encountered */ /*********************************************************************/ /* Date Who Comment */ /* ---------- ------------ --------------------------------------- */ /* 02/02/1998 D. Randall File Created */ /*********************************************************************/ SIGNAL ON HALT NAME STAFAbort /* Load system functions */ call RxFuncAdd "SysLoadFuncs", "REXXUTIL", "SysLoadFuncs" call SysLoadFuncs /* Load STAF functions */ call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs" call STAFLoadFuncs /* Register Sample to STAF */ call STAFRegister "STAF_REXX_Sample2", "STAFHandle" if RESULT \= 0 then do say "Error registering to STAF:" RESULT RETURN RESULT end /* Set a global variable for start timestamp */ request = " GLOBAL SET Start="||DATE('s')||'-'||TIME() STAFRC = STAFSubmit(STAFHandle, "local", "VAR", request) /* Build the process start request with a work load name of STAFSample2 */ request = "START COMMAND pmseek.exe WORKLOAD STAFSample2" /* Submit the request to STAF */ STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request) if STAFRC = 0 then do PROCHandle = STAFResult STAFRC = STAFSubmit(STAFHandle, "local", "VAR", "LIST") say STAFResult say "Press <Enter> to continue" pull response request = "query handle" PROCHandle STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request) say STAFResult say "Press <Enter> to stop PMSEEK" pull response STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "STOP HANDLE" PROCHandle) call SysSleep 1 STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request) say STAFResult STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "FREE HANDLE"

Server: Apache/2.2.15 (CentOS)

Vary: Host

Via: 1.1 varnish