Software Testing Automation Framework (STAF) User's Guide
Version 3.3.0
26 Jun 2008
Appendix B. Service Command Reference
Appendix C. Samples Descriptions
Appendix D. Code Samples and Snipets
As its name indicates, STAF is a framework. It was designed to promote reuse and extensibility. It is intended to make software testing easier, and specifically to make it easier to automate software testing. This includes creating automated testcases, managing and automating the test environment, creating execution harnesses (i.e., applications which schedule and/or execute work on test systems), etc.
STAF externalizes its capabilities through services. A service provides a focused set of functionality, such as, Logging, Process Invocation, etc. STAFProc is the process that runs on a machine, called a STAF Client, which accepts requests and routes them to the appropriate service. These requests may come from the local machine or from another STAF Client. Thus, STAF works in a peer environment, where machines may make requests of services on other machines.
STAF was designed with the following points in mind.
STAF is supported on the following operating systems
A handle is a unique identifier, representing a given process. This handle is used when submitting requests to STAF. This handle, combined with the machine name, uniquely identifies a particular process in the STAF Environment. It is this combination of machine/handle that allows services to track requests from multiple processes on different machines.
In order to submit service requests to STAF, a process must have a handle. Thus, the first thing a process should do is register with STAF to obtain a handle. Other data tied to this handle is the following:
Before a process exits it should unregister with STAF to free up any resources used by that handle.
Note: Handle 1 is always allocated to the STAF Process itself. The name associated with this handle is STAF_Process.
If STAFProc is shutdown on a machine (or the machine is rebooted), STAF handles for that machine are deleted.
The SEM and RESPOOL services perform garbage collection for handles that have been deleted by default, unless you specified no garbage collection when requesting a mutex semaphore or resource pool entry. Performing garbage collection means that when a handle is deleted, any mutex semaphores or resource pool entries owned by the handle will be released and any pending requests submitted by the handle will be removed.
Services are what provide all the capability in STAF. Services may be internal services, in which case, the executable code for the service resides within STAFProc. Services may also be external services, in which case, the executable code for the service resides outside of STAFProc, for example, in a Java routine.
Services are known by their name, such as PROCESS or LOG. Internal services are always available and have a fixed name. External services must be registered, and the name by which they are known is specified when they are registered. If an external service is not registered with STAF, then the service is not available on that STAF Client.
Services may also be delegated to another STAF Client. In this case, when a request is made for the service on the local STAF Client, it is automatically forwarded to the machine to which this service has been delegated. For example, a testcase may request the local machine to log some information via the LOG service. If the LOG service has been delegated to another machine, the LOG request will actually be handled by the machine to which logging has been delegated. In this way, all logs could be conveniently stored on one system, without the testcases needing to explicitly send their LOG requests to the common system. In a similar manner, if a service were only available on a specific operating system, then all testcases could assume that the service was available locally, when, in fact, the service was being delegated to the machine running the required operating system.
Note: Internal services may not be delegated.
External services and delegated services are both registered in the STAF Configuration File. External services also may be dynamically added (registered) or removed (unregistered and terminated) via the SERVICE service (see 8.16, "Service Service").
Service loaders are external services whose purpose is to load services on-demand. They allow services to be loaded only when they have been requested, so they don't take up memory until needed. They also allow dynamic service registration when a request is made so that you don't have to change the STAF configuration file to register a service.
When a request is encountered for a service that doesn't exist, STAF will call each service loader, in the order they were configured, until the service exists or we run out of service loaders. If we run out of service loaders, then the standard RC:2 will be returned. Otherwise, the request will be sent to the newly added service.
A default serviceloader service (STAFDSLS) is shipped with STAF, and it can dynamically load the Log, Zip, Monitor, and ResPool services. This service will automatically be configured in your STAF.cfg file.
Authenticators are special external services whose purpose is to authenticate users in order to provide user level trust, which can be used in addition (or instead of) machine level trust. An Authenticator is a special service that accepts an authenticate request. As a user, you cannot directly submit a request to an authenticator service. Authenticators are accessed indirectly via the Handle service.
Authenticators can only be registered in the STAF configuration file -- they cannot be dynamically registered. One or more Authenticators can be registered. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter. If you want to authenticate across systems, you must register the Authenticator on each system using the same name (case-insensitive).
A workload is a set of processes running on a set of machines. A workload may be as simple as a single process running on a single machine, or it may be as complex as multiple processes on multiple machines coordinating together to perform a larger complex task. STAF was designed to help the creation and automation of workloads of all sizes.
STAF provides a means to store and retrieve variables. These variables may be used for any purpose the tester desires, such as storing testcase configuration parameters. These variables provide two main capabilities to testcase writers. One, they provide a standard means by which to store configuration data, i.e., each tester doesn't have to figure out how to store and retrieve said configuration data. Two, these variables may be changed dynamically. For example, if a testcase queries the WebServer variable before sending a request off to the web server, and that web server goes down, the WebServer variable can be dynamically changed by the tester to refer to a different web server, and the testcase can continue execution. Note how STAF allows the variable's value to be changed outside of the scope of the running testcase, thus allowing the testcase to continue execution without needing to be stopped and restarted.
STAF maintains a "system" variable pool that is common to all the processes on a given STAF Client. STAF also maintains a "shared" variable pool which is also system-wide, but which will be sent across the network and used in variable resolution on remote systems. In addition, each process/handle has its own variable pool. By default, the values of variables in a process' variable pool override the values of variables in the system and shared variable pools. However, the process may override this behavior when asking for the value of a variable. Basically, as part of every remote request, the originating handle and system shared variable pools are sent across the wire. These pools are stored only for the duration of the request for use in variable resolution.
The following system variables are predefined:
To substitute a variable's value, write the name of the variable in curly braces: "{STAF/Config/OS/Name}" is a valid reference to the variable STAF/Config/OS/Name. Assuming STAF/Config/OS/Name=Win2000, string "Operating system is {STAF/Config/OS/Name}" resolves to "Operating system is Win2000".
Variable references can be used in many places when submitting a STAF request. For example:
See section 8.20, "Variable (VAR) Service" for more information on setting and resolving variables.
Security in STAF can be defined at the machine level and/or the user level. In other words, you grant access to machines and/or to userids. Access in STAF is granted by specifying a certain trust level for a machine or user, where trust level 0 indicates no access and trust level 5 indicates all access. Each service in STAF defines what trust level is required in order to use the various functions the service provides.
A basic description of each level follows
In order to use user trust security in STAF, you must have at least one authenticator registered.
Note: The local machine can be granted a trust level by specifying interface "local" and a system identifier of "local".
User authentication overrides machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.
Each handle in STAF has a priority queue associated with it. This queue is used to accept/retrieve messages from other processes/machines. Each message in the queue has the following data associated with it.
STAF allows you to register to receive notifications for certain events, such as STAF starting and shutting down. These events will appear in the queue of the requesting process. They will reveal the originating handle as handle 1 of the originating machine, which is the reserved STAF Process handle.
The requests submitted to STAF and the results received from STAF are all strings. These strings may contain any arbitrary set of characters, including the NULL (i.e., 0) character. When working in an environment with a heterogeneous set of codepages, STAF will translate the request and result strings from and to the necessary codepages. This ensures that the request and result strings are not misinterpreted by the receiver.
In general, when using STAF services, there shouldn't be any round trip problems. "Round trip" in this context means when all requests are originating from the same system, even if the requests are sent to, and the data is stored on, a system with a different codepage. However, if you send, for example, a request to log data containing Japanese codepage specific characters to any system and then query the log from a system using a US English codepage, you won't get the "correct" data, as that is not a valid "round trip".
Note: All STAF generated strings are composed of only ASCII-7 characters and will safely survive the translation from/to different codepages.
If you need to specify non-ASCII characters in a request, then you need to be aware of some anomalies if your target system is a Windows system that isn't using an English codepage and whose ANSI codepage (ACP) identifier is different from the OEM codepage (OEMCP) identifier. The system locale determines which codepages are defaults for the Windows system. However, some European locales such as French and German set different values for the ACP and OEMCP. By default, STAF uses the OEM codepage when doing codepage translation. But, depending on where the data is input, it may be necessary to tell STAF to use the ANSI codepage. The ANSI codepage is used in the window manager and graphics device interface and by many applications. However, the Windows command line and bat files use the OEM codepage as they are interpreted by cmd.exe. You can use CHCP to display or change the codepage used by the command line. Note that these anomalies occur only on Windows systems.
To avoid these Windows codepage anomalies, you may need to change the codepage used by STAF using one of these methods:
Caution: You should NOT change the ACP value to the OEMCP value.
Note: To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage. For example:
STAF testmach1 VAR RESOLVE STRING {STAF/Config/CodePage}
On a GET FILE request to the FS service (or on another service request that submits a GET FILE request to the FS service like the STAX service does on an EXECUTE FILE request), RC 39 (Converter Error) is returned if the file contains data that is not valid in the codepage that STAF is using. To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage as discussed in the previous section.
To resolve an RC 39 (Converter Error) on a GET FILE request to the FS service, either:
The STAF Installation Guide (http://staf.sourceforge.net/current/STAFInstall.pdf) has detailed information on how to install STAF.
STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF Configuration File is read and processed line by line. Whitespace at the front of the line is removed before processing. Blank lines, or lines containing only whitespace are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line. The maximum length for a line in the STAF Configuration File is 2048 characters. The various configuration statements are described in the following sections.
You may use variables for all the values of configuration statement options, with the exception of the SET VAR configuration statement itself. However, these variables must be either predefined STAF variables (see 2.4, "Variables") or be previously defined in the STAF Configuration File via the SET VAR configuration statement (see below).
You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.
# This is a comment line
You may specify a nickname for your machine using the MACHINENICKNAME configuration statement.
This allows you to override the machine nickname which is set to the value of the STAF/Config/Machine system variable by default. This primarily affects the data stored by services such as the Log and Monitor services, which store data based on the machine from which it came by using the STAF/Config/MachineNickname system variable as part of the directory path when creating logs and monitor data. By allowing the STAF/Config/MachineNickname system variable to be overridden, it allows you to better manage your data.
The machine nickname is not used to communicate with other systems and does not have any effect on trust.
This option is used in both connected and disconnected modes (e.g. disconnected mode is when you are not using a network interface).
MACHINENICKNAME <Nickname>
<Nickname> is the nickname you wish to use for your machine. It is case sensitive.
MACHINENICKNAME testmachine1 MACHINENICKNAME JohnDoe
You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement. The INTERFACE configuration statement registers connection providers (also called network interfaces, or interfaces for short).
INTERFACE <Name> LIBRARY <Implementation Library> [OPTION <Name[=value]>]...
<Name> is the name by which this network interface (aka Connection Provider) will be known on this machine.
LIBRARY is the name of the shared library / DLL which implements the network interface (aka Connection Provider). STAF provides one implementation library called STAFTCP which provides support for both secure and non-secure TCP/IP communcation.
OPTION specifies a configuration option that will be passed on to the shared library / DLL which implements the connection provider. You may specify multiple OPTIONs for a given connection provider. See 4.3.2, "STAFTCP Connection Provider" for acceptable options for the STAFTCP shared library / DLL.
INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550 INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500 INTERFACE tcp2 LIBRARY STAFTCP INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6600 INTERFACE serial LIBRARY STAFSER
The STAFTCP connection provider shared library / DLL supports TCP/IP communication. STAF supports both secure and non-secure TCP/IP communication on most platforms. STAF supports both IPv4 and IPv6. IPv6 is supported in the IPv6 enabled version of STAF.
Each STAFTCP connection provider configured on a single machine must use a unique port number. To communicate to a remote machine running STAF, your machine and the remote machine must both have a STAFTCP connection provider configured with the same SECURE option value and the same PORT option value. A non-secure STAFTCP connection provider cannot communicate to a secure STAFTCP connection provider. Also, a secure TCP connection provider can only communicate to another secure TCP connection provider if the same certificate is used.
The STAFTCP connection provider supports the following OPTIONs:
CONNECTTIMEOUT=<Number> specifies the maximum time in milliseconds to wait for a connection attempt to a remote system to succeed. The default is 5000 (5 seconds). You may need to increase this value if you are consistently receiving return code 16 when trying to communicate with distant STAF systems. Note that the total time to wait for a connection to a remote system to succeed is (CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1)). If using the defaults, the maximum total time to wait for a connection to a remote system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds. The CONNECTATTEMPTS and CONNECTRETRYDELAY values are operational parameters that can be set in the STAF configuration file.
PORT=<Number> specifies the TCP/IP port on which this connection provider listens for connections. The default port is 6550 if option SECURE=Yes. The default port is 6500 if option SECURE=No. Each STAFTCP connection provider configured on a single machine must use a unique port number.
PROTOCOL=<IPv4 | IPv6 | IPv4_IPv6> specifies the communication protocol that this connection provider uses. The possible values are IPv4, IPv6, or IPv4_IPv6. When this option is absent, the default is IPv4_IPv6 which indicates to use both IPv4 and IPv6 protocols. This option is only valid for IPv6 enabled versions of STAF.
SECURE=<Yes | No> specifies whether to use secure or non-secure TCP/IP. Secure TCP/IP uses OpenSSL. This option is not available on Windows IA64 and z/OS where only non-secure TCP/IP is currently supported. The default is No.
SSL/CACertificate specifies the fully qualified path to the file containing the STAF CA certificate list used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/CAList.crt which is a list of the default server certificate provided with STAF.
SSL/ServerCertificate specifies the fully qualified path to the file containing the STAF server certificate used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/STAFDefault.crt which is a self-signed x509 default certificate provided with STAF.
SSL/ServerKey specifies the fully qualifed path to the file containing the STAF server key used for secure connections. This option is only valid if option SECURE=Yes is specified. The default is {STAF/Config/STAFRoot}/bin/STAFDefault.key which is a default server key provided with STAF.
INTERFACE ssl LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6550
INTERFACE tcp LIBRARY STAFTCP OPTION SECURE=No OPTION PORT=6500
INTERFACE tcp2 LIBRARY STAFTCP OPTION PORT=6501
INTERFACE tcp3 LIBRARY STAFTCP OPTION PORT=6700 OPTION PROTOCOL=IPv6
INTERFACE tcp4 LIBRARY STAFTCP OPTION CONNECTTIMEOUT=15000
INTERFACE ssl2 LIBRARY STAFTCP OPTION SECURE=Yes OPTION PORT=6551 \
OPTION SSL/CACertificate={STAF/Config/STAFRoot}/bin/MyCAList.crt \
OPTION SSL/ServerCertificate={STAF/Config/STAFRoot}/bin/MySTAF.crt \
OPTION SSL/ServerKey={STAF/Config/STAFRoot}/bin/MySTAF.key
External services are registered with the SERVICE configuration statement.
SERVICE <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
or
SERVICE <Name> DELEGATE <Machine> [TONAME <Remote Service Name>]
<Name> is the name by which this service will be known on this machine.
LIBRARY is the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, for a Java service, this might be the name of the Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See below for information regarding the JSTAF service proxy library. Otherwise, see the documentation provided by the service proxy library.
OPTION specifies a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See below for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the service during initialization.
DELEGATE specifies the machine to which to delegate this service. This machine must be running STAF V3.0.0 or later.
Note: From a trust perspective, the tcp interface names on the "delegated to" service machine and on the machine delegating service requests to it must match or the trust statement for the machine that is delegating service requests must use a wildcard to match any interface.
TONAME is the name of the service on <Machine> to which the delegated requests will be sent. The default is the same name as specified with <Name>.
SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096"
SERVICE LOG LIBRARY STAFLog
SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\service\STAX.jar \
OPTION J2=-Xmx128m
SERVICE SAMPLEJ LIBRARY JSTAF EXECUTE C:\STAF\services\Sample.jar \
PARMS {STAF/Config/STAFRoot}\bin\sample.dft
SERVICE MYLOG DELEGATE TestSrv1
SERVICE PAGER DELEGATE pagesrv.austin.ibm.com
SERVICE EVENT DELEGATE EventSrv TONAME DB2EVENT
SERVICE NOTIFY LIBRARY Notify PARMS "24 Hours 7 Days"
SERVICE ZIP LIBRARY STAFEXECPROXY EXECUTE STAFZip
The library JSTAF acts as a proxy for STAF services implemented in the Java language. JSTAF works with Java 1.3 and above.
The EXECUTE option for a Java service should specify the fully-qualified name of the jar file that implements the service. The jar file will be automatically added to the class path by JSTAF.
Note: In versions of STAF prior to 2.4.0, the name of the Java class that implements the service was specified for the EXECUTE option and you had to make sure that the service's class files were in the class path. This is still supported, but this method is deprecated and will be removed in a future version of STAF.
JSTAF supports the following OPTIONs:
JVMName=<Name> specifies the name for the JVM you want the Java service to run in. If the JVM does not already exist, it will be created. If no JVMName is specified, then the Java service will run in the default JVM, named STAFJVM1, which is created the first time a Java service is registered with no JVMName specified. This option allows JSTAF to run Java services in different JVMs.
JVM=<Executable> specifies the name of the desired Java executable. The default is "java". Note, this option is only valid for the first service created with a given JVMName.
Note: The HP-UX IA64 64-bit version of STAF requires Java 1.4.1 or later.
J2=<Java option> specifies an arbitrary Java option that should be passed to the JVM. You can find more information on these options by using the command "java" (for standard options) and "java -X" (for non-standard options), or by consulting your Java documentation. Note that -X options can vary depending on which Java implementation (e.g. Sun Java 1.4.0 vs IBM Java 1.3.1) you installed. Note, this option is only valid for the first service created with a given JVMName.
Note: If you are using the HP-UX IA64 64-bit version of STAF, you must specify the -d64 option to the JVM. This can be done by specifying J2=-d64
MAXLOGS=<Number> specifies the maximum number of log files for the JVM that should be saved. The default is 5. The JVM log files are stored in the {STAF/DataDir}/lang/java/jvm/<JVMName> directory and contain JVM start information such as the date/time when the JVM was started, the JVM executable, and the J2 options used to start the JVM. In addition, it contains any other information logged by the JVM, including any errors that may have occurred while the JVM was running. The current JVM log file is named JVMLog.1 and saved JVM log files, if any, are named JVMLog.2 to JVMLog.<MAXLOGS>. Note, this option is only valid for the first service created with a given JVMName.
MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the JVM log file(s). The default is 1048576 (1M). This option determines when to create a new JVM log file. When the JVM is started, if the size of a JVM log file exceeds the maximum size specified by this option, a new JVM log file will be created. Note, this option is only valid for the first service created with a given JVMName.
Note: You can view the JVM log for a Java service that is currently registered using the STAFJVMLogViewer utility. Section 9.2, "JVM Log Viewer Class" provides more information on this utility.
OPTION J2=-verbose:gc
OPTION "J2=-cp {STAF/Config/BootDrive}/MyJava/Extra.jar{STAF/Config/Sep/Path}{STAF/Env/Classpath}"
OPTION J2=-Xms64m
OPTION J2=-Xmx128m
OPTION J2=-d64
OPTION JVMName=MyJVM1
OPTION JVM=/opt/sunjdk1.4.0/jre/bin/java
OPTION MAXLOGS=2
OPTION MAXLOGSIZE=2048
If you wanted to run the STAX Java service in a JVM, called MyJVM1, with a maximum heap size of 128M, and wanted the Event and EventManager Java services to run in a different JVM, called MyJVM2, with a maximum heap size of 64M, you could specify the following service registration lines in the STAF.cfg file (or dynamically register the services in this order using the specified options).
SERVICE STAX LIBRARY JSTAF EXECUTE C:/STAF/service/STAX.jar \
OPTION JVMName=MyJVM1 OPTION J2=-Xmx128m
SERVICE Event LIBRARY JSTAF EXECUTE C:/STAF/service/STAFEvent.jar \
OPTION JVMName=MyJVM2 OPTION J2=-Xmx64m
SERVICE EventManager LIBRARY JSTAF EXECUTE C:/STAF/services/EventManager.jar \
OPTION JVMName=MyJVM2
The library PLSTAF acts as a proxy for STAF services implemented in the Perl language. PLSTAF is currently supported on Windows (IA32), Linux (IA32), and Mac OS X. On Linux IA32, PLSTAF is currently only supported with Perl 5.8.0.
The EXECUTE option for a Perl service should specify the name of the .pm file (without the .pm extension) that implements the service.
PLSTAF supports the following OPTIONs:
USELIB=<Number> specifies the directory containing the .pm file that implements the service. You must use the USELIB option unless you have set (prior to starting STAFProc) environment variable PERLLIB to include the directory containing the .pm file that implements the service.
MAXLOGS=<Number> specifies the maximum number of log files for the Perl interpreter that should be saved. The default is 5. The Perl interpreter log files are stored in the {STAF/DataDir}/lang/perl/<serviceName> directory and contain the Perl interpreter start information such as the date/time when the Perl interpreter was started and the Perl service executable. In addition, it contains any other information logged by the Perl service and interpreter, including any errors that may have occurred while the Perl interpreter was running. The current Perl interpreter log file is named PerlInterpreter.1 and saved Perl interpreter log files, if any, are named PerlInterpreter.2 to PerlInterpreter.<MAXLOGS>.
MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the Perl interpreter log file(s). The default is 1048576 (1M). This option determines when to create a new Perl interpreter log file. When the Perl interpreter is started, if the size of a Perl interpreter log file exceeds the maximum size specified by this option, a new Perl interpreter log file will be created.
Note: The PLSTAF service proxy library uses embedded Perl directly within the STAFProc executable. This means that if a Perl service has a fatal error which terminates the Perl interpreter, the STAFProc executable will also be terminated. To prevent this, you can use the STAFEXECPROXY service proxy library when registering a Perl service.
Note: To configure Perl services, prior to starting STAFProc, environment variable PERLLIB must be set to include the directory containing the PLSTAF.pm and PLSTAFService.pm files (located in the "bin" directory in the STAF installation root directory).
Note: To configure Perl services, the directory containing the PLSTAF library (PLSTAF.dll on Windows, libPLSTAF.so on Linux, libPLSTAF.dylib on Mac OS X) must be in the operating system's library path (PATH on Windows, LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on Mac OS X) prior to starting STAFProc.
Note: When configuring Perl services on Linux with Perl 5.8.0, the directory containing the Perl 5.8.0 libperl.so file must be included in environment variable LD_LIBRARY_PATH prior to starting STAFProc.
Note: When removing a Perl service (or when shutting down STAF if Perl services had been configured), you may see a message in the STAFProc output similar to: "Perl exited with active threads". This message can be ignored.
SERVICE Device1 LIBRARY PLSTAF EXECUTE DeviceService
SERVICE Device2 LIBRARY STAFEXECPROXY EXECUTE DeviceService \
OPTION PROXYLIBRARY=PLSTAF
SERVICE testA LIBRARY STAFEXECPROXY EXECUTE myTestService \
OPTION PROXYLIBRARY=PLSTAF OPTION USELIB=C:\MyServices
This library will allow you to execute an external STAF service within a new executable, rather than directly within the STAFProc executable. For example, this library could be used to run the Zip service in a separate executable, or run a Perl service where the Perl interpreter will run in a separate executable.
Running an external STAF service in a separate executable will ensure that if the service has a fatal error, the error will not kill STAFProc. In addition, this allows monitoring of the external service's system resource utilization, since you can view the utilization for the new executable (otherwise, if the service was running within the STAFProc executable, then the service's resource utilization would be part of the STAFProc resource utilization).
Note that using the STAFEXECPROXY library will introduce a level of IPC communication for all service requests to the service; rather than STAFProc sending the requests directly to the service, STAFProc will send the request to the STAFEXECPROXY library, which will then send the request to the new executable, which will then send the request to the service (processing the service result will have the same path in reverse). So, for external STAF services where performance is critical, such as the Log and Monitor services, using the STAFEXECPROXY library is not recommended.
Note that since the JSTAF proxy library already runs the Java STAF service in a new executable (the JVM), using the STAFEXECPROXY library for Java STAF services is not supported (if you attempt to register a Java STAF service using the STAFEXECPROXY library, you will get an RC 27, Service configuration error).
The EXECUTE option is used to indicate the service library to execute, or if the service will be executed by a proxy library, it will be used to indicate what service executable the proxy library should execute. For example, for the Zip service, "STAFZip" would be used for the EXECUTE value. For a Perl service, which uses the PLSTAF proxy library, the service .pm module would be used for the EXECUTE value.
STAFEXECPROXY supports the following OPTIONs (note that all other OPTIONs will be passed to the service library / DLL):
The OPTION PROXYLIBRARY= option 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.
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 loaders are registered with the SERVICELOADER configuration statement.
SERVICELOADER LIBRARY <Implementation library> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
LIBRARY is the name of the shared library / DLL which implements the service loader or acts as a proxy for the service loader. See the information for each service loader to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the service loader. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.
OPTION specifes a configuration option that will be passed on to the service loader library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service loader implementation. You may specify multiple OPTIONs for a given service loader. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the service loader during initialization.
SERVICELOADER LIBRARY STAFDSLS SERVICELOADER LIBRARY JSTAF EXECUTE C:/STAF/services/CustomServiceLoader.jar
Authenticator services are registered with the AUTHENTICATOR configuration statement. The first Authenticator registered is the default, unless overridden by using the DEFAULTAUTHENTICATOR operational parameter.
AUTHENTICATOR <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
[OPTION <Name[=Value]>]... [PARMS <Parameters>]
<Name> is the name by which this authenticator service will be known on this machine. The name cannot be "none" as this is reserved for use by STAF. If you want to authenticate across systems, you must register the authenticator on each system using the same name (case-insensitive).
LIBRARY is the name of the shared library / DLL which implements the authenticator service or acts as a proxy for the authenticator service. See the information for each authenticator to determine the appropriate value for this option.
EXECUTE is used by service proxy libraries to specify what the proxy library should execute. For example, this might be the name of the Java jar file which actually implements the authenticator service. This option has no significance for non-proxy service libraries. See the Service Registration section for information regarding the JSTAF service proxy library.
OPTION specifies a configuration option that will be passed on to the shared library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given authenticator service. See the Service Registration section for acceptable options for the JSTAF service proxy library. Otherwise, see the documentation provided with the service (proxy) library.
PARMS specifies optional parameters that will be passed to the authenticator service during initialization.
AUTHENTICATOR MyAuth LIBRARY JSTAF EXECUTE C:/STAF/services/MyAuth.jar
AUTHENTICATOR AuthSample LIBRARY JSTAF \
EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
OPTION JVMName=Auth \
PARMS "UserPropertiesFile {STAF/Config/STAFRoot}/services/authsample.properties"
A sample authenticator service is provided by STAF and is available via the Download STAF website. It is called AuthSample and is available as a jar file called AuthSampleV300.jar.
To try out user trust, you can register the sample authenticator as follows (assuming you downloaded it to a services directory created in the STAF root directory).
AUTHENTICATOR AuthSample LIBRARY JSTAF \
EXECUTE {STAF/Config/STAFRoot}\services\AuthSampleV300.jar \
PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/authsample.properties"
LIBRARY must be JSTAF for this sample authenticator as it is implemented in Java.
EXECUTE must be the fully-qualified name of the AuthSampleV300.jar file.
This sample authenticator has the following required parameter:
To perform user authentication across systems, the authenticator must be registered as the same name (case-insensitive) on all machines where you want to use user trust authentication and with the same user properties file (e.g. one that supports the same user identifiers and passwords).
An example of a user properties file is:
# User Properties File for the Sample Authenticator User1=Password1 User2=Password2 User3=Password3 User4=Password4 User5=Password5
You can specify any user identifiers and passwords that you want in a user properties file. However, do not specify any confidential information (e.g. any real passwords that you want to protect) as this information is not protected when sent over the network in STAF V3.0.0. In STAF V3.1, a secure TCP interface will be provided.
STAFProc allows you to set various parameters which affect the general operation of STAF. The SET configuration statement lets you set these general operational parameters.
SET [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
[MAXQUEUESIZE <Number>]
[INITIALTHREADS <Number>] [THREADGROWTHDELTA <Number>]
[DATADIR <Directory Name>]
[INTERFACECYCLING <Enabled | Disabled>]
[DEFAULTINTERFACE <Name>]
[DEFAULTAUTHENTICATOR <Name>]
[ENABLEDIAGS]
[STRICTFSCOPYTRUST]
[RESULTCOMPATIBILITYMODE <Mode>]
[DEFAULTSTOPUSING <Method>]
[DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE]
[DEFAULTFOCUS <Background | Foreground | Minimized>]
[PROCESSAUTHMODE <Authentication Mode>]
[DEFAULTAUTHUSERNAME] [DEFAULTAUTHPASSWORD]
[DEFAULTAUTHDISABLEDACTION <Disabled Action>]
[DEFAULTSHELL <Shell>]
[DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
CONNECTATTEMPTS specifies the maximum number of times to attempt to connect to a remote system. The default is 2. Note that a trace warning message is generated for each failed attempt if the Warning trace point is enabled. You may also change this setting dynamically using the MISC service's SET command.
CONNECTRETRYDELAY specifies the maximum time in milliseconds to wait after a failed connection attempt to a remote system before trying to connect again (if the maximum number of times to attempt to connect to a remote system has not been reached yet). The default is 1000 (i.e., 1 second). You may also change this setting dynamically using the MISC service's SET command.
MAXQUEUESIZE specifies the maximum size of the queue associated with each process' handle. The default is 100. You may also change this setting dynamically using the MISC service's SET command.
INITIALTHREADS specifies the number of threads initially created to handle service requests. The default is 5.
THREADGROWTHDELTA specifies the number of additional threads which should be created when all existing threads are busy. The default is 1.
DATADIR specifies the directory that STAF and its services will use to write data. The default is {STAF/Config/STAFRoot}/data/{STAF/Config/InstanceName}. Note that this directory name must be unique per instance of STAFProc running on a single machine. Also, make sure to include the "SET DATADIR" line in the STAF configuration file at the beginning of the file, before any services are registered, since the data directory can be used during service registration. See 4.14, "Data Directory Structure" for more information about the STAF data directory and its contents.
INTERFACECYCLING specifies whether to enable or disable automatic interface cycling. The default is to enable automatic interface cycling. You may also change this setting dynamically using the MISC service's SET command. Recognized values are the following:
Note that automatic interface cycling only has an effect if there are multiple interfaces configured in the STAF configuration file on the machine that is submitting a STAF request. Also, note that the MISC service provides a LIST ENDPOINTCACHE request to show the cached endpoints and a PURGE ENDPOINTCACHE request to purge one or more cached endpoints.
DEFAULTINTERFACE specifies the name of the network interface (aka connection provider) to use, by default. If not specified, the first interface registered is the default. You may also change this setting dynamically using the MISC service's SET command.
DEFAULTAUTHENTICATOR specifies the name of the Authenticator to use, by default. If not specified, the first Authenticator registered is the default. If no authenticators are registered, the default authenticator is none. You may also change this setting dynamically using the MISC service's SET command.
ENABLEDIAGS specifies to enable diagnostics. The default is to disable diagnostics. You may also enable (or disable) recording diagnostics dynamically using the DIAG service.
STRICTFSCOPYTRUST specifies to enable strict trust checking when copying a file or directory using the FS service. The default is to disable strict trust checking (e.g. do lenient trust checking) on a FS COPY request when the machine submitting the request is the same as the machine where which the file/directory is being copied. That is, STRICTFSCOPYTRUST specifies that a trust check should be done to verify that MachineA trusts MachineB when MachineA submits a COPY request to the FS service on MachineB to copy a file or directory back to MachineA. The default is to do lenient trust checking so that MachineA does not have to trust MachineB since why would MachineA ask MachineB to copy the file/directory if he didn't want the copy to work. You may also change this setting dynamically using the FS service's SET command.
RESULTCOMPATIBILITYMODE specifies the compatibility mode used when sending the result from a STAF service request back to a pre-STAF V3 system. Recognized values are the following:
DEFAULTSTOPUSING allows you to specify the default method used to STOP processes. See 8.12.3, "STOP" for more information on available methods. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTNEWCONSOLE specifies that processes should be STARTed in a new console window. This is the default for Windows systems. This option has no effect on Unix systems. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTSAMECONSOLE specifies that processes should be STARTed in the same console as STAFProc. This is the default on Unix systems. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTFOCUS specifies the focus that is to be given to new windows opened when starting a process on a Windows system. The default focus mode is Background. This option only has effect on Windows systems. This option will resolve variables. See 8.12.2, "START" for more information on the FOCUS option. You may also change this setting dynamically using the PROCESS service's SET command.
PROCESSAUTHMODE specifies the mode by which usernames/passwords are authenticated when starting processes. The value of this option is platform specific. Recognized values are the following:
Note: Previously, PASSWD and SHADOW were supported values for the PROCESSAUTHMODE on Unix systems, but support for for these modes has been removed.
You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHUSERNAME specifies the username under which processes will be started, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHPASSWORD specifies the password with which processes will be authenticated, by default. Note, this option IS valid even if process authentication has been disabled. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTAUTHDISABLEDACTION specifies what default action should be taken if the user specifies a username/password on a request to start a process when process authentication has been disabled. The following values are recognized:
DEFAULTSHELL specifies the default shell to use when starting a process via a separate shell. The default shell used for Unix systems is /bin/sh. The default shell used for Windows NT/2000/XP/2003/Vista/2008 systems is "cmd.exe /c". The default shell used for Windows 95/98/ME systems is "command.com /c". You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTNEWCONSOLESHELL specifies the default shell to use when starting a process in a new console window (e.g. NEWCONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.
DEFAULTSAMECONSOLESHELL specifies the default shell to use when starting a process in the same console as STAFProc (e.g. SAMECONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified. You may also change this setting dynamically using the PROCESS service's SET command.
A shell value can contain substitution characters described in the following table.
Table 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 2000 SET MAXQUEUESIZE 1000 SET INITIALTHREADS 10 THREADGROWTHDELTA 3 SET DATADIR /test/stafdata SET DEFAULTINTERFACE tcp SET DEFAULTAUTHENTICATOR SampleAuth SET ENABLEDIAGS SET RESULTCOMPATIBILITYMODE none SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE SET DEFAULTFOCUS minimized SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C" SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C" SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X" SET DEFAULTSHELL "su - %u -c %C"
You may set STAF variables in the system or shared variable pool at startup by using the SET VAR configuration statement. SET VAR will set a variable to a certain value. The variable is created if it does not exist.
Note that you may SET multiple variables with a single request.
SET [SYSTEM | SHARED] VAR <Name=Value> [VAR <Name=Value>] ...
SYSTEM means the variable is to be set in system variable pool. This is the default.
SHARED means the variable is to be set in shared variable pool.
VAR means the variable to be set. Name is the name of the variable and Value is the value of the variable.
SET VAR WebServer=testsrv1.test.austin.ibm.com
SET SHARED VAR "Author1=Jane Tester" VAR "Author2=John Tester"
SET SYSTEM VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
You may grant access to machines or users by using the TRUST configuration statement.
Trust configuration statements for machines are based on the network identification of the system. In particular, different trust levels can be given to the same system coming in through different networking interfaces. Both logical and physical identifiers may be used in trust configuration statements for machines.
Trust configuration statements for users require that you have an authenticator registered.
TRUST LEVEL <Level> < DEFAULT | MACHINE <Machine> [MACHINE <Machine>]... |
USER <User> [USER <User>]... >
LEVEL is the level of trust that you wish to grant, see 2.5, "Security" for a list of trust levels.
DEFAULT indicates that you wish to set the default trust level. This is the trust level that will be used for machines which have no explicit trust level set. If no default has been specified in the STAF Configuration file, the default is set to 3.
MACHINE indicates a specific machine for which to set a trust level. The format for <Machine> is:
[<Interface>://]<System Identifier>where:
Note that you can specify match patterns (e.g. wild cards) in the interface and the system identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
Note that if you specify the hostname in a trust specification for a TCP/IP interface, you must specify the long host name (and/or wildcards).
Note that if you specify a port (e.g. @6500) at the end of the system identifier, it will be removed.
Requests coming from the local system will now appear as though they came from an interface named "local" and a system identifier of "local". This allows you to specify a trust level for local requests. (In STAF V2.x, local requests were automatically granted a trust level of 5.)
USER indicates a user for which to set a trust level. The format for <User> is:
[<Authenticator>://]<User Identifier>where:
Note that you can specify match patterns in the authenticator name and the user identifier. These patterns recognize two special characters, '*' and '?', where '*' matches a string of characters (including an empty string) and '?' matches any single character (the empty string does not match).
If multiple trust specifications would match the same user, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
If multiple trust specifications would match the same system, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:
Note: The user authentication overrides the machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.
TRUST DEFAULT LEVEL 3 TRUST LEVEL 5 MACHINE local://local TRUST LEVEL 5 MACHINE client1.austin.ibm.com MACHINE client3.raleigh.ibm.com TRUST LEVEL 5 MACHINE 9.3.224.16 TRUST LEVEL 4 MACHINE tcp://mysystem.site.com TRUST LEVEL 0 MACHINE badguy.austin.ibm.com TRUST LEVEL 3 MACHINE tcp2://9.3.224.* TRUST LEVEL 2 MACHINE *.austin.ibm.com TRUST LEVEL 2 MACHINE tcp*://*.site.com TRUST LEVEL 5 USER John@company.com USER Jane@company.com TRUST LEVEL 0 USER badguy@company.com TRUST LEVEL 3 USER *@company.com TRUST LEVEL 4 USER SampleAuth://*@company.com TRUST LEVEL 1 USER *://*
You may specify that you want notifications sent to certain machines/processes when STAF is either started or shutdown. You do this by using the NOTIFY configuration statement. Notifications are handled by the STAF Queue service, see 8.13, "Queue Service" for more information.
Note: You may also dynamically register for SHUTDOWN notifications via the SHUTDOWN service, see 8.17, "Shutdown Service".
Warning: In order for the 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> > TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled>
See the TRACE service, section 8.18, "Trace Service", for information on the above options.
See table 8.18.2, "Trace Points Reference" for a list of valid trace points.
TRACE SET DESTINATION TO STDERR
TRACE SET DESTINATION TO FILE {STAF/Config/STAFRoot}/bin/STAF.trc
TRACE ENABLE ALL
TRACE DISABLE SERVICE "Sem"
TRACE ENABLE TRACEPOINTS "Error ServiceAccessDenied"
TRACE DISABLE SERVICES "Process Queue Var"
TRACE SET DEFAULTSERVICESTATE Enabled
In order to ensure that you are only tracing service results on the var and sem services, and that tracing for all other services is disabled (including services registered in the future) do this :
TRACE SET DEFAULTSERVICESTATE Disabled TRACE DISABLE ALL SERVICES TRACE DISABLE ALL TRACEPOINTS TRACE ENABLE TRACEPOINTS "ServiceResult" TRACE ENABLE SERVICES "VAR SEM"
This is the default configuration file provided with STAF.
# Turn on tracing of internal errors and deprecated options trace enable tracepoints "error deprecated" # Enable TCP/IP connections interface 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. |
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.17, "Shutdown Service" for more information on the SHUTDOWN service.
Note: Any changes made to the STAF Configuration File after STAFProc has been started will not take effect until you shutdown and restart STAFProc.
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 with UAC (User Account Controls) enabled, STAFProc is run using the least amount of privileges (e.g. that of a standard user) even if you are logged in as an administrator. If you want to run a process via the STAF PROCESS START request that requires administrative privileges, such as an install program, and not get UAC prompts, you may need to run STAFProc as an administrator. There are several ways to do this:
Note: When STAFProc.exe is run as an administrator, you must also run STAF.exe as an administrator if you want to submit local STAF requests from a command prompt on the local Windows Vista machine. Otherwise, you'll get "Error registering with STAF, RC: 21".
STAF is an executable that is used to submit requests to STAF from the command line. Please see "Using the STAF command from shell-scripts" for more information on using the STAF command from within shell-scripts.
STAF [-verbose] <Endpoint> <Service> <Request>
[<Interface>://]<System Identifier>[@<Port>]where:
STAF local PING PING STAF local sem event SynchSem post STAF testmach1 PROCESS START COMMAND notepad STAF testmach1.company.com PROCESS LIST STAF -verbose testmach1.company.com PROCESS LIST STAF ssl://testmach1 PROCESS START SHELL COMMAND /tests/myTest RETURNSTDOUT STDERRTOSTDOUT WAIT STAF tcp://testmach1 TRUST LIST STAF alt-tcp2://9.3.283.13 SERVICE LIST STAF testmach1@6600 PROCESS START COMMAND notepad NOTIFY ONEND STAF tcp://testmach.company.com@6500 MISC WHOAMI STAF local ECHO ECHO "Hi there" STAF 9.3.823.20 LOG MACHINE LOGNAME MyLog LEVEL info MESSAGE "This is a message" STAF local var set SYSTEM var "SomeName=Some text string"
set STAF_INSTANCE_NAME=MySTAF staf local ping ping
On a successful STAF request (i.e., a request with a zero return code), the output from the STAF command will be as follows
Response -------- <Result string>
where <Result string> is any information that was returned from the STAF service request.
For example, the output of STAF LOCAL PING PING should be
Response -------- PONG
On an unsuccessful STAF request (i.e., a request with a non-zero return code), the output from the STAF command will be as follows
Error submitting request, RC: <Return code> Additional info --------------- <Result string>
where <Return code> is the actual return code from the request, and <Result string> is any information returned from the request. <Result string> usually contains information that explains why the error occurred. Note, the "Additional info" will only be present if a non-empty result string was returned. Additionally, you may refer to Appendix A, "API Return Codes" for information about the <Return code>
For example, the output of STAF LOCAL SEM LIST should be
Error submitting request, RC: 7 Additional info --------------- You must have at least 1, but no more than 1 of the option(s), MUTEX EVENT
Note: If the <Result string> from a STAF command contains any null characters, you can set the environment variable STAF_REPLACE_NULLS to any non-empty value. This will cause the STAF command to replace any null characters in the <Result string> with the specified value. Otherwise, the <Result string> will be truncated at the first null character found.
When structured data (see 6.1, "Marshalling Structured Data") is returned in the result strings above, the STAF command will automatically unmarshall the data and print it in the most appropriate format. If the data is a <List> of <String>, then each entry in the list will be printed on its own line. For example,
C:\> staf local fs list directory c:\ Response -------- AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT
If the data is a <Map> (or <Map:<Class>>) which has values which are all of type <String>, then each key/value pair will be printed on its own line. For example,
C:\> staf local monitor list settings Response -------- Max Record Size : 1024 Resolve Message : Disabled Resolve Message Var: Disabled
The above two types of formatted output are frequently referred to as "default format".
If the data is a <List> of <Map:<Class>> where every item in the list is an instance of the same map class, then the data will be printed out in a tabular format, called "table format". For example,
$ staf local handle list handles Response -------- Handle Handle Name State Last Used Date-Time ------ ------------------------------- ---------- ------------------- 1 STAF_Process InProcess 20040929-13:57:40 2 STAF/Service/STAFServiceLoader1 InProcess 20040929-16:06:47 5 STAF/Service/LOG InProcess 20040929-13:57:52 7 STAF/Service/RESPOOL InProcess 20040929-13:58:04 51 STAF/Service/MONITOR InProcess 20040929-16:06:47 57 STAF/Client Registered 20040929-16:09:35
The column headings in the table format are determined using the display name specified for each key. Short display names may be used as column headings by the STAF executable when displaying the result in a tabular form if the total width of the display names exceeds 80 characters.
By default a single record in the table format will only display the first 20 lines (the last line will show "(More...)" to indicate that there were more lines in the record). You can override the maximum number of lines that are displayed per record by setting the environment variable STAF_TABLE_LINES_PER_RECORD to the maximum number of lines.
You can disable the output of tables by setting the environment variable STAF_PRINT_NO_TABLES to any value. If you disable the output of tables, their data will show up in the more verbose mode (described below).
If the data is more complex than the above (or tables have been turned off), the output will be printed in a hierarchical nested format, called "verbose format". The best way to describe it is with an example.
C:\> staf local sem query event Test
Response
--------
{
State : Reset
Last Posted: {
Machine : crankin3
Handle Name: STAF/Client
Handle : 62
User : none://anonymous
Date-Time : 20040929-16:20:56
}
Last Reset : {
Machine : crankin3
Handle Name: STAF/Client
Handle : 65
User : none://anonymous
Date-Time : 20040929-16:21:43
}
Waiters : [
{
Machine : crankin3
Handle Name: TestHandle
Handle : 67
User : none://anonymous
Date-Time : 20040929-16:22:16
}
]
}
You can change the amount of indentation used by setting the environment variable STAF_INDENT_DELTA to any non-negative integer.
You can use the -verbose option to force the use of the verbose mode on a command basis. For example,
C:\> staf -verbose local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
You can force the exclusive use of the verbose mode by setting the environment variable STAF_PRINT_MODE to "verbose". For example,
C:\> set STAF_PRINT_MODE=verbose C:\> staf local fs list directory c:\ Response -------- [ AUTOEXEC.BAT boot.ini CONFIG.SYS Documents and Settings i387 IO.SYS MSDOS.SYS My Music NTDETECT.COM ntldr PAGEFILE.SYS Program Files Recycled RECYCLER System Volume Information temp WINNT ]
If you should ever need to get at the raw result string (instead of the structured output), you can set the environment variable STAF_PRINT_MODE to "raw". For example,
C:\> set STAF_PRINT_MODE=raw
C:\> staf local fs list directory C:/temp/docs
Response
--------
@SDT/*:267:@SDT/{:26::13:map-class-map@SDT/{:0:@SDT/[10:218:@SDT/$S:11:STAFTcl.h
tm@SDT/$S:12:STAFPerl.htm@SDT/$S:14:STAFPython.htm@SDT/$S:7:History@SDT/$S:12:ST
AFCMDS.htm@SDT/$S:11:STAFFAQ.htm@SDT/$S:10:STAFGS.pdf@SDT/$S:12:STAFHome.htm@SDT
/$S:10:STAFRC.htm@SDT/$S:10:STAFUG.htm
Note, by default, any <String> value that looks as though it, itself, is a marshalled data structure will be recursively unmarshalled. For example, if someone marshalls a data structure and uses the resultant string as the message for a log request, and then you query the log, the data structure in the log message string will automatically be unmarshalled. If you want to turn off this behavior from the command line, and, instead, see the marshalled string in the message, set the environment variable STAF_IGNORE_INDIRECT_OBJECTS to any value.
There are two special environment variables that can be used to make the STAF command blend in with shell-scripts. The first is STAF_QUIET_MODE. Setting this environment variable to any non-null value will cause the STAF command to only output the <Result string> that the request generated. For example, the "STAF local ping ping" command above would simply return
PONG
This makes it easy to call STAF from shell-scripts. For example,
export STAF_QUIET_MODE=1 STAFResult=`STAF local ping ping` if [ $? -ne 0 ]; then echo "Non-zero return code from ping request"; elif [ "$STAFResult" != "PONG" ]; then echo "Expected PONG, received $STAFResult"; else echo "ping request succeeded" fi
The second environment variable is STAF_STATIC_HANDLE. If this environment variable is set, the STAF command will use the handle number indicated by this environment variable. This ensures that the shell-script can use the same handle throughout its execution. You may obtain a static handle in one of two ways. The first is using the CREATE command of the HANDLE service (see 8.5.2, "CREATE"). For example,
export STAF_STATIC_HANDLE=`STAF local handle create handle name "My Test"`
In this case, you are responsible for deleting the shell-scripts handle prior to your shell-script exiting. For example,
STAF local handle delete handle $STAF_STATIC_HANDLE
The second way is by using the STATICHANDLENAME option when starting your script through the PROCESS service (see 8.12.2, "START"). In this case the STAF_STATIC_HANDLE environment variable will already be set for you. In addition, the handle will automatically be deleted by STAF when your shell-script completes.
You can test for the existence of the STAF_STATIC_HANDLE environment variable to determine if your shell-script was started via STAF, or whether it was started by hand from the command line.
STAF supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure.
STAF supports the following generic data types with its marshalling.
Most languages support some form of the None, String, List, and Map data types. However, a map class and a marshalling context are likely new concepts.
A map class is really just a specialized map that is associated with a map class definition. The map class definition is used to reduce the size of a marshalling map class in comparison to a map containing the same data. It also contains information about how to display instances of the map class. A map class definition contains for following information for each key defined for a map class:
You indicate that a map is an instance of a map class by setting the key "staf-map-class-name" to the name of the map class. And, when you unmarshall a data structure, if you see that a map has a key called "staf-map-class-name", you know that the map is really an instance of a map class. You get and set map class definitions using a marshalling context.
A marshalling context is simply a container for map class definitions and a data structure that uses (or is defined in terms of) them. In order to use a map class when marshalling data, you must add the map class definition to the marshalling context, set the root object of the marshalling context to the object you want to marshall, and then marshall the marshalling context itself. When you unmarshall a data structure, you will always receive a marshalling context. Any map class definitions referenced by map classes within the data structure will be present in the marshalling context.
When a string is unmarshalled into a data structure, it is possible that one of the string objects that is unmarshalled is itself the string form of another marshalled data structure. By default, STAF will recursively unmarshall these nested objects. However, each language has a way to disable these additional processing.
STAF externalizes six primary APIs to C/C++ programs. These APIs allow you to register/unregister with STAF, submit service requests, and free the memory associated with service request results. In addition, STAF provides a wide range of APIs for defining, manipulating, and marshalling data structures. Also, STAF provides some APIs for handling private data.
Note: STAF-enabled programs written in C must be linked with the C++ compiler (or by using any other means which allows the C++ runtime to get initialized). Otherwise, the C++ runtime won't get a chance to initialize so the STAF static data doesn't get initialized. Most systems require mixed C and C++ code to get linked by the C++ compiler.
The STAFRegister call is used by a C program to register with STAF.
STAFRC_t STAFRegister(char *handleName, STAFHandle *handle)
handleName points to the name by which you want this handle to be known.
handle is a pointer to the STAFHandle that will be set on successful return from the function. You will use this handle on all other subsequent STAF calls.
char *myName = "MyProgram"; STAFHandle_t myHandle = 0; STAFRC_t rc = STAFRegister(myName, &myHandle);
The STAFRegisterUTF8 API is identical in all respects with STAFRegister, except that handleName is a string in UTF-8 format. This API is used primarily by the Java interfaces.
The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.
STAFRC_t STAFUnRegister(STAFHandle handle)
handle is the handle that you received on the call to STAFRegister.
/* myHandle was previously set by STAFRegister */ STAFRC_t rc = STAFUnRegister(myHandle);
The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.
STAFRC_t STAFSubmit(STAFHandle handle, char *where, char *service,
char *request, unsigned int requestLength,
char **resultPtr, unsigned int *resultLength);
handle is the handle you received on the call to STAFRegister.
where points to a string containing the destination machine for the service request. This should be either LOCAL or the name of a machine.
service points to the name of the service to which you are submitting the request.
request points to the actual request that you are sending to the service. This request may contain NULL (0x00) bytes.
requestLength indicates the length of the request buffer passed in.
resultPtr points to a char * that will contain the address of the result on return from the function. If, on return from STAFSubmit, *resultPtr is not 0, you must use STAFFree to free the result, even if the return code from STAFSubmit was non-zero. Note, if resultPtr is non-zero, then the buffer that resultPtr points to will always be NULL terminated. However, this buffer may contain NULL (0x00) bytes, therefore, it is not safe to determine the length of the buffer via strlen(). Instead, you should use the length provided by resultLength below.
resultLength points to an unsigned int which, on return from STAFSubmit, will contain the length of the result buffer.
/* myHandle was previously set by STAFRegister */ char *someMachine = "testmach1"; char *service = "PING"; char *request = "PING"; unsigned int requestLength = strlen(request); char *result = 0; unsigned int resultLength = 0; STAF