STAF V2 User's Guide

Software Testing Automation Framework (STAF) User's Guide
Version 2.6.11

18 Apr 2006


Table of Contents

1.0 Overview

  • 1.1 Requirements
  • 2.0 Concepts

  • 2.1 Handles
  • 2.2 Services
  • 2.3 Workloads
  • 2.4 Variables
  • 2.5 Security
  • 2.6 Queues
  • 2.7 Strings and Codepages
  • 3.0 Installation

  • 3.1 Registering STAF
  • 3.2 Reinstalling/Migrating
  • 3.3 Windows installation
  • 3.4 Unix installation
  • 3.5 Linux installation
  • 3.6 HP-UX IA64 64-bit installation
  • 3.7 AS/400 installation
  • 3.8 z/OS installation
  • 3.9 Environment Variable Settings
  • 3.10 Installation Problems
  • 4.0 Configuration

  • 4.1 Comments
  • 4.2 Machine Name
  • 4.3 Network Interfaces
  • 4.4 Service Registration
  • 4.5 Service Loader Registration
  • 4.6 Operational parameters
  • 4.7 Variables
  • 4.8 Trust
  • 4.9 Start/Shutdown Notifications
  • 4.10 Tracing
  • 4.11 Configuration File Example
  • 4.12 Tuning
  • 5.0 Commands

  • 5.1 STAFProc
  • 5.2 STAF
  • 5.3 STAF.cmd
  • 5.4 CSTAF
  • 6.0 API Reference

  • 6.1 C
  • 6.2 C++
  • 6.3 Rexx
  • 6.4 Java
  • 7.0 Services overview

  • 7.1 General Service Syntax
  • 7.2 Option Value Formats
  • 7.3 Variable Resolution
  • 7.4 Service Help
  • 7.5 Service list
  • 8.0 Service reference

  • 8.1 Delay Service
  • 8.2 Diagnostics (DIAG) Service
  • 8.3 Echo Service
  • 8.4 File System (FS) Service
  • 8.5 Handle Service
  • 8.6 Help Service
  • 8.7 Log Service
  • 8.8 Misc Service
  • 8.9 Monitor Service
  • 8.10 Ping Service
  • 8.11 Process Service
  • 8.12 Queue Service
  • 8.13 Resource Pool (ResPool) Service
  • 8.14 Remote Log Service (RLog)
  • 8.15 Semaphore (SEM) Service
  • 8.16 Service Service
  • 8.17 Shutdown Service
  • 8.18 Trust Service
  • 8.19 Variable (VAR) Service
  • 8.20 Zip Service
  • 9.0 Generic Workload Processor

  • 9.1 GenWL Syntax
  • 9.2 Workload Definition File
  • 9.3 Notes on querying a workload
  • 9.4 GenWL Example
  • 10.0 Utilities

  • 10.1 Format Log Utility
  • 11.0 STAF V3.0 Migration Preparation

    Appendix A. API Return Codes

    Appendix B. Service Command Reference

    Appendix C. Samples Descriptions

    Appendix D. Code Samples and Snipets

  • D.1 Java
  • D.2 Rexx
  • D.3 C
  • D.4 C++
  • Index

    End Of Document


    1.0 Overview

    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.


    1.1 Requirements

    1.1.1 Operating System

    STAF is supported on the following operating systems


    2.0 Concepts


    2.1 Handles

    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.


    2.2 Services

    Services are what provide all the capability in STAF. Services may be internal services, in which case, the executable code for the service resides within STAFProc. Services may also be external services, in which case, the executable code for the service resides outside of STAFProc, for example, in a Java routine.

    Services are known by their name, such as PROCESS or LOG. Internal services are always available and have a fixed name. External services must be registered, and the name by which they are known is specified when they are registered. If an external service is not registered with STAF, then the service is not available on that STAF Client.

    Services may also be delegated to another STAF Client. In this case, when a request is made for the service on the local STAF Client, it is automatically forwarded to the machine to which this service has been delegated. For example, a testcase may request the local machine to log some information via the LOG service. If the LOG service has been delegated to another machine, the LOG request will actually be handled by the machine to which logging has been delegated. In this way, all logs could be conviently stored on one system, without the testcases needing to explicitly send their LOG requests to the common system. In a similar manner, if a service were only available on a specific operating system, then all testcases could assume that the service was available locally, when, in fact, the service was being delegated to the machine running the required operating system.

    Note: Internal services may not be delegated.

    External services and delegated services are both registered in the STAF Configuration File. External services also may be dynamically added (registered) or removed (unregistered and terminated) via the SERVICE service (see 8.16, "Service Service").

    Service loaders are external services whose purpose is to load services on-demand. They allow services to be loaded only when they have been requested, so they don't take up memory until needed. They also allow dynamic service registration when a request is made so that you don't have to change the STAF configuration file to register a service.

    When a request is encountered for a service that doesn't exist, STAF will call each service loader, in the order they were configured, until the service exists or we run out of service loaders. If we run out of service loaders, then the standard RC:2 will be returned. Otherwise, the request will be sent to the newly added service.

    A default serviceloader service (STAFDSLS) is shipped with STAF, and it can dynamically load the Log, Monitor, ResPool and Zip services. This service will automatically be configured in your STAF.cfg file.


    2.3 Workloads

    A workload is a set of processes running on a set of machines. A workload may be as simple as a single process running on a single machine, or it may be as complex as multiple processes on multiple machines coordinating together to perform a larger complex task. STAF was designed to help the creation and automation of workloads of all sizes. STAF provides a Generic Workload Processer (see 9.0, "Generic Workload Processor"), which is capable of starting, stopping, and querying many kinds of workloads.


    2.4 Variables

    STAF provides a means to store and retrieve variables. These variables may be used for any purpose the tester desires, such as storing testcase configuration parameters. These variables provide two main capabilities to testcase writers. One, they provide a standard means by which to store configuration data, i.e., each tester doesn't have to figure out how to store and retrieve said configuration data. Two, these variables may be changed dynamically. For example, if a testcase queries the WebServer variable before sending a request off to the web server, and that web server goes down, the WebServer variable can be dynamically changed by the tester to refer to a different web server, and the testcase can continue execution. Note how STAF allows the variable's value to be changed outside of the scope of the running testcase, thus allowing the testcase to continue execution without needing to be stopped and restarted.

    STAF maintains a global variable pool that is common to all the processes on a given STAF Client. Each process/handle has its own variable pool. By default, the values of variables in a process' variable pool override the values of variables in the global variable pool. However, the process may override this behavior when asking for the value of a variable.

    The following global variables are predefined:

    2.4.1 The Basics of Variable References

    To substitute a variable's value, write the name of the variable in curly braces: "{STAF/Config/OS/Name}" is a valid reference to the variable STAF/Config/OS/Name. Assuming STAF/Config/OS/Name=Win2000, string "Operating system is {STAF/Config/OS/Name}" resolves to "Operating system is Win2000".

    Variable references can be used in many places when submitting a STAF request. For example:

    See section 8.19, "Variable (VAR) Service" for more information on setting and resolving variables.


    2.5 Security

    Security in STAF is defined at the machine level. In other words, you grant access to machines as oppossed to userids. Access in STAF is granted by specifying a certain trust level for a machine, where trust level 0 indicates no access and trust level 5 indicates all access. Each service in STAF defines what trust level is required in order to use the various functions the service provides.

    Note: The local machine is always at trust level 5 with respect to itself.

    A basic description of each level follows


    2.6 Queues

    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.


    2.7 Strings and Codepages

    The requests submitted to STAF and the results received from STAF are all strings. These strings may contain any arbitrary set of characters, including the NULL (i.e., 0) character. When working in an environment with a heterogeneous set of codepages, STAF will translate the request and result strings from and to the necessary codepages. This ensures that the request and result strings are not misinterpreted by the receiver.

    In general, when using STAF services, there shouldn't be any round trip problems. "Round trip" in this context means when all requests are originating from the same system, even if the requests are sent to, and the data is stored on, a system with a different codepage. However, if you send, for example, a request to log data containing Japanese codepage specific characters to any system and then query the log from a system using a US English codepage, you won't get the "correct" data, as that is not a valid "round trip".

    Note: All STAF generated strings are composed of only ASCII-7 characters and will safely survive the translation from/to different codepages.

    Caution: If you use a STAF service that is written in REXX, it can have round trip codepage translation problems. All of STAF services currently provided are written in C++/Java so they do not have this problem.

    2.7.1 Windows Codepage Translation Anomalies

    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:

    Note: To see the codepage that STAF is using, check the value of STAF variable STAF/Config/CodePage. For example:

        STAF testmach1 VAR RESOLVE {STAF/Config/CodePage}
    


    3.0 Installation


    3.1 Registering STAF

    By default, the first time STAF starts after installation, it will automatically register with IBM Austin. This is of particular importance, as keeping an accurate count of the number of users and systems using STAF helps to ensure the continued support of STAF, as well as, providing compelling evidence for other groups to adopt STAF. When installing STAF, you may optionally include your name, e-mail address, and organization. This allows us to send you information about updates to STAF, as well as allowing us to better understand which types of groups are benefitting from STAF. If you are installing large numbers of STAF systems, we don't expect you to continually enter this information. We would ask that you enter this information only once.

    While STAF registration is enabled by default, all of the installers allow you to bypass this registration. Please see the installation section for your specific platform.


    3.2 Reinstalling/Migrating

    If you want to reinstall STAF or migrate to a newer version of STAF, you must uninstall STAF first and then perform an install. An uninstall of STAF will only remove the files that the STAF install created. Any files created after STAF was installed (e.g. additional services, log files, updated STAF.cfg, etc) will not be removed. The STAF.cfg file will be backed up to file STAF.cfg.ismp.bak by the STAF install (if you perform a InstallShield MultiPlatform install).


    3.3 Windows installation

    3.3.1 Installing Using InstallShield MultiPlatform

    STAF provides the following two methods to install STAF on Windows. Both methods use MultiPlatform InstallShield:

    You will be guided through the following steps:

    1. On the Welcome panel, click Next to continue.

    2. On the next panel, carefully read the license agreement. If you accept the terms of the license agreement, click on "I accept the terms of the license agreement", and then click on Next.

    3. If you already have any version of STAF installed, a panel is displayed indicating that you must first uninstall STAF.

    4. Click Next to install STAF to the default directory, or click Browse to install STAF to a different directory.

    5. Choose the type of install that best suits your needs:

    6. Choose options for the install:

    7. If you selected to place icons on the "Start Programs" menu, you will be asked to specify the program folder name where the icons will be placed or you may use the default folder name. Click Next to continue.

    8. A panel will be displayed so you can review your installation options. If you want to change anything, click Back. Otherwise, click Next to start copying files.

    9. When the install is complete, you should get a message that the InstallShield Wizard has successfully installed STAF. On Windows NT/2000/XP/2003 systems, click Finish to exit the wizard. On Windows 95/98/ME systems, you will get a message that you must restart your system to complete the installation.

    3.3.2 Uninstalling STAF

    To uninstall STAF on Windows systems, open the Control Panel and double click on the "Add/Remove Programs" icon. Scroll down through the list of installed programs and select "STAF - Software Testing Automation Framework" and click on the "Add/Remove..." button. When uninstalling STAF 2.3 and later (when it was installed using InstallShield MultiPlatform), all STAF features will be uninstalled; you cannot choose which features to uninstall. Also, any files created after STAF was installed will not be removed.

    Note that beginning with STAF 2.6.6, if you selected to place icons on the "Start Programs" menu during the installation, there will also be an "Uninstall STAF" icon in the program folder name you specified. You can also use this icon to uninstall STAF on Windows systems.

    When uninstalling STAF 2.2 or earlier, when you click on the "Add/Remove..." button, a panel will be displayed asking whether you want to completely uninstall STAF or prepare for a reinstallation of STAF. The latter choice should be used if you are planning to reinstall STAF on this system. Select the option that you want and click Ok.

    You must uninstall STAF before reinstalling STAF. Please see 3.2, "Reinstalling/Migrating" for more information.

    3.3.3 Performing a Silent Installation or Uninstallation of STAF

    If you need to install or uninstall the same STAF configuration multiple times or in multiple locations, you can bypass the ISMP Installer GUI and perform a silent installation or uninstallation to save time.

    Silent Installation

    In a silent installation, STAF will be installed with the default options. To perform a silent installation on Windows, issue the following command:

      STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept"
    
    or
      java -Dis:debug=1 -jar STAF2611-setup-win32.jar -silent -W license.selection="Accept"
    

    After performing a silent installation of STAF on Windows 95/98/ME systems, you must restart your system to complete the installation (e.g. sets environment variables for STAF).

    You can also use a response file for the responses you normally specify manually when you run the ISMP Installer GUI. To create a response file, you can run a non-silent installation, specifying the response file name, and select the responses during the installation:

      STAF2611-setup-win32 -options-record settings.txt 
    

    To specify a response file for a silent STAF installation, issue the following command:

      STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept" -options settings.txt
    

    You can also override installation settings when doing a silent installation. For example, to install STAF with the default options, except for specifying a different install location, issue the following command:

      STAF2611-setup-win32 -is:log c:\temp\ismplog.txt -silent -W license.selection="Accept" -W stafinstalldirectory.defaultInstallLocation="C:\tools\staf"
    

    The following table shows the most commonly-used "-W" silent install options:

    Table 1. -W silent install options
    Option Default Value Description
    -W license.selection= N/A Specify the value "Accept" to indicate that you have read the STAF license agreement and that you accept the terms of the license agreement. You are required to use this option and set the value to "Accept".
    -W stafinstalldirectory.defaultInstallLocation= "C:\STAF" The directory in which STAF should be installed.

    Silent Uninstallation

    The silent uninstallation uninstalls all STAF components. To perform a silent uninstallation, issue the following command:

      ProductDir/_uninst/uninstaller -silent
    

    3.3.4 Installing STAF as a Windows service

    If you wish to have STAFProc start automatically on Windows when the operating system is rebooted (without requiring a user to log on to Windows), you can install STAF as a Windows service.

    These instructions assume you have copied INSTSRV.EXE and SVRANY.EXE (available from the Windows Resource Kit) into C:\WINNT\SYSTEM32.

    1. Create a base STAF service which by default is started automatically when the system boots.
      instsrv STAF c:\winnt\system32\srvany.exe
      

    2. Start the Windows Registry Editor by typing regedit and find:
      My Computer\HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\STAF
      

    3. Create a new string value with the name Description. Set the value to Automatically start STAF service.

    4. Create a new Key with name Parameters. Inside the new key, create a new string value with the name Application and set the value to c:\staf\bin\stafproc.exe.

    5. Close the Registry Editor.

    6. If on Windows 2000, open the following program:
      Start > Programs > Administrative Tools > Services
      

    7. If on Windows 2000 Terminal Server, open the following program:
      Start > Programs > Administrative Tools > Management Console (Windows 2000 Terminal Server)
      Services and Applications > Services
      

    8. If on Windows XP Professional, open the following program:
      Start > Settings > Control Panel > Administrative Tools > Services
      

    9. Locate STAF, right click on the STAF entry, and select Properties.

    10. From the 'Log On' tab, click 'Allow service to interact with desktop', then click on Apply and then click on OK.

    11. Next, type:
      net start staf
      

    12. Check that STAF is now running from a command prompt:
      staf local ping ping
      

    13. Note that when running STAF as a Windows service, you should not have STAFProc automatically start when users log on to Windows. You should either deselect the "Start STAF on user login" option when installing STAF, or delete STAF from Start > Programs > Startup folder.

    14. Note that STAF should not be started or shutdown with the commands on the start menu when STAF is configured as a service.

    3.4 Unix installation

    3.4.1 Installing Using InstallShield MultiPlatform

    STAF provides the following two methods to install STAF on Unix using MultiPlatform InstallShield. All operating systems supported by STAF, except for Irix and AIX 4.3.2 or earlier, are supported by MultiPlatform InstallShield.

    You will be guided through the following steps:

    1. On the Welcome panel, click Next to continue.

    2. On the next panel, carefully read the license agreement. If you accept the terms of the license agreement, click on "I accept the terms of the license agreement", and then click on Next.

    3. Click Next to install STAF to the default directory, or click Browse to install STAF to a different directory.

    4. If you already have any version of STAF installed, a panel is displayed indicating that you must first uninstall STAF.

    5. Choose the type of install that best suits your needs:

    6. Choose options for the install:

    7. A panel will be displayed so you can review your installation options. If you want to change anything, click Back. Otherwise, click Next to start copying files.

    8. When the install is complete, you should get a message that the InstallShield Wizard has successfully installed STAF. You will get a message that you must logout and login to complete the installation.

    3.4.2 Performing a Silent Installation or Uninstallation of STAF

    If you need to install or uninstall the same STAF configuration multiple times or in multiple locations, you can bypass the ISMP Installer GUI and perform a silent installation or uninstallation to save time.

    Silent Installation

    In a silent installation, STAF will be installed with the default options. To perform a silent installation on Unix, issue the following command (where xxxxx is the operating system, such as "linux", "aix", etc.):

      STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept"
    
    or
      java -Dis:debug=1 -jar STAF2611-setup-xxxxx.jar -silent -W license.selection="Accept"
    

    After performing a silent installation of STAF, be sure to logout and login to complete the installation (e.g. sets environment variables for STAF).

    You can also use a response file for the responses you normally specify manually when you run the ISMP Installer GUI. To create a response file, you can run a non-silent installation, specifying the response file name, and select the responses during the installation:

      STAF2611-setup-xxxxx.bin -options-record settings.txt 
    

    To specify a response file for a silent STAF installation, issue the following command:

      STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept" -options settings.txt
    

    You can also override installation settings when doing a silent installation. For example, to install STAF with the default options, except for specifying a different install location, issue the following command:

      STAF2611-setup-xxxxx.bin -is:log /tmp/ismplog.txt -silent -W license.selection="Accept" -W stafinstalldirectory.defaultInstallLocation="/tools/staf"
    

    The following table shows the most commonly-used "-W" silent install options:

    Table 2. -W silent install options
    Option Default Value Description
    -W license.selection= N/A Specify the value "Accept" to indicate that you have read the STAF license agreement and that you accept the terms of the license agreement. You are required to use this option and set the value to "Accept".
    -W stafinstalldirectory.defaultInstallLocation= "C:\STAF" The directory in which STAF should be installed.

    Silent Uninstallation

    The silent uninstallation uninstalls all STAF components. To perform a silent uninstallation, issue the following command:

      ProductDir/_uninst/uninstaller.bin -silent
    

    3.4.3 Installing Using STAFInst

    A single gzipped or compressed tar file is provided for Unix systems. For some platforms that are not supported by InstallShield MultiPlatform, such as Linux IA-64, Linux AMD-64, z/OS, AS/400, Irix, etc, this is the only install file provided. Before installing STAF, you will need to gunzip the gzipped tar file or uncompress the compressed tar file and then untar it into a temporary directory from which you will later run the STAFInst commmand. Note that when you untar the file, it will expand into a single directory named "staf" that will contain the installation files and directories.

    For example, assuming you downloaded the gzipped tar file for Linux IA64 into a temporary directory named /tmp/STAF,

    cd /tmp/STAF
    gunzip STAF2611-linux-ia64.tar.gz
    tar -xvf STAF2611-linux-ia64.tar
    cd staf
    

    Or, for example, assuming you downloaded the compressed tar file for z/OS into a temporary directory named /tmp/STAF,

    cd /tmp/STAF
    compress -d STAF2611-zos.tar.Z
    tar -xvf STAF2611-zos.tar
    cd staf
    

    Note that you can delete this temporary directory (e.g. /tmp/STAF) after you have run the STAFInst command to install STAF to it's target directory.

    Optionally, you may prefer to untar STAF on one system and mount the installable images from other systems.

    Once the STAF installation image is ready, you should run the STAFInst command. The syntax is as follows.

    Usage: STAFInst [-source <source path>] [-target <target path>]
           [-bin <directory>] [-lib <directory>] [-preview]
           [-type < m<s<o>> | r<s<o>> | f<s<o>> >] [-verbose] [-warn]
           [-ro <mode>] [-rx <mode>] [-rw <mode>] [-dp <mode>]
           [-noreg | [-name <name>] [-email <email>] [-org <org>]]
    

    -source specifes the directory in which the STAF files were untar'd. In our example above, this would be /tmp/STAF. The default is the current directory. If you are not running STAFInst from the directory in which STAFInst resides, you must specify -source.

    -target specifes where STAF will be installed. The default is /usr/local/staf.

    -bin specifies the directory where softlinks to executables will be created. The default is /usr/bin.

    -lib specifies the directory where softlinks to libraries will be created. The default is /usr/lib.

    -type specifies the type of installation (the default is rs). Possible values are

    Any of these options may be suffixed with 's' to indicate that appropriate softlinks should be created in the directories specified by the -bin and -lib options. You may further append 'o' to indicate that only softlinks should be created. That is, no files will be copied. This is useful when you simply wish to create softlinks to a remotely shared copy of STAF. Note, if you perform a softlink-only install, the STAFUninst script (see 3.4.6, "Starting STAF automatically during reboot") will still be created in the directory specified by -target.

    -verbose specifies that all operations performed by STAFInst should be displayed to the user.

    -warn specifies that STAFInst should stop execution if it encounters a warning condition. An example of a warning condition is trying to copy or link a non-existant file. Normally, these warning conditions are printed and execution continues.

    -preview displays the intended actions of STAFInst without touching the file system.

    -ro allows you to specify the mode bits for STAF files intended to be read-only. The default is 444.

    -rx allows you to specify the mode bits for STAF files intended to be read-execute. The default is 555.

    -rw allows you to specify the mode bits for STAF files intended to be read-write. The default is 664.

    -dp allows you to specify the mode bits for the directories STAF creates. The default is 775.

    -noreg prevents STAF from automatically registering with IBM Austin. This option is highly discouraged. Please see 3.1, "Registering STAF" for more information.

    -name allows you to specify the name STAF uses when registering. The default is the empty string.

    -email allows you to specify the e-mail address STAF uses when registering. The default is the empty string.

    -org allows you to specify the organization STAF uses when registering. The default is the empty string.

    IMPORTANT! In order to start STAF or to use STAF, you must make set some environment variables as described in section 3.9, "Environment Variable Settings". STAFInst does not update these environment variables for you.

    It is recommended that you start STAFProc (see 5.1, "STAFProc") as root. This is to ensure that the Process and File System services will have full access to the system.

    3.4.4 Examples using STAFInst

    For the following examples, assume the STAF installation image is in /tmp/STAF and your current directory is also /tmp/STAF.

    To take all the defaults, which will perform a recommended install of STAF into /usr/local/staf and create softlinks in /usr/bin and /usr/lib, you would simply enter

    ./STAFInst
    

    To perform a recommended install of STAF into /usr/local/staf, but have the softlinks placed into usr/local/bin and /usr/local/lib, you would enter

    ./STAFInst -bin /usr/local/bin -lib /usr/local/lib
    

    To perform a minimum installation of STAF into /opt/staf without any softlinks, you would enter

    ./STAFInst -target /opt/staf -type m
    

    To perform a preview of a full STAF installation into the default /usr/local/staf with default softlinks in /usr/bin and /usr/lib, you would enter

    ./STAFInst -type fs -preview
    

    To perform a default install of STAF and provide your name and e-mail address for registration, you would enter

    ./STAFInst -name "Your name" -email "Your e-mail address"
    

    To install STAF in the default locations but change read-only permissions to 440, read-execute permissions to 550, read-write priveleges to 660, and directory permissions to 770, you would enter

    ./STAFInst -ro 440 -rw 550 -rw 660 -dp 770
    

    3.4.5 Uninstalling STAF

    When STAF is installed on Unix systems, a script called STAFUninst is created which can be used to uninstall STAF. This file is created in the directory where you installed STAF (default is /usr/local/staf). All STAF features will be uninstalled; you cannot choose which features to uninstall. However, only the files and softlinks that the STAF install created will be removed. Any files created after STAF was installed will not be removed.

    If STAF was installed using InstallShield MultiPlatform, you will be prompted to logout to complete the uninstall.

    You must uninstall STAF before reinstalling STAF. Please see 3.2, "Reinstalling/Migrating" for more information.

    3.4.6 Starting STAF automatically during reboot

    You can have STAF start automatically during reboot on Unix machines by using a script file similar to the following:

    #!/bin/sh
    PATH=/usr/local/staf/bin:$PATH
    export PATH
    LD_LIBRARY_PATH=/usr/local/staf/lib
    export LD_LIBRARY_PATH
    CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar
    export CLASSPATH
    STAFCONVDIR=/usr/local/staf/codepage
    export STAFCONVDIR
    STAFCODEPAGE=LATIN_1
    export STAFCODEPAGE
    nohup /usr/local/staf/bin/STAFProc > /usr/local/staf/stafproc.out
    

    If you did not install STAF to the default directory (/usr/local/staf), then you would need to specify the non-default installation directory in the script file.

    Note that on AIX, you need to replace LD_LIBRARY_PATH with LIBPATH, and on HP-UX, you need to replace LD_LIBRARY_PATH with SHLIB_PATH.

    Note that if your Unix operating system does not support the "nohup" command, then remove it from the last line in the script:

    /usr/local/staf/bin/STAFProc > /usr/local/staf/stafproc.out
    

    The console output from STAFProc will be stored in the /usr/local/staf/stafproc.out file.

    The usage of this script file varies depending on the specific Unix operating system:

    You may get the following error message:

    STAFProcess::processMonitorThread: error opening /dev/tty, errno: 6
    

    However, STAFProc does start despite this message, and functions normally.


    3.5 Linux installation

    Note, when you are running STAF on Linux RedHat 9.0 or later, you may encounter a Segmentation Fault every time you execute the STAF executable. To work around this problem, set the following environment variable:

    LD_ASSUME_KERNEL=<kernel-version>
    

    The following versions can be specified for <kernel-version>


    3.6 HP-UX IA64 64-bit installation

    Note, if you plan to use Java services, or STAF-enabled Java applications with the 64-bit version of STAF for HP-UX IA64, you must use Java 1.4.1 or later. For more information see 4.4.3, "JSTAF service proxy library".


    3.7 AS/400 installation

    3.7.1 Setup instructions for STAF on AS/400

    Note: STAF will only run on AS/400 V5R2 or newer.


    3.8 z/OS installation

    3.8.1 Setup instructions for STAF on z/OS

    Note: STAF will only run on z/OS V1.4 or newer. STAF's Java support on z/OS requires JDK 1.4.1 or newer.

    To install STAF on z/OS, you should follow the steps described in 3.4.3, "Installing Using STAFInst".

    It is critical that you remember to make set the _CEE_RUNOPTS environment variable. Failure to set this variable will prevent STAF from working properly. The proper setting should be

    _CEE_RUNOPTS="posix(on)"
    

    If you did not install STAF in the default /usr/local/staf directory, STAFCONVDIR must be be set to the STAF codepage directory.


    3.9 Environment Variable Settings

    STAF requires setting some environment variables to run. If you performed an InstallShield install and selected an option to have the install update the environment variables, these environment variables should already be updated for STAF. Otherwise, you must set these environment variables yourself. In most cases, you'll probably want to set these environments for the system so that they are always set even after logging out or rebooting.

    Please verify that the following environment variables have been set as follows before using STAF:


    3.10 Installation Problems

    If you have a problem while installing STAF, please check the STAF V2 FAQ at http://staf.sourceforge.net/current2x/STAFFAQ.htm, particularly section 3.2 "STAF Install Questions" under section 3 "Debugging STAF".

    If you have a problem starting STAFProc, please be sure that the necessary environment variables have been set for STAF (see section 3.9, "Environment Variable Settings"). Also, check the STAF V2 FAQ at http://staf.sourceforge.net/current2x/STAFFAQ.htm.


    4.0 Configuration

    STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF Configuration File is read and processed line by line. Whitespace at the front of the line is removed before processing. Blank lines, or lines containing only whitespace are ignored. You may continue a configuration statement onto the next line by placing a "\" as the last character of the line. The maximum length for a line in the STAF Configuration File is 2048 characters. The various configuration statements are described in the following sections.

    You may use variables for all the values of configuration statement options, with the exception of the VAR configuration statement itself. However, these variables must be either predefined STAF variables (see 2.4, "Variables") or be previously defined in the STAF Configuration File via the VAR configuration statement (see below).


    4.1 Comments

    4.1.1 Description

    You specify a comment by placing a pound sign, #, as the first character on the line. Comment lines are ignored.

    Examples

    # This is a comment line
    

    4.2 Machine Name

    4.2.1 Description

    You may specify the name by which your machine is known by using the MACHINE configuration statement. This option is used in a disconnected mode.

    Note: The MACHINE and INTERFACE configuration statements are mutually exclusive.

    Syntax

    MACHINE <Name>
    

    <Name> is the name you wish to use for your machine. It is case sensitive.

    Examples

    MACHINE Office
    

    4.3 Network Interfaces

    4.3.1 Description

    You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement.

    Note: The MACHINE and INTERFACE configuration statements are mutually exclusive.

    Note: Currently, the only supported network interface is TCP/IP.

    Syntax

    INTERFACE TCPIP [Port]
    

    [Port] is the TCP/IP port on which to listen for connections. The default is 6500. All machines in the same STAF Environment must use the same port.

    Examples

    INTERFACE TCPIP
    INTERFACE TCPIP 6600
    

    4.4 Service Registration

    4.4.1 Description

    External services are registered with the SERVICE configuration statement.

    Syntax

    SERVICE <Name> LIBRARY <Implementation library> [EXECUTE <Executable>]
                   [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    or

    SERVICE <Name> DELEGATE <Machine> [TONAME <Remote Service Name>]
    

    <Name> is the name by which this service will be known on this machine.

    LIBRARY is the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the REXX script or Java jar file which actually implements the service. This option has no significance for non-proxy service libraries. See below for information regarding the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documentation provided by the service proxy library.

    OPTION specifes a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See below for acceptable options for the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service during initialization.

    DELEGATE specifies the machine to which to delegate this service.

    TONAME is the name of the service on <Machine> to which the delegated requests will be sent. The default is the same name as specified with <Name>

    Examples

    SERVICE MONITOR LIBRARY STAFMon PARMS "RESOLVEMESSAGE MAXRECORDSIZE 4096"
    SERVICE LOG     LIBRARY STAFLog
    SERVICE SAMPLER LIBRARY RXSTAF EXECUTE C:\STAF\bin\Sample.cmd PARMS "Sample Data"
    SERVICE STAX    LIBRARY JSTAF  EXECUTE C:\STAF\service\STAX.jar \
                    OPTION J2=-Xmx128m
    SERVICE SAMPLEJ LIBRARY JSTAF  EXECUTE C:\STAF\services\Sample.jar \
                    PARMS {STAF/Config/STAFRoot}\bin\sample.dft
    SERVICE MYLOG   DELEGATE TestSrv1
    SERVICE PAGER   DELEGATE pagesrv.austin.ibm.com
    SERVICE EVENT   DELEGATE EventSrv TONAME DB2EVENT
    SERVICE NOTIFY  LIBRARY Notify PARMS "24 Hours 7 Days"
    SERVICE ZIP     LIBRARY STAFZip
    

    4.4.2 RXSTAF service proxy library

    The library RXSTAF acts as a proxy for STAF services implemented in the REXX language.

    The EXECUTE option for a Rexx service should specify the full path to the Rexx script that implements the service.

    RXSTAF supports the following OPTIONs:

    DEBUG specifies that Rexx service code should be re-read for every service request, thus, allowing debugging without stopping STAFProc. If this option is not specified, the Rexx service code is read in once at initialization time and a tokenized image is created. This tokenized image is used for all service requests, and any changes to the Rexx service code will not be reflected until STAFProc is stopped and started again.

    Warning: Using the DEBUG option will degrade the service's performance.

    Examples

    OPTION Debug
    

    4.4.3 JSTAF service proxy library

    The library JSTAF acts as a proxy for STAF services implemented in the Java language. JSTAF works with Java 1.2 and above.

    The EXECUTE option for a Java service should specify the fully-qualified name of the jar file that implements the service. The jar file will be automatically added to the class path by JSTAF.

    Note: In versions of STAF prior to 2.4.0, the name of the Java class that implements the service was specified for the EXECUTE option and you had to make sure that the service's class files were in the class path. This is still supported, but this method is deprecated and will be removed in a future version of STAF.

    JSTAF supports the following OPTIONs:

    JVMName=<Name> specifies the name for the JVM you want the Java service to run in. If the JVM does not already exist, it will be created. If no JVMName is specified, then the Java service will run in the default JVM, named STAFJVM1, which is created the first time a Java service is registered with no JVMName specified. This option allows JSTAF to run Java services in different JVMs.

    JVM=<Executable> specifies the name of the desired Java executable. The default is "java". Note, this option is only valid for the first service created with a given JVMName.

    Note: The HP-UX IA64 64-bit version of STAF requires Java 1.4.1 or later.

    J2=<Java option> specifies an arbitrary Java option that should be passed to the JVM. You can find more information on these options by using the command "java" (for standard options) and "java -X" (for non-standard options), or by consulting your Java documentation. Note that -X options can vary depending on which Java implementation (e.g. Sun Java 1.4.0 vs IBM Java 1.3.1) you installed. Note, this option is only valid for the first service created with a given JVMName.

    Note: If you are using the HP-UX IA64 64-bit version of STAF, you must specify the -d64 option to the JVM. This can be done by specifying J2=-d64

    MAXLOGS=<Number> specifies the maximum number of log files for the JVM that should be saved. The default is 5. The JVM log files are stored in the {STAF/Config/STAFRoot}/data/JSTAF/<JVMName> directory and contain JVM start information such as the date/time when the JVM was started, the JVM executable, and the J2 options used to start the JVM. In addition, it contains any other information logged by the JVM, including any errors that may have occurred while the JVM was running. The current JVM log file is named JVMLog.1 and saved JVM log files, if any, are named JVMLog.2 to JVMLog.<MAXLOGS>. Note, this option is only valid for the first service created with a given JVMName.

    MAXLOGSIZE=<Number> specifies the maximum size, in bytes, for the JVM log file(s). The default is 1048576 (1M). This option determines when to create a new JVM log file. When the JVM is started, if the size of a JVM log file exceeds the maximum size specified by this option, a new JVM log file will be created. Note, this option is only valid for the first service created with a given JVMName.

    Examples

    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
    

    4.5 Service Loader Registration

    4.5.1 Description

    Service loaders are registered with the SERVICELOADER configuration statement.

    Syntax

    SERVICELOADER LIBRARY <Implementation library> [EXECUTE <Executable>]
                  [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    LIBRARY is the name of the shared library / DLL which implements the service loader or acts as a proxy for the service loader. See the information for each service loader to determine the appropriate value for this option.

    EXECUTE is used by service loader proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the REXX script or Java jar file which actually implements the service loader. This option has no significance for non-proxy service loader libraries. See the Service Registration section for information regarding the RXSTAF and JSTAF service proxy libraries.

    OPTION specifes a configuration option that will be passed on to the service loader library / DLL. This is typically used by service loader proxy libraries to further control the interface to the actual service loader implementation. You may specify multiple OPTIONs for a given service loader. See the Service Registration section for acceptable options for the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service loader during initialization.

    Examples

    SERVICELOADER LIBRARY STAFDSLS
    SERVICELOADER LIBRARY JSTAF EXECUTE C:\STAF\services\CustomServiceLoader.jar
    

    4.6 Operational parameters

    4.6.1 Description

    STAFProc allows you to set various parameters which affect the general operation of STAF, such as the amount of time to wait for a successful connection to another system. The SET configuration statement lets you set these general operational parameters.

    Syntax

    SET [CONNECTTIMEOUT <Number>] [CONNECTATTEMPTS <Number>] [CONNECTRETRYDELAY <Number>]
        [MAXFILES <Number>] [MAXQUEUESIZE <Number>]
        [USELONGNAMES] [INITIALTHREADS <Number>] [THREADGROWTHDELTA <Number>]
        [ENABLEDIAGS]
        [DEFAULTSTOPUSING <Method>] [DEFAULTNEWCONSOLE | DEFAULTSAMECONSOLE]
        [PROCESSAUTHMODE <Authentication Mode>]
        [DEFAULTAUTHUSERNAME] [DEFAULTAUTHPASSWORD]
        [DEFAULTAUTHDISABLEDACTION <Disabled Action>]
        [DEFAULTSHELL <Shell>]
        [DEFAULTNEWCONSOLESHELL <Shell>] [DEFAULTSAMECONSOLESHELL <Shell>]
    

    CONNECTTIMEOUT specifies the maximum time in milliseconds to wait for a connection attempt to a remote system to succeed. The default is 5000 (i.e., 5 seconds). You may need to increase this value if you are consistently receiving return code 16 when trying to communicate with distant STAF systems. Note that the total time to wait for a connection to a remote system to succeed is (CONNECTTIMEOUT * CONNECTATTEMPTS) + (CONNECTRETRYDELAY * (CONNECTATTEMPTS - 1)). If using the defaults, the maximum total time to wait for a connection to a remote system to succeed is (5000 * 2) + (1000 * 1), which equals 11 seconds.

    CONNECTATTEMPTS specifies the maximum number of times to attempt to connect to a remote system. The default is 2. Note that a trace warning message is generated for each failed attempt if the Warning trace point is enabled.

    CONNECTRETRYDELAY specifies the maximum time in milliseconds to wait after a failed connection attempt to a remote system before trying to connect again (if the maximum number of times to attempt to connect to a remote system has not been reached yet). The default is 1000 (i.e., 1 second).

    MAXFILES specifies the maximum number of files STAFProc may have open. The default is 500.

    MAXQUEUESIZE specifies the maximum size of the queue associated with each process' handle. The default is 100.

    USELONGNAMES specifies that STAF should use full TCP/IP host names instead of the host name minus the domain name. By default, STAF uses short names (the first portion of the TCP/IP hostname) to track machine requests, grant access, etc. This may not be desirable in situations where you are using multiple TCP/IP domains which have duplicate short names across them, for example, server1.austin.ibm.com and server1.test.austin.ibm.com. If USELONGNAMES is set, a machine's effective machine name will be the entire TCP/IP host name (e.g., automate.austin.ibm.com), otherwise, a machine's effective machine name will be the first portion of the TCP/IP host name (e.g., automate).

    Note: Using long names can have implications for various external services. For example, the Log Service uses the effective machine name as part of the directory path when creating logs. This might result in a directory structure of C:\STAF\Logging\MACHINE\automate.austin.ibm.com\ which would require a file system which supports long names, such as HPFS.

    INITIALTHREADS specifies the number of threads initially created to handle service requests. The default is 5.

    THREADGROWTHDELTA specifies the number of additional threads which should be created when all existing threads are busy. The default is 1.

    ENABLEDIAGS specifies to enable diagnostics. The default is to disable diagnostics.

    Note: You may also enable (or disable) recording diagnostics dynamically using the DIAG service.

    DEFAULTSTOPUSING allows you to specify the default method used to STOP processes. See 8.11.3, "STOP" for more information on available methods.

    DEFAULTNEWCONSOLE specifies that processes should be STARTed in a new console window. This is the default for Win32 and OS/2. This option has no effect on Unix systems.

    DEFAULTSAMECONSOLE specifies that processes should be STARTed in the same console as STAFProc. This is the default on Unix systems. This option has no effect on OS/2.

    PROCESSAUTHMODE specifies the mode by which usernames/passwords are authenticated when starting processes. The value of this option is platform specific. Recognized values are the following

    Note: Previously, PASSWD and SHADOW were supported values for the PROCESSAUTHMODE on Unix systems, but support for for these modes has been removed.

    DEFAULTAUTHUSERNAME specifies the username under which processes will be started, by default. Note, this option IS valid even if process authentication has been disabled.

    DEFAULTAUTHPASSWORD specifies the password with which processes will be authenticated, by default. Note, this option IS valid even if process authentication has been disabled.

    DEFAULTAUTHDISABLEDACTION specifies what default action should be taken if the user specifies a username/password on a request to start a process when process authentication has ben DISABLED. The following values are recognized.

    DEFAULTSHELL specifies the default shell to use when starting a process via a separate shell. The default shell used for Unix systems is /bin/sh. The default shell used for Windows NT/2000/XP/2003 systems is "cmd.exe /c". The default shell used for Windows 95/98/ME systems is "command.com /c".

    DEFAULTNEWCONSOLESHELL specifies the default shell to use when starting a process in a new console window (e.g. NEWCONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified.

    DEFAULTSAMECONSOLESHELL specifies the default shell to use when starting a process in the same console as STAFProc (e.g. SAMECONSOLE) via a separate shell, overriding the DEFAULTSHELL value if specified.

    A shell value can contain substitution characters described in the following table.

    Table 3. Substitution Characters for Shells
    Substitution character Description Supported systems
    %c Substitute the values specified by the COMMAND and PARMS options. Win32 and Unix
    %C Same as %c, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %p Substitute the value specified by the PASSWORD option, or an empty string if no PASSWORD is provided. Win32 and Unix
    %P Same as %p, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %t Substitute the value specified by the TITLE option, or <Unknown> if no TITLE is provided. Win32 and Unix
    %T Same as %t, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %u Substitute the value specified by the USERNAME option, or an empty string if no USERNAME is provided. Win32 and Unix
    %U Same as %u, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %w Substitute the value specified by the WORKLOAD option, or <Unknown> if no WORKLOAD is provided. Win32 and Unix
    %W Same as %w, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %x Substitute the values specified by the COMMAND and PARMS options followed by input/output redirection, if I/O options are specified on the PROCESS START request (e.g. STDIN, STDOUT). When using this option, do not specify any redirection in the COMMAND/PARMS values. Win32 and Unix
    %X Same as %x, except the substituted value will be quoted (with all nested quotes properly escaped). Win32 and Unix
    %% Substitute a %. Win32 and Unix

    Notes:

    1. When specifying a shell value, it must contain one of the following: %c, %C, %x, %X.
    2. The use of %c versus %C, as well as %x versus %X, is highly dependent on the shell you specify. If the shell expects the command and parameters to be parsed as a single string, then use %C or %X. If the shell expects the command and parameters to be parsed as separate strings, then use %c or %x.
    3. Specifying 'su - %u -c %C' as the shell when starting a process on a UNIX system (so that it simulates the environment of the user specified by the USERNAME option) will cause variables specified via an ENV option to not be set for the process.

    Examples

    SET CONNECTTIMEOUT 15000
    SET CONNECTTIMEOUT 10000 CONNECTATTEMPTS 5 CONNECTRETRYDELAY 2000
    SET MAXFILES 1000 MAXQUEUESIZE 300
    SET USELONGNAMES
    SET INITIALTHREADS 10 THREADGROWTHDELTA 3
    SET ENABLEDIAGS
    SET DEFAULTSTOPUSING SIGTERM DEFAULTSAMECONSOLE
    SET PROCESSAUTHMODE windows DEFAULTAUTHUSERNAME testuser DEFAULTAUTHPASSWORD tupass
    SET PROCESSAUTHMODE none DEFAULTAUTHUSERNAME guest DEFAULTAUTHDISABLEDACTION error
    SET DEFAULTSHELL "C:/cygwin/bin/bash.exe -c %C"
    SET DEFAULTSAMECONSOLESHELL "/bin/csh -c %C"
    SET DEFAULTNEWCONSOLESHELL "xterm -title %T -e /bin/sh -c %X"
    SET DEFAULTSHELL "su - %u -c %C"
    

    4.7 Variables

    4.7.1 Description

    You may set global STAF variables at startup by using the VAR configuration statement.

    Syntax

    VAR <Name=Value>
    

    Name is the name of the variable.

    Value is the value of the variable.

    Examples

    VAR WebServer=testsrv1.test.austin.ibm.com
    VAR "Author=Jane Tester"
    VAR STAF/Service/Log/Directory={STAF/Config/BootDrive}\STAF\Log
    

    4.8 Trust

    4.8.1 Description

    You may grant access to machines by using the TRUST configuration statement.

    Warning: Trust is granted based on the effective machine name. If using short names, be aware that machines with identical hostnames but in different domains (e.g. automate.austin.ibm.com and automate.raleigh.ibm.com) will be treated as one in the same. To ensure that machines from multiple domains with the same short name appear as separate machines, set USELONGNAMES via the SET configuration statement.

    Syntax

    TRUST LEVEL <Level> <DEFAULT | MACHINE <Machine> [MACHINE <Machine>]  ...>
    

    LEVEL is the level of trust that you wish to grant, see 2.5, "Security" for a list of trust levels.

    DEFAULT indicates that you wish to set the default trust level. This is the trust level that will be used for machines which have no explicit trust level set. If no default has been specified in the STAF Configuration file, the default is set to 3.

    MACHINE indicates a specific machine for which to set a trust level.

    Examples

    If using short names:

    TRUST LEVEL 3 MACHINE client1 MACHINE client2 MACHINE client3
    TRUST LEVEL 5 MACHINE office
    TRUST LEVEL 0 MACHINE badguy
    TRUST DEFAULT LEVEL 1
    
    If using long names:
    TRUST LEVEL 3 MACHINE client1.austin.ibm.com MACHINE client3.austin.ibm.com
    TRUST LEVEL 2 MACHINE client1.raleigh.ibm.com
    TRUST LEVEL 5 MACHINE office.austin.ibm.com
    TRUST LEVEL 0 MACHINE badguy.austin.ibm.com
    TRUST DEFAULT LEVEL 1
    

    4.9 Start/Shutdown Notifications

    4.9.1 Description

    You may specify that you want notifications sent to certain machines/processes when STAF is either started or shutdown. You do this by using the NOTIFY configuration statement. Notifications are handled by the STAF Queue service, see 8.12, "Queue Service" for more information.

    Note: You may also dynamically register for SHUTDOWN notifications via the SHUTDOWN service, see 8.17, "Shutdown Service".

    Warning: In order for the receving machine to accept the notifications, it must specify a default or explicit trust level of at least 3 for this machine. As of version 2.2.0 of STAF, the default trust level is 3, so no explicit action is necessary on systems running this version of STAF (or higher).

    Syntax

    NOTIFY <ONSTART | ONSHUTDOWN> MACHINE <Machine> [PRIORITY <Priority>]
           <NAME <Name> | HANDLE <Handle>>
    

    ONSTART indicates that a notification should be sent when STAF is fully initialized. The content of the message will be the string STAF/START.

    ONSHUTDOWN indicates that a notification should be sent when STAF is shutdown. The content of the message will be the string STAF/SHUTDOWN.

    MACHINE indicates the machine to receive the message.

    PRIORITY indicates the priority of the message. The default is 5.

    NAME specifies that all processes with the given registered name on the given machine should be notified. This option is usually preferred over HANDLE, as it is difficult to know the desired handle in advance.

    HANDLE specifies that the process with the given handle on the given machine should be notified.

    Examples

    NOTIFY ONSTART MACHINE Server1 PRIORITY 3 NAME EventManager
    NOTIFY ONSHUTDOWN MACHINE Server1 NAME EventManager
    

    4.10 Tracing

    4.10.1 Description

    STAF provides various tracing facilities to help in auditing and debugging. STAF externalizes these facilities through trace points. Enabling a particular trace point causes trace messages to be generated whenever a particular event occurs, such as a service request resulting in an "Insufficient Trust Level" (aka "Access Denied) error code. Care should be taken when enabling trace points, as certain trace points, such as ServiceResult, can lead to large quantities of trace messages being generated. In these cases, it is best to limit tracing to only specific services.

    You may enable STAF trace points as well as set the trace output destination and the services to be traced using the TRACE configuration statement.

    Note: You may also interact with STAF tracing via the TRACE command of the MISC service, see 8.8.4, "TRACE".

    Syntax

    TRACE ON [ServiceRequest] [ServiceResult] [ServiceError]
             [ServiceAccessDenied] [ServiceManagement]
             [Registration] [RemoteRequests] [Error]
             [Warning] [Info] [Deprecated] [All]
    TRACE TO <STDOUT | STDERR | FILE <Filename> >
    TRACE [ALL] SERVICES [Service list]
    

    See the TRACE command of the MISC service, section 8.8.4, "TRACE", for information on the above options.

    Examples

    TRACE TO STDOUT
    TRACE TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc
    TRACE ON ServiceResult
    TRACE ON Error ServiceAccessDenied
    TRACE SERVICES "Process Queue Var"
    

    4.11 Configuration File Example

    Warning: This configuration file contains references to fictional services, machines, etc. and is provided for informational purposes only. Please do not try to use this as your actual STAF.cfg file. It is unlikely to work.

    # ---------------------------------------------------------------------
    # STAF Configuration File
    # ---------------------------------------------------------------------
    INTERFACE TCPIP
    SET USELONGNAMES CONNECTTIMEOUT 10000
     
    # ---------------------------------------------------------------------
    # STAF Log Mask Variable
    # ---------------------------------------------------------------------
    VAR STAF/Service/Log/Mask="START STOP WARNING FATAL ERROR"
     
    # ---------------------------------------------------------------------
    # Setup Trust Levels
    # ---------------------------------------------------------------------
    TRUST DEFAULT LEVEL 2
    TRUST LEVEL 3 MACHINE test1.austin.ibm.com MACHINE test2.test.austin.ibm.com
    TRUST LEVEL 4 MACHINE test3.test.austin.ibm.com
    TRUST LEVEL 5 MACHINE automate.austin.ibm.com
     
    # ---------------------------------------------------------------------
    # Delegated Services
    # ---------------------------------------------------------------------
    SERVICE pager DELEGATE globpager.test.austin.ibm.com
     
    # ---------------------------------------------------------------------
    # Rexx Services
    # ---------------------------------------------------------------------
    SERVICE doit LIBRARY RXSTAF Execute C:\STAF\services\doit.cmd
     
    # ---------------------------------------------------------------------
    # Java Services
    # ---------------------------------------------------------------------
     
    # Operating system independent name for my STAF services directory
    VAR myServiceDir={STAF/Config/STAFRoot}{STAF/Config/Sep/File}services
     
    SERVICE STAX  LIBRARY JSTAF \
                  EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAX.jar \
                  OPTION J2=-Xms64m OPTION J2=-Xmx128m
    SERVICE Event LIBRARY JSTAF \
                  EXECUTE {myServiceDir}{STAF/Config/Sep/File}STAFEvent.jar
     
    # ---------------------------------------------------------------------
    # C++ Services
    # ---------------------------------------------------------------------
    SERVICE log      LIBRARY STAFLog
    SERVICE monitor  LIBRARY STAFMon
    SERVICE respool  LIBRARY STAFPool
     
    # ---------------------------------------------------------------------
    # Notifications
    # ---------------------------------------------------------------------
    NOTIFY ONSTART MACHINE automate.austin.ibm.com PRIORITY 3 NAME EventManager
    NOTIFY ONSHUTDOWN MACHINE automate.austin.ibm.com NAME EventManager
     
    # ---------------------------------------------------------------------
    # Activate tracing
    # ---------------------------------------------------------------------
    TRACE TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc
    TRACE ON ServiceAccessDenied Error
    TRACE SERVICES "Process Trust"
    

    4.12 Tuning

    4.12.1 Description

    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.

    Examples, to set the thread stack size to 128KB

    On Unix: export STAF_THREAD_STACK_SIZE=128
    On Windows: set STAF_THREAD_STACK_SIZE=128
    


    5.0 Commands


    5.1 STAFProc

    STAFProc is what starts STAF running on a machine.

    Syntax

    STAFProc [STAF Configuration File]
    

    Examples

    STAFProc d:\staf\bin\mystaf.cfg
    

    If [STAF Configuration File] is not specified, STAFProc will try to use the file staf.cfg. It will search for this file in the current directory, as well as the directory in which STAFProc resides.

    Warning: In order to stop the STAFProc daemon process, you should enter the command "STAF local shutdown shutdown" (or use the associated program in your "Start" menu on Win32). Pressing CTRL-C (or issuing a "kill" command) will terminate STAFProc, but will not allow it to properly cleanup, which may cause problems and/or delays when trying to restart STAFProc. See section 8.17, "Shutdown Service" for more information on the SHUTDOWN service.

    Note: Any changes made to the STAF Configuration File after STAFProc has been started will not take effect until you shutdown and restart STAFProc.


    5.2 STAF

    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.

    Syntax

    STAF <Where> <Service> <Request>
    

    <Where> is either LOCAL, if you wish to make a request of the local machine, or the name of the machine of which you wish to make a request.

    <Service> is the name of the service to which you are submitting a request.

    <Request> is the actual request string that you wish to submit to the service.

    Examples

    STAF local ping ping
    STAF testmach1 process query all
    STAF local sem event SynchSem post
    STAF local var global set "SomeName=Some  text  string"
    

    Note: Take a closer look at the last example. Quotes are required around the value to the set option because the value contains spaces. When calling STAF APIs directly from testcases/applications, you should normally use the colon-length-colon delimited format described in 7.2, "Option Value Formats".

    Note: Older versions of STAF (prior to V2.1.0) required extra effort when quoting things on the command line. If you should need to resort to the old command line handling algorithm, simply set the environment variable STAF_OLDCLI to any non-empty value.

    Output

    On a successful STAF request (i.e., a request with a zero return code), the output from the STAF command will be as follows

    Response
    --------
    [Result string]
    

    where [Result string] is any information that was returned from the STAF service request.

    For example, the output of STAF LOCAL PING PING should be

    Response
    --------
    PONG
    

    On an unsuccessful STAF request (i.e., a request with a non-zero return code), the output from the STAF command will be as follows

    Error submitting request, RC: <Return code>
    [Additional info: <Result string>]
    

    where <Return code> is the actual return code from the request, and <Result string> is any information returned from the request. <Result string> usually contains information that explains why the error occurred. Additionally, you may refer to Appendix A, "API Return Codes" for information about the <Return code>

    For example, the output of STAF LOCAL SEM LIST should be

    Error submitting request, RC: 7
    Additional info: You must have at least 1, but no more than 1 of the option(s),
    MUTEX EVENT
    

    Note: If the <Result string> from a STAF command contains any null characters, you can set the environment variable STAF_REPLACE_NULLS to any non-empty value. This will cause the STAF command to replace any null characters in the <Result string> with the specified value. Otherwise, the <Result string> will be truncated at the first null character found.

    Using the STAF command from shell-scripts

    There are two special environment variables that can be used to make the STAF command blend in with shell-scripts. The first is STAF_QUIET_MODE. Setting this environment variable to any non-null value will cause the STAF command to only output the <Result string> that the request generated. For example, the "STAF local ping ping" command above would simply return

    PONG
    

    This makes it easy to call STAF from shell-scripts. For example,

    export STAF_QUIET_MODE=1
     
    STAFResult=`STAF local ping ping`
     
    if [ $? -ne 0 ]; then
       echo "Non-zero return code from ping request";
    elif [ "$STAFResult" != "PONG" ]; then
       echo "Expected PONG, received $STAFResult";
    else
       echo "ping request succeeded"
    fi
    

    The second environment variable is STAF_STATIC_HANDLE. If this environment variable is set, the STAF command will use the handle number indicated by this environment variable. This ensures that the shell-script can use the same handle throughout its execution. You may obtain a static handle in one of two ways. The first is using the CREATE command of the HANDLE service (see 8.5.2, "CREATE"). For example,

    export STAF_STATIC_HANDLE=`STAF local handle create handle name "My Test"`
    

    In this case, you are responsible for deleting the shell-scripts handle prior to your shell-script exiting. For example,

    STAF local handle delete handle $STAF_STATIC_HANDLE
    

    The second way is by using the STATICHANDLENAME option when starting your script throught the PROCESS service (see 8.11.2, "START"). In this case the STAF_STATIC_HANDLE environment variable will already be set for you. In addition, the handle will automatically be deleted by STAF when your shell-script completes.

    You can test for the existence of the STAF_STATIC_HANDLE environment variable to determine if your shell-script was started via STAF, or whether it was started by hand from the command line.


    5.3 STAF.cmd

    STAF.cmd is a Rexx program that interfaces with STAF and allows you to submit STAF service requests from the command line.

    Warning: This command is now deprecated. All command line STAF requests should be submitted through the STAF command. STAF.cmd is currently only available on a full install of STAF and may be removed from future versions of STAF.


    5.4 CSTAF

    CSTAF is an executable similar to STAF.cmd that allows you to submit STAF service requests from the command line.

    Warning: This command is now deprecated. All command line STAF requests should be submitted through the STAF command. CSTAF is currently only available on a full install of STAF and may be removed from future versions of STAF.


    6.0 API Reference


    6.1 C

    STAF externalizes six primary APIs to C/C++ programs. These APIs allow you to register/unregister with STAF, submit service requests, and free the memory associated with service request results.

    Note: STAF-enabled programs written in C must be linked with the C++ compiler (or by using any other means which allows the C++ runtime to get initialized). Otherwise, the C++ runtime won't get a chance to initialize so the STAF static data doesn't get initialized. Most systems require mixed C and C++ code to get linked by the C++ compiler.

    6.1.1 STAFRegister

    Description

    The STAFRegister call is used by a C program to register with STAF.

    Syntax

    STAFRC_t STAFRegister(char *processName, STAFHandle *handle)
    

    processName points to the name by which you want this process to be known.

    handle is a pointer to the STAFHandle that will be set on successful return from the function. You will use this handle on all other subsequent STAF calls.

    Examples

    char *myName = "MyProgram";
    STAFHandle_t myHandle = 0;
    STAFRC_t rc = STAFRegister(myName, &myHandle);
    

    6.1.2 STAFRegisterUTF8

    Description

    The STAFRegisterUTF8 API is identical in all respects with STAFRegister, except that processName is a string in UTF-8 format. This API is used primarily by the Java interfaces.

    6.1.3 STAFUnRegister

    The STAFUnRegister call is used by a C program to unregister with STAF, which frees up any internal STAF resources used by the handle.

    Syntax

    STAFRC_t STAFUnRegister(STAFHandle handle)
    

    handle is the handle that you received on the call to STAFRegister.

    Examples

    /* myHandle was previously set by STAFRegister */
     
    STAFRC_t rc = STAFUnRegister(myHandle);
    

    6.1.4 STAFSubmit

    Description

    The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.

    Syntax

    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.

    Examples

    /* 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);
    

    6.1.5 STAFSubmit2

    Description

    The STAFSubmit2 API is identical to the STAFSubmit API except that it has an additional parameter, syncOption, which allows submission of asynchronous requests.

    Syntax

    STAFRC_t STAFSubmit2(STAFHandle_t handle, STAFSyncOption_t syncOption,
                         char *where, char *service,
                         char *request, unsigned int requestLength,
                         char **resultPtr, unsigned int *resultLength)
    

    syncOption can be any of the following:

    The format of the queued message obtained when specifying kSTAFReqQueue or kSTAFReqQueueRetain is

    STAF/RequestComplete <Request #>;<Request return code>;<Request result buffer>
    

    for example, if you submitted the request "RESOLVE {STAF/Config/OS/Name}" to the VAR service using kSTAFReqQueue, and received a request number of 42, then the message you would receive when the request completed might look like

    STAF/RequestComplete 42;0;Win95
    

    The queued message will always be delivered with the default priority of 5.

    6.1.6 STAFSubmitUTF8

    Description

    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.

    6.1.7 STAFSubmit2UTF8

    Description

    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.

    6.1.8 STAFFree

    Description

    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.

    Syntax

    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.

    Examples

    /* myHandle was previously set by STAF     */
    /* result was previously set by STAFSubmit */
     
    STAFRC_t rc = 0;
     
    if (result != 0) rc = STAFFree(myHandle, result);
    

    6.1.9 Other APIs

    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.


    6.2 C++

    STAF externalizes two primary classes to C++ programs. These class are

    Addtionally, these classes use several other classes which are

    STAF also provides some other miscellaneous C++ classes, which are

    In addtion, C++ applications are able to take advantage of the C-only APIs, such as Thread support.

    6.2.1 STAFHandle and STAFResult

    The STAFHandle class is used to register with, and submit service requests to, STAF. In C++ STAFHandles are reference counted, so they are automatically freed for you. To obtain a STAFHandle, you call one of the create() methods. The first is the standard call you will use, and it allows you to specify the name by which your program should be known. The second create method allows you to create a STAFHandle object from an existing STAFHandle_t which would have been obtained from the C API STAFRegister(). By default, a STAFHandle obtained through the first method will automatically be unregistered when the STAFHandle is destructed. A STAFHandle created via the second method will not automatically be unregistered when the STAFHandle is destructed. In either case, you can change this behaviour with the setDoUnreg() method.

    Once you have a valid STAFHandlePtr, you can begin submitting requests to STAF. To do this, you use the submit() method, to which you specify the machine and service which should handle the request, as well as the request string itself. An optional fourth parameter defines whether this will be a synchronous or asynchronous request (if the parameter is not specified, the request will be synchronous). See the documentation for the C API STAFSubmit2 for the values allowed for this parameter. In return you get a reference counted pointer to a STAFResult object. Again, the underlying STAFResult object will be automatically freed when the reference count reaches zero. The STAFResult object itself contains a return code, rc, and a result string, result.

    You may examine the underlying STAFHandle_t via getHandle(). You may take ownership of the underlying STAFHandle_t via adoptImpl(). In this latter case, you are now responsible for the STAFHandle_t and are required to call STAFUnRegister(). Additionally, after a call to adoptImpl(), the existing STAFHandle object is invalidated and may not be used to call the submit() method.

    The utility function wrapData returns the colon-length-colon delimited version of the specified string. This is useful for specifying the values in STAF request string. See 7.2, "Option Value Formats" for more information.

    Definition

    typedef STAFRefPtr<STAFResult> STAFResultPtr;
    typedef STAFRefPtr<STAFHandle> STAFHandlePtr;
     
    class STAFResult
    {
    public:
        unsigned int rc;
        STAFString result;
    };
     
     
    class STAFHandle
    {
    public:
        static unsigned int create(const STAFString &name, STAFHandlePtr &handle);
        static unsigned int create(STAFHandle_t handleT, STAFHandlePtr &handle,
                                   bool doUnreg = false);
     
        STAFResultPtr submit(const STAFString &where, const STAFString &service,
                             const STAFString &request,
                             const STAFSyncOption_t synchOption = kSTAFReqSync);
     
        static STAFString wrapData(const STAFString &data);
     
        STAFHandle_t getHandle();
        STAFHandle_t adoptHandle();
     
        bool getDoUnreg();
        void setDoUnreg(bool doUnreg);
     
        ~STAFHandle();
    };
    

    Examples

    #include "STAF.h"
    #include "STAF_iostream.h"
     
    int main(void)
    {
        STAFHandle handle;
        unsigned int rc  = STAFHandle::create("MyApplication", handle);
     
        if (rc != 0)
        {
            cout << "Error registering with STAF, RC: " << rc << endl;
            return 1;
        }
     
        STAFResultPtr result = handle->submit("LOCAL", "PING", "PING");
     
        cout << "PING RC: " << result->rc << ", Result: " << result->result << endl;
     
        STAFString semName("Sem name with spaces");
     
        result = handle->submit("LOCAL", "SEM", "Event " +
                                STAFHandle::wrapData(semName) + " Post");
     
        cout << "Sem Post RC: " << result->rc << ", Result: " << result->result
             << endl;
     
        // Send an Asynchronous request
        result = handle->submit("LOCAL", "SERVICE", "LIST", kSTAFReqQueueRetain);
     
        cout << "Service List Request Number: " << << result->result << endl;
     
        return 0;
    }
    

    6.3 Rexx

    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:

    6.3.1 STAFRegister

    Description

    The STAFRegister call is used by a Rexx program to register with STAF.

    Syntax

    call STAFRegister processName[, handleVarName]
    

    processName is the name by which you want this process to be known.

    handleVarName is the name of the Variable which you want to contain the handle that you will use on all other subsequent STAF calls. If this parameter is not specified, the handle will be placed in the variable STAFHandle.

    Examples

    call STAFRegister "MyProcess", "MyHandle"
    say "My handle is:" MyHandle
    

    or

    call STAFRegister "MyProcess"
    say "My handle is:" STAFHandle
    

    6.3.2 STAFUnRegister

    Description

    The STAFUnRegister call is used by a Rexx program to unregister with STAF, which frees up any internal STAF resources used by the handle.

    Syntax

    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.

    Examples

    call STAFUnRegister MyHandle
    

    or

    call STAFUnRegister
    

    6.3.3 STAFSubmit

    Description

    The STAFSubmit call is the primary API that you will use. It is what allows you to submit a request to a service.

    Syntax

    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.

    Examples

    /* 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
     
    

    6.3.4 STAFMon wrapper library

    Description

    The STAFMon wrapper library provides a wrapper around the MONITOR service. The following functions are provided:

    Syntax

    call STAFMonErrorText
    call STAFMonitor <Message>[, <Extra request data>]
    

    <Mesasage> is the message that you wish to log to the MONITOR service.

    <Extra request data> is any additional information that should be passed along with the MONITOR service LOG request, such as additional options like RESOLVEMESSAGE.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFMonErrorText
     
    do i = 1 to numLoops
        call STAFMonitor "Beginning of loop #"i
          ...
          ...
    end
    

    6.3.5 STAFLog wrapper library

    Description

    The STAFLog wrapper library provides a wrapper around the LOG service. The following functions are provided:

    Syntax

    call STAFLogErrorText
    call STAFInitLog <Reference>, <Log name>[, [Log type], [Monitor mask]]
    call STAFSetCurrentLog <Reference>
    call STAFLog <Log level>, <Message>[, <Extra request data>]
    

    <Reference> is a text string of your desire that is used to refer to a log. This facilitates switching between several different log files.

    <Log name> is the name of the log to which you wish to log messages

    [Log type] is the type of log. This should be one of GLOBAL, MACHINE, or HANDLE. The default is MACHINE.

    [Monitor mask] is a string which specifies which logging levels should also be sent to the MONITOR service. The default is "FATAL ERROR WARNING INFO STATUS"

    <Log level> is the logging level of the message to be logged, e.g. ERROR or WARNING.

    <Mesasage> is the message that you wish to log to the LOG service.

    <Extra request data> is any additional information that should be passed along with the LOG service LOG request, such as additional options like RESOLVEMESSAGE.

    Examples

    /* 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"
    

    6.3.6 STAFPool wrapper library

    Description

    The STAFPool wrapper library provides a wrapper around the RESPOOL service. The following functions are provided:

    Syntax

    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.

    Examples

    /* STAFHandle was set by a previous call to STAFRegister */
    call STAFPoolErrorText
     
    call STAFPoolRequest "Pool1", "Entry1"
    say "The entry obtained was:" Entry1
     
      ...
     
    call STAFPoolRelease Entry1
    

    6.3.7 STAFUtil library

    Description

    The STAFUtil library provides some utilitiy functions for use by Rexx programs. The following functions are provided:

    Syntax

    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.

    Examples

    /* 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
    

    6.4 Java

    STAF externalizes five primary classes to Java applications. These classes are

    These classes all reside in the com.ibm.staf package. In order to use them in a Java application, you must import the STAF package like so

    import com.ibm.staf.*;
    

    STAF externalizes two wrapper classes. These classes are

    These classes all reside in the com.ibm.staf.wrapper package. In order to use them in a Java application, you must import the STAF wrapper package like so

    import com.ibm.staf.wrapper.*;
    

    6.4.1 STAFHandle

    The STAFHandle class is used to register, unregister, and submit service requests to STAF. Each Java application should create one and only one STAFHandle object. The act of creating this object registers the Java application with STAF using the name passed to the constructor. Once this is done, service requests may be submitted by one of two methods:

    Before the Java application exits, it should unregister with STAF by calling the unRegister() method.

    STAFHandle also defines the following constants which can be used as the syncOption parameter for the submit() and submit2() methods:

    Definition

    package com.ibm.staf;
     
    public class STAFHandle
    {
        public static final int ReqSync = 0;
        public static final int ReqFireAndForget = 1;
        public static final int ReqQueue = 2;
        public static final int ReqRetain = 3;
        public static final int ReqQueueRetain = 4;
     
        public STAFHandle(String processName) throws STAFException;
        public STAFHandle(int staticHandleNumber)
        public String submit(String where, String service, String request) throws STAFException;
        public String submit(int syncOption, String where, String service, String request) throws STAFException;
        public STAFResult submit2(String where, String service, String request);
        public STAFResult submit2(int syncOption, String where, String service, String request);
        public void unRegister() throws STAFException;
        public int getHandle();
    }
    

    Examples

    import com.ibm.staf.*;
     
    public class STAFTest
    {
        public static void main(String argv[])
        {
            try
            {
                STAFHandle handle = new STAFHandle("MyApplication");
     
                try
                {
                    System.out.println("My handle is: " + handle.getHandle());
                    String result1 = handle.submit("LOCAL", "PING", "PING");
                    System.out.println("PING Result: " + result1);
                    String result2 = handle.submit(STAFHandle.ReqQueueRetain, "LOCAL", "PING", "PING");
                    System.out.println("PING Request number: " + result2);
                    STAFResult result3 = handle.submit2("LOCAL", "ECHO", "ECHO Hello");
                    System.out.println("ECHO Result: " + result3.result);
                    STAFResult result4 = handle.submit2(STAFHandle.ReqRetain, "LOCAL", "ECHO", "ECHO Hello");
                    System.out.println("Asynchronous ECHO Request number: " + result4.result);
                    
                    STAFResult result = handle.submit2("local", "handle", "create handle name " + "MyStaticHandleName");                
                    STAFHandle staticHandle;                
     
                    if (result.rc == 0)
                    {                
                        staticHandle = new STAFHandle(new Integer(result.result).intValue());
                    }
                }
                catch (STAFException e)
                {
                    System.out.println("Error submitting request to STAF, RC: " + e.rc);
                    System.out.println(e.getMessage());
                }
                finally
                {
                    handle.unRegister();
                }
            }
            catch (STAFException e)
            {
                System.out.println("Error (un)registering with staf, RC:" + e.rc);
            }
     
        }   // End of main()
     
    }  // End of STAFTest
    

    6.4.2 STAFException

    The STAFException class is the exception class thrown by the STAFHandle class. It contains an rc variable which contains the actual return code from STAF. You may use the standard Throwable method getMessage() to retrieve any extra information provided by STAF.

    Definition

    package com.ibm.staf;
     
    public class STAFException extends Exception
    {
        public STAFException();
        public STAFException(int theRC);
        public STAFException(int theRC, String s);
     
        public int rc;
    }
    

    6.4.3 STAFResult

    The STAFResult class is returned by the STAFHandle.submit2() method. It contains both the STAF return code as well as the result string. It is typically used in places where you wish to avoid catching exceptions when using STAF. This class also contains the constant definitions for all the STAF return codes. These return codes are common to STAFResult and STAFException.

    Definition

    package com.ibm.staf;
     
    public class STAFResult
    {
        STAFResult();
        STAFResult(int theRC);
        STAFResult(int theRC, String theResult);
     
        public int rc;
        public String result;
     
        public static final int Ok = 0;
        public static final int InvalidAPI = 1;
        public static final int UnknownService = 2;
        public static final int InvalidHandle = 3;
        public static final int HandleAlreadyExists = 4;
        public static final int HandleDoesNotExist = 5;
        public static final int UnknownError = 6;
        public static final int InvalidRequestString = 7;
        public static final int InvalidServiceResult = 8;
        public static final int REXXError = 9;
        public static final int BaseOSError = 10;
        public static final int ProcessAlreadyComplete = 11;
        public static final int ProcessNotComplete = 12;
        public static final int VariableDoesNotExist = 13;
        public static final int UnResolvableString = 14;
        public static final int InvalidResolveString = 15;
        public static final int NoPathToMachine = 16;
        public static final int FileOpenError = 17;
        public static final int FileReadError = 18;
        public static final int FileWriteError = 19;
        public static final int FileDeleteError = 20;
        public static final int STAFNotRunning = 21;
        public static final int CommunicationError = 22;
        public static final int TrusteeDoesNotExist = 23;
        public static final int InvalidTrustLevel = 24;
        public static final int AccessDenied = 25;
        public static final int STAFRegistrationError = 26;
        public static final int ServiceConfigurationError = 27;
        public static final int QueueFull = 28;
        public static final int NoQueueElement = 29;
        public static final int NotifieeDoesNotExist = 30;
        public static final int InvalidAPILevel = 31;
        public static final int ServiceNotUnregisterable = 32;
        public static final int ServiceNotAvailable = 33;
        public static final int SemaphoreDoesNotExist = 34;
        public static final int NotSemaphoreOwner = 35;
        public static final int SemaphoreHasPendingRequests = 36;
        public static final int Timeout = 37;
        public static final int JavaError = 38;
        public static final int ConverterError = 39;
        public static final int ServiceAlreadyExists = 40;
        public static final int InvalidObject = 41;
        public static final int InvalidParm = 42;
        public static final int RequestNumberNotFound = 43;
        public static final int InvalidAsynchOption = 44;
        public static final int RequestNotComplete = 45;
        public static final int ProcessAuthenticationDenied = 46;
        public static final int InvalidValue = 47;
        public static final int DoesNotExist = 48;
        public static final int AlreadyExists = 49;
        public static final int DirectoryNotEmpty = 50;
        public static final int DirectoryCopyError = 51;
        public static final int DiagnosticsNotEnabled = 52;
        
        public static final int UserDefined = 4000;
    }
    

    6.4.4 STAFQueueMessage

    The STAFQueueMessage class provides a wrapper around messages received via the STAF Queue service. It takes the received string as input and breaks it into its constituent parts.

    Definition

    package com.ibm.staf;
     
    public class STAFQueueMessage
    {
        public STAFQueueMessage(String queueMessage);
     
        public int    priority;
        public String timestamp;
        public String machine;
        public String handleName;
        public int    handle;
        public String message;
    }
    

    6.4.5 STAFUtil

    The STAFUtil class contains utility functions provided by STAF. Currently, the only function provided is the static function wrapData() which is used to generate the length-delimited version of a string (see 7.2, "Option Value Formats") to be passed to STAF.

    Definition

    package com.ibm.staf;
     
    public class STAFUtil
    {
        public static string wrapData(String data);
    }
    

    6.4.6 STAFLog

    The STAFLog class provides a wrapper around the LOG command of the LOG service. It provides constants for the log type and log levels. It has instance and static methods for logging. The STAFLog class also interfaces with the MONITOR service. You may provide the STAFLog class a monitor mask. For the levels set in the monitor mask, STAFLog will log the message via the LOG service and then log the message via the MONITOR service. STAFLog will also log an error message to the MONITOR service, if it should receive an error while trying to log a message.

    Definition

    package com.ibm.staf.wrapper;
     
    public class STAFLog
    {
        // Log type constants
     
        public static final String GLOBAL  = "GLOBAL";
        public static final String MACHINE = "MACHINE";
        public static final String HANDLE  = "HANDLE";
     
     
        // Log level constants (int format)
     
        public static final int Fatal     = 0x00000001;
        public static final int Error     = 0x00000002;
        public static final int Warning   = 0x00000004;
        public static final int Info      = 0x00000008;
        public static final int Trace     = 0x00000010;
        public static final int Trace2    = 0x00000020;
        public static final int Trace3    = 0x00000040;
        public static final int Debug     = 0x00000080;
        public static final int Debug2    = 0x00000100;
        public static final int Debug3    = 0x00000200;
        public static final int Start     = 0x00000400;
        public static final int Stop      = 0x00000800;
        public static final int Pass      = 0x00001000;
        public static final int Fail      = 0x00002000;
        public static final int Status    = 0x00004000;
        public static final int Reserved1 = 0x00008000;
        public static final int Reserved2 = 0x00010000;
        public static final int Reserved3 = 0x00020000;
        public static final int Reserved4 = 0x00040000;
        public static final int Reserved5 = 0x00080000;
        public static final int Reserved6 = 0x00100000;
        public static final int Reserved7 = 0x00200000;
        public static final int Reserved8 = 0x00400000;
        public static final int Reserved9 = 0x00800000;
        public static final int User1     = 0x01000000;
        public static final int User2     = 0x02000000;
        public static final int User3     = 0x04000000;
        public static final int User4     = 0x08000000;
        public static final int User5     = 0x10000000;
        public static final int User6     = 0x20000000;
        public static final int User7     = 0x40000000;
        public static final int User8     = 0x80000000;
     
        // Log level constants (String format)
     
        public static final String FatalStr     = "FATAL";
        public static final String ErrorStr     = "ERROR";
        public static final String WarningStr   = "WARNING";
        public static final String InfoStr      = "INFO";
        public static final String TraceStr     = "TRACE";
        public static final String Trace2Str    = "TRACE2";
        public static final String Trace3Str    = "TRACE3";
        public static final String DebugStr     = "DEBUG";
        public static final String Debug2Str    = "DEBUG2";
        public static final String Debug3Str    = "DEBUG3";
        public static final String StartStr     = "START";
        public static final String StopStr      = "STOP";
        public static final String PassStr      = "PASS";
        public static final String FailStr      = "FAIL";
        public static final String StatusStr    = "STATUS";
        public static final String Reserved1Str = "RESERVED1";
        public static final String Reserved2Str = "RESERVED2";
        public static final String Reserved3Str = "RESERVED3";
        public static final String Reserved4Str = "RESERVED4";
        public static final String Reserved5Str = "RESERVED5";
        public static final String Reserved6Str = "RESERVED6";
        public static final String Reserved7Str = "RESERVED7";
        public static final String Reserved8Str = "RESERVED8";
        public static final String Reserved9Str = "RESERVED9";
        public static final String User1Str     = "USER1";
        public static final String User2Str     = "USER2";
        public static final String User3Str     = "USER3";
        public static final String User4Str     = "USER4";
        public static final String User5Str     = "USER5";
        public static final String User6Str     = "USER6";
        public static final String User7Str     = "USER7";
        public static final String User8Str     = "USER8";
     
        // Constructors - Default monitor mask is 0x00007C07.  This causes messages
        //                with log levels Fatal, Error, Warning, Start, Stop, Pass,
        //                Fail, and Status to also be logged via the MONITOR
        //                service
     
        public STAFLog(String logType, String logName, STAFHandle handle);
        public STAFLog(String logType, String logName, STAFHandle handle, int mask)
     
        // Methods to actually log a message with a given level
     
        public STAFResult log(int level, String msg)
        
        public STAFResult log(String level, String msg)
     
        public static STAFResult log(STAFHandle theHandle, String logType,
                                     String logName, int level, String msg)
                                     
        public static STAFResult log(STAFHandle theHandle, String logType,
                                     String logName, String level, String msg)
     
        public static STAFResult log(STAFHandle theHandle, String logType,
                                     String logName, int level, String msg,
                                     int mask)
     
        public static STAFResult log(STAFHandle theHandle, String logType,
                                     String logName, String level, String msg,
                                     int mask)
                                     
        // Accessor methods
     
        public String getName();
        public String getLogType();
        public int getMonitorMask();
    }
    

    Examples

    import com.ibm.staf.*;
    import com.ibm.staf.wrapper.*;
       ...
       ...
    // Create a log object that only logs Fatal and Error messages.
    // myHandle is a STAFHandle object that was created earlier.
     
    STAFLog logger = new STAFLog(STAFLog.GLOBAL, "MyLog", myHandle,
                                 STAFLog.Fatal | STAFLog.Error);
     
    STAFResult result;
     
    // Log an error via the instance and static methods
     
    result = logger.log(STAFLog.Error, "Error during test");
    result = STAFLog.log(myHandle, STAFLog.GLOBAL, "MyLog", STAFLog.Error,
                         "Error during test");
     
    // Set a mask to log Fatal, Error, Warning and Info messages.
    // Then log a warning via a static method.
     
    int myMask = STAFLog.Fatal | STAFLog.Error | STAFLog.Warning | STAFLog.Info;
     
    result = STAFLog.log(myHandle, STAFLog.GLOBAL, "MyLog", STAFLog.Warning,
                         "This is just a warning", myMask);
    

    6.4.7 STAFMonitor

    The STAFMonitor class provides a wrapper around the LOG command of the MONITOR service. It has instance and static methods for logging messages to the MONITOR service.

    Definition

    package com.ibm.staf.wrapper;
     
    public class STAFMonitor
    {
        // Constructor
     
        STAFMonitor(STAFHandle stafHandle);
     
        // Methods to log data to the MONITOR service
     
        public STAFResult log(String message);
        public static STAFResult log(STAFHandle theHandle, String message);
    }
    

    Examples

    import com.ibm.staf.*;
    import com.ibm.staf.wrapper.*;
       ...
       ...
    // Create a monitor object.  myHandle is a STAFHandle object that was created
    // earlier.
     
    STAFMonitor monitor = new STAFMonitor(myHandle);
     
    STAFResult result;
     
    // Log a message to the MONITOR service via the instance and static methods
     
    result = monitor.log("Beginning phase 1");
    result = STAFMonitor.log(myHandle, "Beginning phase 2");
    


    7.0 Services overview

    Services are what provide all the capabilities of STAF.


    7.1 General Service Syntax

    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.

    7.2 Option Value Formats

    Values for options may be specified in one of three ways.

    1. If the value contains no spaces or quotes, you may simply specify the value. For example,
      MESSAGE Hello
      
    2. You may enclose the value in quotes. When doing so, the backslash character is the escape character. Any character after the backslash is treated as a literal character. To specify a backslash, use two backslashes. For example,
      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

    3. You may use a length delimited format that is of the form :<Length>:<String>. Note that the length is specified in characters, not bytes. For example,
      MESSAGE :11:Hello World
      

      specifies the message Hello World

      MESSAGE :23:He said, "What is that"
      

      specifies the message He said, "What is that"

      MESSAGE :35:c:\MyApp\Some directory with spaces
      

      specifies the message c:\MyApp\Some directory with spaces

    The first two formats are most appropiate when using the STAF command line. The third is most appropriate and easiest from within programs.

    Note that when the value of an option is the same as the name of the option (or another supported option), the value must be distinguished as such either by quoting the value or by using the length delimited format. For example, if NAME is the name of an option and you also want to specify NAME as the value of the option, you should specify either NAME "NAME" or NAME :4:NAME.


    7.3 Variable Resolution

    Most command options allow their values to contain variable references which will be resolved by the service. This will be noted in the command options that allow it. In addition, the machine and service specified when submitting a STAF request may contain variable references.

    Unless otherwise specified, variable resolution is handled in one of two ways, based on whether the request is performed locally (i.e., on the originating system) or on another system.

    Note: Since, by definition, a delegated service request will not be handled locally, the variable pool associated with the requesting process will never be used for variable resolution in a delegated service request.


    7.4 Service Help

    Most services provide a HELP command that list basic service syntax information. The following internal services do not provide HELP due to their simplicity.

    It is recommended that external service writers also provide a HELP facility.


    7.5 Service list

    The following table contains a brief description of the services provided with STAF. The chapter that follows provides a detailed explanation of each service.

    Table 4. Service Descriptions
    Service name Description String Representation
    DELAY Provides a means to sleep a specified amount of time
    DIAG Provides diagnostics services
    ECHO Echos back a supplied message
    FS Provides file transfer between systems
    HANDLE Provides information about existing STAF handles
    HELP Provides help on STAF error codes
    LOG Provides robust logging services
    MISC Handles miscellaneous commands. Also handles tracing.
    MONITOR Provides a means to monitor the status of running programs
    PING Provides a simple is-alive message
    PROCESS Handles starting, stopping, and querying processes
    QUEUE Interacts with STAF queues
    RESPOOL Manages pools of named elements
    SEM Provides named event and mutex semaphores
    SERVICE Provides information on available STAF services
    SHUTDOWN Provides a means to shutdown STAF and register for shutdown notifications
    TRUST Interfaces with STAF's security
    VAR Allows inspection and manipulation of STAF variable pools
    ZIP Provides a means to zip/unzip/list/delete PKZip/WinZip compatible archives


    8.0 Service reference

    The foundation services that STAF provides are described in this chapter. For each service the following sections are listed.


    8.1 Delay Service

    8.1.1 Description

    The DELAY service is an internal STAF service. A DELAY request simply sleeps for a specified amount of time (in milliseconds) before returning to the calling program.

    8.1.2 DELAY

    Syntax

    DELAY <milliseconds>
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from DELAY are documented in Appendix A, "API Return Codes".

    Examples

    Goal: Delay 3 seconds before returning from STAFProf.

    DELAY 3000
    


    8.2 Diagnostics (DIAG) Service

    8.2.1 Description

    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.

    8.2.2 RECORD

    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.

    Syntax

    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.

    Security

    This command requires trust level 3.

    Note: This command may only be submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from RECORD are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RECORD command.

    Examples

    Goal:  Record trigger "PROCESS QUERY" and "myApp;machinea.ibm.com" as the source of the trigger in the diagnostics map.
    Syntax:  RECORD TRIGGER "PROCESS QUERY" SOURCE "myApp;machinea.ibm.com"

    8.2.3 LIST

    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.

    Syntax

    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.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain data based on the LIST command.

    The result buffer for LIST (without specifying option TRIGGER, SOURCE, TRIGGERS, SOURCES, or SETTINGS) will contain a list of all unique trigger/source combinations and a count of how many times each was recorded in the following format:

     From Timestamp    : <yyyymmdd-hh:mm:ss>
     To Timestamp      : <yyyymmdd-hh:mm:ss>
     Elapsed Time      : <hh:mm:ss>
     Number of Triggers: <Number of Triggers>
     Number of Sources : <Number of Sources>
     
     <Count>;<Trigger>;<Source>
     ...
     ...
    

    From Timestamp specifies the date/time that diagnostics were first enabled or last reset, or <N/A> if diagnostics have never been enabled.

    To Timestamp specifies the date/time that diagnostics were disabled or, if still enabled, the current time.

    Elapsed Time specifies the difference between the From Timestamp and the To Timestamp in hours, minutes, and seconds, or <N/A> if diagnostics have never been enabled.

    Number of Triggers specifies the number of unique triggers that have been recorded.

    Number of Sources specifies the number of unique sources that have been recorded.

    Count specifies the number of times each trigger/source combination has been recorded.

    The result buffer for LIST TRIGGERS will contain a list of all unique triggers that have been recorded.

     From Timestamp    : <yyyymmdd-hh:mm:ss>
     To Timestamp      : <yyyymmdd-hh:mm:ss>
     Elapsed Time      : <hhh:mm:ss>
     Number of Triggers: <Number of Triggers>
     
     <Count>;<Trigger>
     ...
     ...
    

    Count specifies the number of times the trigger has been recorded.

    The result buffer for LIST SOURCES will contain a list of all unique sources that have been recorded.

     From Timestamp    : <yyyymmdd-hh:mm:ss>
     To Timestamp      : <yyyymmdd-hh:mm:ss>
     Elapsed Time      : <hhh:mm:ss>
     Number of Sources : <Number of Sources>
     
     <Count>;<Source>
     ...
     ...
    

    Count specifies the number of times the source has been recorded.

    The result buffer for LIST TRIGGER <Trigger> will contain a list of all unique sources that have been recorded for the specified trigger.

     
     From Timestamp    : <yyyymmdd-hh:mm:ss>
     To Timestamp      : <yyyymmdd-hh:mm:ss>
     Elapsed Time      : <hhh:mm:ss>
     Trigger           : <Specified Trigger>
     Number of Sources : <Number of Sources for Trigger>
     
     <Count>;<Source>
     ...
     ...
    

    Count specifies the number of times the source has been recorded for the specified trigger.

    The result buffer for LIST SOURCE <Source> will contain a list of all unique triggers that have been recorded for the specified source.

     From Timestamp    : <yyyymmdd-hh:mm:ss>
     To Timestamp      : <yyyymmdd-hh:mm:ss>
     Elapsed Time      : <hhh:mm:ss>
     Source            : <Specified Source>
     Number of Triggers: <Number of Triggers for Source>
     
     <Count>;<Trigger>
     ...
     ...
    

    Count specifies the number of times the trigger has been recorded for the specified source.

    The result buffer for LIST SETTINGS will contain the current operational settings.

     
     Diagnostics               : <Enabled | Disabled>
     Last Reset / First Enabled: <yyyymmdd-hh:mm:ss>
     Last Disabled             : <yyyymmdd-hh:mm:ss>
    

    Diagnostics specifies if recording diagnostics is currently enabled or disabled.

    Last Reset / First Enabled specifies the timestamp when diagnostics were last reset or first enabled or <N/A> if diagnostics have never been reset since STAF was started.

    Last Disabled specifies the timestamp when diagnostics were last disabled or last cleared via the RESET command. It is initially set to the date/time when STAF was started.

    Examples

    Goal:  Show me all the trigger/source combinations that have been recorded (sorted in descending order by count, the default).
    Syntax:  LIST
    Results:
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:29:08
     Elapsed Time      : 00:03:36
     Number of Triggers: 3
     Number of Sources : 9
     
     17;STAX QUERY;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78
     15;STAX QUERY;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98
     14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100
     14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80
     10;LOG QUERY;STAX/Job/7;lucas.austin.ibm.com;77
     10;LOG QUERY;STAX/Job/8;lucas.austin.ibm.com;97
     4;PROCESS QUERY;STAX/Job/7;lucas.austin.ibm.com;77
     4;PROCESS QUERY;STAX/Job/8;lucas.austin.ibm.com;97
     3;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79
     2;STAX QUERY;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10
     1;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99
    
    Goal:  Show me all the triggers and sources that have been recorded sorted in ascending order by trigger.
    Syntax: LIST SORTBYTRIGGER
    Results:
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:32:53
     Elapsed Time      : 00:07:21
     Number of Triggers: 3
     Number of Sources : 9
     
     10;LOG QUERY;STAX/Job/7;lucas.austin.ibm.com;77
     10;LOG QUERY;STAX/Job/8;lucas.austin.ibm.com;97
     4;PROCESS QUERY;STAX/Job/7;lucas.austin.ibm.com;77
     4;PROCESS QUERY;STAX/Job/8;lucas.austin.ibm.com;97
     3;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79
     1;STAX QUERY;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99
     14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100
     14;STAX QUERY;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80
     2;STAX QUERY;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10
     17;STAX QUERY;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78
     15;STAX QUERY;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98
    
    Goal:  Show me all the triggers that have been recorded, sorted by trigger in ascending order.
    Syntax:  LIST TRIGGERS SORTBYTRIGGER
    Results:
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:35:03
     Elapsed Time      : 00:09:31
     Number of Triggers: 3
     
     20;LOG QUERY
     8;PROCESS QUERY
     66;STAX QUERY
    
    Goal:  Show me all the sources that have been recorded (sorted by count in descending order, the default).
    Syntax:  LIST SOURCES
    Results:
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:36:03
     Elapsed Time      : 00:10:31
     Number of Sources : 9
     
     17;STAX/JobMonitor/lucas/7;lucas.austin.ibm.com;78
     15;STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98
     14;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;100
     14;STAFMonitorSTAFCmdTableExtension;lucas.austin.ibm.com;80
     14;STAX/Job/7;lucas.austin.ibm.com;77
     14;STAX/Job/8;lucas.austin.ibm.com;97
     3;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;79
     2;STAX/JobMonitor/Controller;lucas.austin.ibm.com;10
     1;STAFMonitorProcessTableExtension;lucas.austin.ibm.com;99
    
    Goal:  Show me all of the sources for trigger "LOG QUERY", sorted by source in ascending order.
    Syntax:  LIST TRIGGER "LOG QUERY" SORTBYSOURCE
    Results:
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:37:04
     Elapsed Time      : 00:11:32
     Trigger           : LOG QUERY
     Number of Sources : 2
     
     10;STAX/Job/7;lucas.austin.ibm.com;77
     10;STAX/Job/8;lucas.austin.ibm.com;97
    
    Goal:  Show me all of the triggers for source "STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98" (sorted by count in descending order, the default).
    Syntax:  LIST SOURCE "STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98"
    Results:
     
     From Date/Time    : 20040212-18:25:32
     To Date/Time      : 20040212-18:39:01
     Elapsed Time      : 00:13:29
     Source            : STAX/JobMonitor/lucas/8;lucas.austin.ibm.com;98
     Number of Triggers: 1
     
     15;STAX QUERY
    
    Goal:  Show me the current operational settings.
    Syntax:  LIST SETTINGS
    Results:
     Diagnostics               : Enabled
     Last Disabled             : 20040212-18:25:32
     Last Reset / First Enabled: 20040212-18:25:32
    

    8.2.4 RESET

    RESET allows you to clear all data from the diagnostics map.

    Syntax

    RESET FORCE
    

    FORCE is a confirmation that you want to clear all data.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from RESET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a RESET command.

    Examples

    Goal:  Remove all information in the diagnostics map.
    Syntax:  RESET FORCE

    8.2.5 ENABLE

    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.

    Syntax

    ENABLE
    

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from ENABLE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a ENABLE command.

    Examples

    Goal:  Enable recording diagnostics.
    Syntax:  ENABLE

    8.2.6 DISABLE

    DISABLE allows you to disable recording diagnostics.

    Syntax

    DISABLE
    

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from DISABLE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on a successful return from a DISABLE command.

    Examples

    Goal:  Disable recording diagnostics.
    Syntax:  DISABLE


    8.3 Echo Service

    8.3.1 Description

    The ECHO service is an internal STAF service. ECHO provides a similiar service as PING. The difference is that ECHO allows you to specify the return string that STAFProc will return. ECHO can also be used to determine if STAFProc is up and running and accessible.

    8.3.2 ECHO

    Syntax

    ECHO <Message>
    

    Note: ECHO does not follow the request parsing rules described earlier. Any text after the ECHO command will be returned verbatim.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from ECHO are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain <Message> on a successful return from an ECHO command.

    Examples

    Goal: Have STAFProc return the string Hello World to you.

    ECHO Hello World
    


    8.4 File System (FS) Service

    8.4.1 Description

    The File System service, called FS, allows you to interface with the file system on STAF Clients. It provides the following commands.

    In the descriptions of these commands, three different options are used to refer to objects in the file system. FILE is used when the object in question must be a file. DIRECTORY is used when the object in question must be a directory. ENTRY is used when the object in question may be any object in the file system.

    Some of these commands allow match patterns to be specified. These patterns recognize two special characters, '*' and '?'. '*' matches an string of characters (including an empty string). '?' matches any single character (the empty string does not match).

    8.4.2 COPY FILE

    COPY FILE allows you to copy files between machines, as well as locally.

    Note: A file copied via the FS services does not retain its system or extended attributes.

    Syntax

    COPY FILE <FileName> [TOFILE <FileName>] [TOMACHINE <Machine>]
         [TEXT [FORMAT <Format>]]
         [FAILIFEXISTS | FAILIFNEW]
    

    FILE specifies the name of the file to copy. This option will resolve variables.

    TOFILE specifies the name of the file to create. This defaults to the same, unresolved, name as specified in FILE. This option will resolve variables. These variables will be resolved on the target machine.

    TOMACHINE specifies the machine to copy the file to. This defaults to the machine which originated the request. Specifying local indicates to copy the file to the same machine that the file is being copied from. This option will resolve variables.

    TEXT specifies to convert line-ending characters in the file being copied as specified via the FORMAT option and to perform codepage conversion. This option should only be specified for a text file, not a binary file.

    FORMAT specifies the end-of-line character(s) to use. This option will resolve variables. See 8.4.4, "GET FILE" for more information on available formats.

    FAILIFEXISTS specifies that the copy should fail if TOFILE already exists. The default is to replace the file if it exists.

    FAILIFNEW specifies that the copy should fail if TOFILE does not already exist. The default is to create the file if it does not exist.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from COPY FILE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a COPY FILE command.

    Examples

    In the following examples, assume the command is being issued locally from machine TestSrv1.

    Goal: Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file c:\testcase\tc1.cmd on machine Client1

    COPY FILE c:\testcase\tc1.cmd TOMACHINE Client1
    

    Goal: Copy file c:\testcase\tc1.cmd from machine TestSrv1 to file d:\WebTests\webtc1.cmd on machine Client1. Don't overwrite the file if it exists.

    COPY FILE c:\testcase\tc1.cmd TOFILE d:\WebTests\webtc1.cmd TOMACHINE Client1
         FAILIFEXISTS
    

    Goal: Copy text file test1.txt (in the directory specified by STAF variable TestcaseDir) from machine TestSrv1 to file test1.txt (in the directory specified by STAF variable TestcaseDir) on machine Client1. Convert any line-ending characters in the file to those appropriate for machine Client1, if machine Client1 has a different platform (e.g. Unix) than machine TestSrv1 (e.g. Windows). Note that both of these COPY FILE examples are equivalent.

    COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT
    COPY FILE {TestcaseDir}/test1.txt TOMACHINE Client1 TEXT FORMAT Native
    

    Goal: Copy text file c:\tc\test1.txt from machine TestSrv1 to file c:\tc\test1.txt on machine Client1. Convert any line-ending characters in the file to a space.

    COPY FILE c:\tc\test1.txt TOMACHINE Client1 TEXT FORMAT " "
    

    In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.

    Goal: Retrieve file d:\WebTests\Logs\WebTC1.log from Client1 and store it in directory f:\Logs on machine TestSrv1.

    COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE f:\Logs\WebTC1.log
    

    Goal: Copy file d:\WebTests\Logs\WebTC1.log from Client1 to server LogSrv in directory h:\Logs.

    COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE h:\Logs\WebTC1.log TOMACHINE LogSrv
    

    Goal: Copy file d:\WebTests\Logs\WebTC1.log from Client1 to file c:\temp\tc1.log on machine Client1.

    COPY FILE d:\WebTests\Logs\WebTC1.log TOFILE c:\temp\tc1.log TOMACHINE local
    

    Goal: Copy the startup.cmd on the boot drive of Client1 to the boot drive of TestSrv1. Convert any line-ending characters of the text file as needed.

    COPY FILE {STAF/Config/BootDrive}\startup.cmd TEXT
    

    8.4.3 COPY DIRECTORY

    COPY DIRECTORY allows you to copy entire directories (including subdirectories if needed) between machines, as well as locally.

    Note: A file copied via the FS services does not retain its system or extended attributes.

    Note: The entries in COPY DIRECTORY are files and directories.

    Syntax

    COPY DIRECTORY <Name> [TODIRECTORY <Name>] [TOMACHINE <Machine>]
         [NAME <Pattern>] [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
         [TEXTEXT <Pattern>... [FORMAT <Format>]]
         [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]]
         [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
    

    DIRECTORY specifies the name of the source directory to copy. This option will resolve variables.

    TODIRECTORY specifies the name of the destination directory. This defaults to the same, unresolved, name as specified in DIRECTORY. This option will resolve variables. These variables will be resolved on the target machine.

    TOMACHINE specifies the machine to copy the directory and its contents to. This defaults to the machine which originated the request. Specifying local indicates to copy the directory and its contents to the same machine that the directory is being copied from. This option will resolve variables.

    NAME specifies a pattern used to match the name of files in the specified directory (and files in its subdirectories, if RECURSE is specified). Only the files whose names match this pattern will be copied. Match patterns may be specified using special characters '*' and/or '?'. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of files in the specified directory (and files in its subdirectories, if RECURSE is specified). Only the files whose extensions match this pattern will be copied. Match patterns may be specified using special characters '*' and/or '?'. The default pattern is "*". This option will resolve variables.

    Note: The COPY/LIST DIRECTORY commands recognize the "name" (NAME) portion of a filename as the character(s) that preceed a period (or the entire filename if it does not include a period) and the "extension" (EXT) portion of a filename are character(s) that follow a period. For example, for filename myfile.txt the "name" portion is "myfile" and the "extension" portion is "txt". To match filenames whose name begins with "my" and whose extension is "txt", you could specify options NAME my* EXT txt.

    CASESENSITIVE specifies that the patterns specified by NAME, EXT, and TEXTEXT are to be matched in a case sensitive manner.

    CASEINSENSITIVE specifies that the patterns specified by NAME, EXT, and TEXTEXT are to be matched in a case insensitive manner.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE.

    TEXTEXT specifies a pattern used to match the extension of text files being copied. The files whose extensions match this pattern should contain text, not binary data. The line-ending characters in the files being copied whose extensions match this pattern will be converted as specified via the FORMAT option and codepage conversion will be performed. Multiple TEXTEXT patterns are handled as an "or" condition. Match patterns may be specified using special characters '*' and/or '?'. This option will resolve variables.

    FORMAT specifies the end-of-line character(s) to use. This option will resolve variables. See 8.4.4, "GET FILE" for more information on available formats.

    RECURSE specifies that the subdirectories in DIRECTORY will be recursively copied.

    KEEPEMPTYDIRECTORIES specifies that the empty directories are also to be created in the TODIRECTORY on the target. The default behavior is to prune the empty directories while copying files.

    ONLYDIRECTORIES specifies that the directory (empty diretoreis and no files copied) structure is to be created in the TODIRECTORY on the target machine. Using the NAME, EXT, CASESENSITIVE and CASEINSENSITIVE options with the ONLYDIRECTORIES option will be ignored as no files will be copied.

    IGNOREERRORS specifies that errors encountered copying entries should not be returned. By default, all errors encountered while copying entries will be returned in the result buffer.

    FAILIFEXISTS specifies that the copy should fail if TODIRECTORY already exists. The default is to copy over the directory contents if it exists.

    FAILIFNEW specifies that the copy should fail if TODIRECTORY does not already exist. The default is to create the directory if it does not exist.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from COPY DIRECTORY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty. If errors were encountered copying entries and IGNOREERRORS was not specified, the result buffer will be formatted like so

    <Failure 1 full path name>;<Failure 1 return code>[:Failure 1 OS return code]
    <Failure 2 full path name>;<Failure 2 return code>[:Failure 2 OS return code]
    <Failure N full path name>;<Failure N return code>[:Failure N OS return code]
    

    The OS return code will only be provided if the return code indicated a base operating system error occured (i.e., if RC == 10).

    Examples

    In the following examples, assume the command is being issued locally from machine TestSrv1.

    Goal: Copy directory c:/testcase from machine TestSrv1 to directory c:/testcase on machine Client1

    COPY DIRECTORY c:/testcase TOMACHINE Client1
    

    Goal: Copy directory c:/testcase and its subdirectories from machine TestSrv1 to directory c:/testcase on machine Client1.

    COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE
    

    Goal: Copy directory c:/testcase from machine TestSrv1 to directory d:/WebTests on machine Client1. Don't overwrite the directory if it exists.

    COPY DIRECTORY c:/testcase TODIRECTORY d:/WebTests TOMACHINE Client1 FAILIFEXISTS
    

    Goal: Copy all files with an extension of "tmp" in directory c:/testcase to directory c:/testcase on machine Client1. Match the extension in a case insensitive manner. Do not recurse down subdirectories.

    COPY DIRECTORY c:/testcase TOMACHINE Client1 EXT tmp CASEINSENSITIVE
    

    Goal: Recursively copy all files under {MyTempDirectory} with a base name beginning with "test" to directory {MyTempDirectory} on machine Client1. Match the file names in a case sensitive manner. Do not report any errors during the copying. Don't create the directory if it does not exist on the target machine.

    COPY DIRECTORY {MyTempFiles} TOMACHINE Client1 NAME "test*" CASESENSITIVE RECURSE IGNOREERRORS
    

    In the following examples, assume the command is being issued locally from machine TestSrv1 and the following directory structures exist under the c:/testcase directory:

      c:\testcase
      c:\testcase\error.txt
      c:\testcase\web.exe
      c:\testcase\web.txt
      c:\testcase\web.xml
      c:\testcase\subdir
      c:\testcase\subdir\subdir_1
      c:\testcase\subdir\subdir_2
      c:\testcase\subdir\subdir_2\readme.txt
    

    Goal: Copy directory c:/testcase and its subdirectories, including empty subdirectories, from machine TestSrv1 to directory c:/testcase on machine Client1.

    COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE KEEPEMPTYDIRECTORIES
    

    The expected result is that the following entries exist on machine Client1:

      c:\testcase
      c:\testcase\error.txt
      c:\testcase\web.exe
      c:\testcase\web.txt
      c:\testcase\web.xml
      c:\testcase\subdir
      c:\testcase\subdir\subdir_1
      c:\testcase\subdir\subdir_2
      c:\testcase\subdir\subdir_2\readme.txt
    

    Goal: Copy directory c:/testcase and its subdirectories from machine TestSrv1 to directory c:\testcase on machine Client1. However, do not copy any files.

    COPY DIRECTORY c:/testcase TOMACHINE Client1 RECURSE ONLYDIRECTORIES
    

    The expected result is that the following entries were created on machine Client1:

      c:\testcase
      c:\testcase\subdir
      c:\testcase\subdir\subdir_1
      c:\testcase\subdir\subdir_2
    

    Goal: Copy all files from machine TestSrv1 in directory c:/testcase whose name is 'web' to directory /testcase on machine Client1. Convert the line-ending characters in the files whose extensions are 'txt' or 'xml' (as they are considered to be text files) to the line-ending characters for machine Client1's platform. Note that both of these COPY DIRECTORY examples are equivalent.

    COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
         NAME web TEXTEXT txt TEXTEXT xml
         
    COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
         NAME web TEXTEXT txt TEXTEXT xml FORMAT Native
    

    The expected result is that the following entries were created on machine Client1. Note that error.txt was not copied since its name is not 'web'.

      /testcase
      /testcase/web.exe
      /testcase/web.txt
      /testcase/web.xml
    

    Goal: Copy all .txt files from machine TestSrv1 in directory c:/testcase, and it's subdirectories, to directory /testcase on machine Client1. Convert the line-ending characters in all the files being copied (as they are considered to be text files) to the line-ending characters for machine Client1's platform. Note that both of these COPY DIRECTORY examples are equivalent.

    COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
         EXT txt TEXTEXT "*" RECURSE
         
    COPY DIRECTORY c:/testcase TODIRECTORY /testcase TOMACHINE Client1
         EXT txt TEXTEXT txt FORMAT Native RECURSE
    

    The expected result is that the following entries were created on machine Client1.

      /testcase
      /testcase/error.txt
      /testcase/subdir
      /testcase/subdir/subdir_2
      /testcase/subdir/subdir_2/readme.txt
    

    In the following examples, assume the command is being issued to machine Client1 from machine TestSrv1.

    Goal: Retrieve all files in directory d:\WebTests\Logs from Client1 and store them in directory f:\Logs on machine TestSrv1. Do not copy its subdirectories.

    COPY DIRECTORY d:/WebTests/Logs TODIRECTORY f:/Logs
    

    Goal: Copy directory d:\WebTests\Logs and its non-empty subdirectories from Client1 to directory h:\Logs on server LogSrv.

    COPY DIRECTORY d:/WebTests/Logs TODIRECTORY h:/Logs TOMACHINE LogSrv RECURSE
    

    Goal: Copy directory d:\WebTests\Logs and its non-empty subdirectories from Client1 to directory h:\Logs on Client1.

    COPY DIRECTORY d:/WebTests/Logs TODIRECTORY h:/Logs TOMACHINE local RECURSE
    

    Goal: Copy all .cmd files in the root of the boot drive from Client 1 to the root of the boot drive of machine TestSrv1.

    COPY DIRECTORY {STAF/Config/BootDrive}\ EXT cmd
    

    8.4.4 GET FILE

    GET FILE retrieves the contents of a file.

    Syntax

    GET FILE <FileName> [[TEXT | BINARY] [FORMAT <Format>]]
    

    FILE specifies the name of the file to get. This option will resolve variables.

    TEXT specifies to convert line-ending characters in the file being retrieved as specified via the FORMAT option and to perform codepage conversion. This option should only be specified for a text file, not a binary file. This is the default.

    BINARY specifies to retrieve the contents of the file in binary.

    FORMAT specifies the format of the file's contents. This option will resolve variables.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from GET FILE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the contents of the specified file.

    Examples

    Goal: Retrieve the contents of the CONFIG.SYS file as text. Convert any line-ending characters to those of the platform of the machine making the request. Note that all of these GET FILE examples are equivalent.

    GET FILE {STAF/Config/BootDrive}/CONFIG.SYS
    GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT
    GET FILE {STAF/Config/BootDrive}/CONFIG.SYS TEXT FORMAT Native
    

    Goal: Retrieve the contents of the STAF configuration file as text. Convert any line-ending characters in the file being retrieved to the line-ending characters for Unix.

    GET FILE {STAF/Config/STAFRoot}/bin/STAF.cfg TEXT FORMAT Unix
    

    Goal: In this example, assume the command is being issued to a Unix machine from a Windows machine. Retrieve the contents of file /testcases/test1.txt as text and convert the line-ending characters to the line-ending characters for Windows.

    GET FILE /testcases/test1.txt TEXT FORMAT Windows
    

    Goal: Retrieve the contents of file /testcases/test1.txt as text and convert the line-ending characters to a space.

    GET FILE /testcases/test1.txt TEXT FORMAT " "
    

    Goal: Retrieve the contents of file c:/testcases/test1.cmp in binary and display its contents in hex. Note that both of these GET FILE examples are equivalent.

    GET FILE c:/testcases/test1.cmp BINARY
    GET FILE c:/testcases1/test1.cmp BINARY FORMAT HEX
    

    8.4.5 GET ENTRY

    GET ENTRY retrieves an attribute of a file system entry, such as its type, size, or last modification time.

    Syntax

    GET ENTRY <Name> <TYPE | SIZE | MODTIME>
    

    ENTRY specifies the name of the file system entry for which to retrieve an attribute. This option will resolve variables.

    TYPE specifies that the type of the file system entry should be retrieved.

    SIZE specifies that the size of the file system entry should be retrieved.

    MODTIME specifies that the last modification time of the file system entry should be retrieved.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET ENTRY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the contents of the result buffer will depend on the attribute type requested. If TYPE is specified, the result buffer will contain one of the following letters

    Table 5. File System Entry Types Reference
    Type identifier Description
    F File
    D Directory
    P Pipe
    S Socket
    L Symbolic link
    B Block device
    C Character device
    O Other undefined type
    ? Unknown type

    If SIZE is specified, the result buffer will contain the 64-bit size of the file system entry in the format

    <Upper 32-bit integer>:<Lower 32-bit integer>
    

    If MODTIME is specified, the result buffer will contain the last modification time of the file system entry in the format YYYYMMDD-HH:MM:SS

    Examples

    Goal: Retrieve the type of the file system entry C:\Stuff\WhatIsIt.d

    GET ENTRY C:\Stuff\WhatIsIt.d TYPE
    

    Goal: Retrieve the size of the file system entry /var/log/messages

    GET ENTRY /var/log/messages SIZE
    

    Goal: Retrieve the last modification time of the file system entry {STAF/Config/BootDrive}\CONFIG.SYS

    GET ENTRY {STAF/Config/BootDrive}\CONFIG.SYS MODTIME
    

    8.4.6 QUERY

    QUERY retrieves all associated attributes of a file system entry.

    Syntax

    QUERY ENTRY <Name>
    

    ENTRY specifies the name of the file system entry to query. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the file system entry attributes in the following format

    Name    : <Name>
    Type    : <Type>
    Size    : <Size>
    Modified: <Last Modification Time>
    
    <Type>, <Size>, and <Last Modification Time> are formatted as specified in section 8.4.5, "GET ENTRY".

    Examples

    Goal: Retrieve the attributes for the file system entry /var/log/messages

    QUERY ENTRY /var/log/messages
    

    8.4.7 LIST

    LIST retrieves the contents of a directory.

    Syntax

    LIST DIRECTORY <Name> [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
         [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
         [CASESENSITIVE | CASEINSENSITIVE] [LONG [FORMAT]]
    

    DIRECTORY specifies the name of the directory to list. This option will resolve variables.

    NAME specifies a pattern used to match the name of child entries. Only child entries whose name match this pattern will be returned. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of child entries. Only child entries whose extension match this pattern will be returned. The default pattern is "*". This option will resolve variables.

    Note: The COPY/LIST DIRECTORY commands recognize the "name" (NAME) portion of a filename as the character(s) that preceed a period (or the entire filename if it does not include a period) and the "extension" (EXT) portion of a filename are character(s) that follow a period. For example, for filename myfile.txt the "name" portion is "myfile" and the "extension" portion is "txt". To match filenames whose name begins with "my" and whose extension is "txt", you could specify options NAME my* EXT txt.

    TYPE specifies the types of child entries to return. These types are the same types described in section 8.4.5, "GET ENTRY", with the addition of '!', which, when specified along with 'D', includes the special directories '.' and '..'. You may also specify the string "ALL" to include all entry types. By default, only files and non-special directories are included. This option will resolve variables.

    SORTBYNAME specifies that the list of child entries should be sorted by their name.

    SORTBYSIZE specifies that the list of child entries should be sorted by their size.

    SORTBYMODTIME specifies that the list of child entries should be sorted by their last modification time.

    Note: If none of the sorting options is used, the default is not to sort the list. It will be in the same order as returned by the operating system, which is not guaranteed to perform any sorting of its own.

    CASESENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case sensitive manner. It also affects the sorting performed by SORTBYNAME.

    CASEINSENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case insensitive manner. It also affects the sorting performed by SORTBYNAME.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE.

    LONG specifies that the list of child entries should include their name, type, size, and last modification time. By default the list only includes the name of the entry.

    FORMAT specifies that the LONG listing should be formatted in a way that makes it easier to read by humans. The default LONG listing is formatted to make it easier to parse by an application.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the contents of the specified directory. If LONG was not specified, the format will be

    <Name 1>
    <Name 2>
    <Name N>
    

    If LONG was specified without FORMAT, the format will be

    <Name 1>;<Type 1>;<Size 1>;<Last Modification Time 1>
    <Name 2>;<Type 2>;<Size 2>;<Last Modification Time 2>
    <Name N>;<Type N>;<Size N>;<Last Modification Time N>
    

    If LONG and FORMAT were specified, the format will look like the following example

    D     0 20010213-16:42:42 WINNT
    F  209K 19991207-12:00:00 ntldr
    F 34468 20010214-09:53:24 NTDETECT.COM
    F   512 20010213-16:44:22 bootsect.dos
    D     0 20010213-16:45:28 Documents and Settings
    D     0 20010213-16:45:58 Program Files
    D     0 20010522-11:23:56 Config.Msi
    F     0 20010214-09:22:44 CONFIG.SYS
    F     0 20010214-09:22:44 AUTOEXEC.BAT
    F     0 20010214-09:22:44 IO.SYS
    F     0 20010214-09:22:44 MSDOS.SYS
    D     0 20010214-09:32:38 Recycled
    D     0 20010214-09:41:18 drivers
    D     0 20010214-10:27:02 temp
    F   192 20010214-12:30:58 boot.ini
    D     0 20010215-08:36:12 Lotus
    D     0 20010215-08:40:00 NotesSQL
    F   170 20010215-13:58:44 setup.log
    F  384M 20010727-17:49:44 pagefile.sys
    D     0 20010424-14:23:06 sdwork
    

    Note: When using FORMAT, the size listed will only include the lower 32-bits of the size. It will also use the extensions 'K' and 'M' to represent kilobytes and megabytes, respectively.

    Examples

    Goal: List the contents of the /tmp directory.

    LIST DIRECTORY /tmp
    

    Goal: List only files in the /tmp directory.

    LIST DIRECTORY /tmp TYPE F
    

    Goal: List all the entries in C:\Projects with an extension of "txt". Match this extension in a case sensitive manner.

    LIST DIRECTORY C:\Projects EXT txt CASESENSITIVE
    

    Goal: Produce a formatted listing of the C:\Projects directory sorted by size.

    LIST DIRECTORY C:\Projects LONG FORMAT SORTBYSIZE
    

    8.4.8 CREATE

    CREATE creates a directory.

    Syntax

    CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
    

    DIRECTORY specifies the name of the directory to create. This option will resolve variables.

    FULLPATH specifies that any intermediate parent directories should be created if they don't exist.

    FAILIFEXISTS specifies that the request should generate an error if the specified directory alread exists. By default, the request will succeed if the specified directory already exists.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from CREATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples

    Goal: Create the directory /tmp/tests

    CREATE DIRECTORY /tmp/tests
    

    Goal: Create the directory {Tests/Root} and ensure that any intermediate parent directories are created as well.

    CREATE DIRECTORY {Tests/Root} FULLPATH
    

    Goal: Create the directory D:\TestData. Generate an error if the directory already exists.

    CREATE DIRECTORY D:\TestData FAILIFEXISTS
    

    8.4.9 DELETE

    DELETE deletes a file system entry.

    Syntax

    DELETE ENTRY <Name> [CHILDREN [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
           [CASESENSITIVE | CASEINSENSITIVE]] [RECURSE] [IGNOREERRORS] CONFIRM
    

    ENTRY specifies the name of the file system entry to delete. This option will resolve variables.

    CHILDREN specifies that only children matching NAME, EXT, and TYPE should be deleted. The entry itself will not be deleted.

    NAME specifies a pattern used to match the name of child entries. Only child entries whose name match this pattern will be deleted. The default pattern is "*". This option will resolve variables.

    EXT specifies a pattern used to match the extension of child entries. Only child entries whose extenision match this pattern will be deleted. The default pattern is "*". This option will resolve variables.

    TYPE specifies the types of child entries to delete. These types are the same types described in section 8.4.5, "GET ENTRY". You may also specify the string "ALL" to delete all entry types. By default, all entry types are deleted. This option will resolve variables.

    CASESENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case sensitive manner.

    CASEINSENSITIVE specifies that the patterns specified by NAME and EXT are to be matched in a case insensitive manner.

    Note: If neither CASESENSITIVE nor CASEINSENSITIVE is specified, the default is determined by the operating system -- unix systems default to CASESENSITIVE, all others default to CASEINSENSITIVE.

    RECURSE specifies that the entry's children will be recursively deleted.

    Note: If neither CHILDREN nor RECURSE is used, only the entry itself will be deleted. If RECURSE is specified without CHILDREN then the entry and all of its children will be deleted. If RECURSE and CHILDREN are specified, then only the children matching the specified NAME, EXT, and TYPE will be deleted (i.e., the entry itself will not be deleted).

    IGNOREERRORS specifies that errors encountered (recursively) deleting children should not be returned. By default, all errors encountered while (recursively) deleting children will be returned in the result buffer.

    CONFIRM indicates that you really want the deletion to occur.

    Security

    This command requires trust level 4. If you specify RECURSE, you must have trust level 5.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty. If errors were encountered and IGNOREERRORS was not specified, the result buffer will be formatted like so

    <Failure 1 full path name>;<Failure 1 return code>[:Failure 1 OS return code]
    <Failure 2 full path name>;<Failure 2 return code>[:Failure 2 OS return code]
    <Failure N full path name>;<Failure N return code>[:Failure N OS return code]
    

    The OS return code will only be provided if the return code indicated a base operating system error occured (i.e., if RC == 10).

    Examples

    Goal: Delete the entry /tmp/myfile.txt

    DELETE ENTRY /tmp/myfile.txt CONFIRM
    

    Goal: Delete the directory /tmp/myfiles and all of its children.

    DELETE ENTRY /tmp/myfiles RECURSE CONFIRM
    

    Goal: Recursively delete all the children of C:\TEMP, without deleting the directory itself.

    DELETE ENTRY C:\TEMP CHILDREN RECURSE CONFIRM
    

    Goal: Delete all entries with an extension of "tmp" in C:\MyFiles. Match the extension in a case insensitive manner. Do not recurse down subdirectories.

    DELETE ENTRY C:\TEMP CHILDREN EXT tmp CASEINSENSITIVE CONFIRM
    

    Goal: Recursively delete all files (and only files) under {MyTempFiles} with a base name beginning with "test". Match the name in a case sensitive manner. Do not report an errors during the deletion.

    DELETE ENTRY {MyTempFiles} CHILDREN NAME "test*" RECURSE CASESENSITIVE IGNOREERRORS CONFIRM
    


    8.5 Handle Service

    8.5.1 Description

    The HANDLE service is one of the internal STAF services. It provides the following commands.

    8.5.2 CREATE

    CREATE creates a static handle. A static handle is a handle which can be shared by several processes on the same system. This is most directly useful for shell-scripts which rely on the STAF command, and need to ensure that the same handle is used for every request. See "Using the STAF command from shell-scripts" for more information on how to use static handles with the STAF command.

    Note: Be sure to DELETE any static handles you create via the CREATE command. you

    Syntax

    CREATE HANDLE NAME <Handle Name>
    

    NAME specifies the registered name of the handle.

    Security

    This command requires trust level 5.

    Note: This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from CREATE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the new handle number.

    Examples

    Goal: Create a static handle which will be registered with the name "Script Test"

    CREATE HANDLE NAME "Script Test"
    

    8.5.3 DELETE

    DELETE deletes a static handle.

    Syntax

    DELETE HANDLE <Number>
    

    HANDLE specifies the handle number to delete.

    Security

    This command requires trust level 5.

    Note: This command is only valid if submitted to the local machine, not to remote machines.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will be empty.

    Examples

    Goal: Delete static handle number 42

    DELETE HANDLE 42
    

    8.5.4 QUERY

    QUERY will allow you to display various process' handles. You can query all the handles, only those with a given name, and further restrict the set by only including handles in a certain state.

    Syntax

    QUERY [ALL | NAME <Handle Name>]  [PENDING]  [REGISTERED]  [INPROCESS]  [STATIC]
    

    ALL will retrieve information about all the handles in use.

    NAME specifies that you only want information on handles with the name <Handle Name>.

    PENDING shows handles that are in a pending state. A handle is in pending state when a process has been started via the PROCESS service, but that process has not yet registered with STAF.

    REGISTERED shows handles that are registered with STAF.

    INPROCESS shows handles for external services that are running within the same process as STAFProc.

    STATIC shows static handles. A static handle is a handle which was created using the CREATE command of the HANDLE service or by using the STATICHANDLENAME option when starting a process through the PROCESS service.

    If none of PENDING, REGISTERED, INPROCESS, or STATIC are specified, the default is REGISTERED, INPROCESS, and STATIC, otherwise, only those specified are shown.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a listing of the handles, their registered names, their state, and the date and time of their last use. For example,

    2 STAF_REXX_Monitor InProcess 19980216-08:45:45
    17 <Unknown> Pending 19980216-10:24:13
    42 WebTest1 Registered 19980216-11:23:36
    63 WebTest2 Registered 19980216-11:39:57
    

    Examples

    Goal: Query all the REGISTERED and INPROCESS handles.

    QUERY ALL
    

    might result in the following

    2 STAF_REXX_Monitor InProcess 19980216-08:45:45
    5 STAF_REXX_Logging InProcess 19980216-08:45:55
    30 STAF_REXX_Client Registered 19980216-10:03:29
    

    Goal: Query only handles registered with the name WebTest1.

    QUERY NAME WebTest1
    

    might result in the following

    42 WebTest1 Registered 19980216-11:23:36
    

    Goal: Query all pending handles.

    QUERY ALL PENDING
    

    might result in the following

    17 <Unknown> Pending 19980216-10:24:13
    23 <Unknown> Pending 19980216-10:37:45
    


    8.6 Help Service

    8.6.1 Description

    The Help service is one of the internal STAF services. It allows you to obtain information about the return codes generated by STAF services.

    Note: Prior to version 2.2.0 of STAF, the Help service was an external Rexx service. That service is now obsolete and should no longer be used.

    Note: Error codes of 4000 and beyond are service specific return codes, and not all external services register their return codes with the Help service. Therefore, if you don't find information on a 4000+ return code returned by a service, be sure to check the documentation provided with the service.

    The Help service provides the following commands.

    8.6.2 LIST

    Allows you to list the information managed by the Help service, including

    Syntax

    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.

    Security

    This command requires trust level 2.

    Examples

    1. Goal: Show me all the common STAF return codes

      Syntax: LIST ERRORS

      Results:

          1  Invalid API
          2  Unknown Service
          3  Invalid Handle
          4  Handle Already Exists
          5  Handle Does Not Exist
          6  Unknown Error
          7  Invalid Request String
          8  Invalid Service Result
          9  Rexx Error
         10  Base OS Error
         11  Process Already Complete
         12  Process Not Complete
         13  Variable Does Not Exist
         14  UnResolvable String
         15  Invalid Resolve String
         16  No Path To Machine
         17  File Open Error
         18  File Read Error
         19  File Write Error
         20  File Delete Error
         21  STAF Not Running
         22  Communication Error
         23  Trustee Does Not Exist
         24  Invalid Trust Level
         25  Insufficient Trust Level
         26  STAF Registration Error
         27  Service Configuration Error
         28  Queue Full
         29  No Queue Element
         30  Notifiee Does Not Exist
         31  Invalid API Level
         32  Service Not Unregisterable
         33  Service Not Available
         34  Semaphore Does Not Exist
         35  Not Semaphore Owner
         36  Semaphore Has Pending Requests
         37  Timeout
         38  Java Error
         39  Converter Error
         40  Service already exists
         41  Invalid object
         42  Invalid parm
         43  Request number not found
         44  Invalid asynchronous option
         45  Request not complete
         46  Process authentication denied
         47  Invalid value
         48  Does not exist
         49  Already exists
         50  Directory Not Empty
         51  Directory Copy Error
         52  Diagnostics Not Enabled
         ..
      4000+  Service specific errors
      
    2. Goal: Show me return codes for the Log service

      Syntax: LIST SERVICE Log ERRORS

      Results:

       4001  Invalid number (deprecated)
       4002  Invalid date (deprecated)
       4003  Invalid time (deprecated)
       4004  Invalid level
       4005  Invalid log directory (deprecated)
       4006  Error creating directory (deprecated)
       4007  Invalid file format
       4008  Unable to purge all log records
       4009  No remote log server defined (deprecated)
      
    3. Goal: Show me the services that have registered return codes with the Help service

      Syntax: LIST SERVICES

      Results:

      LOG
      MONITOR
      RESPOOL
      

    8.6.3 ERROR

    Display help information for a particular return code.

    Syntax

    [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

    Security

    This command requires trust level 2.

    Examples

    1. Goal: Show me information on STAF error 22

      Syntax: ERROR 22

      Results:

      Communication Error
       
      This indicates an error transmitting data across the network, or to the
      local STAF process.  For example, you would receive this error if STAFProc.exe
      was terminated in the middle of a service request, or if a bridge went down
      in the middle of a remote service request.
      
    2. Goal: Show me all the information on STAF error 4007

      Syntax: ERROR 4007

      Results:

      LOG service: Invalid file format
       
      An invalid/unknown record format was encountered while reading the log file
       
       
      MONITOR service: Invalid file format (deprecated)
       
      An invalid/unknown record format was encountered while reading the monitor
      file
      
    3. Goal: Show me only Log service information on STAF error 4007

      Syntax: SERVICE Log ERROR 4007

      Results:

      Invalid file format
       
      An invalid/unknown record format was encountered while reading the log file
      

    8.6.4 REGISTER

    Allows a service to register return codes with the Help service.

    Syntax

    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.

    Security

    This command is only valid when issued by local services.

    Examples

    1. Goal: Register the Log services 4008 return code

      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."

    8.6.5 UNREGISTER

    Allows a service to unregister return codes with the Help service.

    Syntax

    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

    Security

    This command is only valid when issued by local services.

    Examples

    1. Goal: Unregister the Log services 4008 return code

      Syntax: UNREGISTER SERVICE Log ERROR 4008

    8.6.6 Help Error Code Reference

    All return codes from Help are documented in Appendix A, "API Return Codes".


    8.7 Log Service

    8.7.1 Description

    The Log service is an external STAF service that provides the following functions:

    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.

    8.7.2 Registration

    The Log service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    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.

    Example

    service log library STAFLog
    service log library STAFLog parms OldReturnCodes
    service log library STAFLog parms "Directory {STAF/Config/STAFRoot}/logdata"
    

    8.7.3 Parameters

    The Log service accepts a parameter string in the following formats

    [DIRECTORY <Log Directory Root>]
    [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
    [RESOLVEMESSAGE | NORESOLVEMESSAGE] [OLDRETURNCODES | NEWRETURNCODES]
    [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
    
    or
    ENABLEREMOTELOGGING REMOTELOGSERVER <Server name>
                        [REMOTELOGSERVICE <Service Name>]
    

    DIRECTORY specifies the root directory under which log files are stored. The default is {STAF/Config/STAFRoot}/data/log.

    MAXRECORDSIZE specifies the maximum length (in characters) of a logged message. The default is 100000.

    DEFAULTMAXQUERYRECORDS specifies the maximum number of records that will be returned if your query criteria selects more records than this number. The default is 0 which means there is no limit on the maximum number of records. If a non-zero value is specified, it's equivalent to specifying LAST <Number>. This limit is only used if none of the following options are specified on a QUERY request: FIRST, LAST, ALL, TOTAL, or STATS.

    RESOLVEMESSAGE specifies that variables in log messages should be resolved by default.

    NORESOLVEMESSAGE specifies that variables in log messages should not be resolved by default. This is the default.

    OLDRETURNCODES specifies that the Log service should return the same error codes it always has. See 8.7.12, "Log Error Code Reference" for more information.

    OLDRETURNCODES specifies that the Log service should return the old error codes used prior to STAF 2.1. See 8.7.12, "Log Error Code Reference" for more information.

    NEWRETURNCODES specifies that the Log service should return the error codes newly defined in STAF 2.1. See 8.7.12, "Log Error Code Reference" for more information. This is the default.

    ENABLERESOLVEMESSAGEVAR specifies that the log service should check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. This option will adversely affect the performance of the Log service. See below for more information.

    DISABLERESOLVEMESSAGEVAR specifies that the log service should not check the value of the STAF/Service/<Name>/ResolveMessage variable to determine if variables in log messages should be resolved. See below for more information. This is the default.

    ENABLEREMOTELOGGING specifies that the Log service should operate in remote/forwarding mode.

    REMOTELOGSERVER specifies the server to which forwarded log requests should be sent.

    REMOTELOGSERVICE specifies the service to which forwarded log requests should be sent. The default is the same name under which the Log service was registered on the local machine.

    Note: All these parameters, with the exception of DIRECTORY, ENABLEREMOTELOGGING, REMOTELOGSERVER, and REMOTELOGSERVICE may be changed with the SET command, see 8.7.10, "SET" for more information.

    8.7.4 Variables

    The following variables will affect the behavior of the Log service.
    STAF/Service/<Name>/Mask: A string of log mask descriptions, or a 32 bit binary mask.
    STAF/Service/<Name>/ResolveMessage: Whether to resolve variables in the message

    STAF/Service/<Name>/Mask

    The variable determines what messages will and will NOT be written to the log file. You can set it to only have FATAL and ERROR messages written to the log file for example, or turn on DEBUG in the middle of a running test. This allows you to put as much informational, trace, debug, status, etc. logging messages into your testcases as you want, but based on the circumstance, dynamically alter the logging levels via configuration, not the testcase.

    See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.

    The log mask contains the set of levels that will actually be logged to the log file.

    Example: var "STAF/Service/Log/Mask=START STOP WARNING FATAL ERROR"
    Default: All logging levels will be logged
    Alternatively, a 32 bit binary string may be specified that determines which logging levels will be applied.
    Example: var STAF/Service/Log/Mask=11111111000000000000000000000000

    STAF/Service/<Name>/ResolveMessage

    This variable determines if messages should be resolved before writing them. If message resolution is desired, then a call to the STAF variable service is made and all variables in the message are resolved. If for any reason the resolution is unsuccessful (e.g. unbalanced braces {}, infinite recursion, etc.) then an error is generated.

    Note: This variable is not checked unless the ENABLERESOLVEMESSAGEVAR option has been set.

    Example: var STAF/Service/Log/ResolveMessage=1
    Default: 0 (messages are NOT resolved)
    If a message was "Machine booted from {STAF/Config/BootDrive}" and STAF/Service/<Name>/ResolveMessage was set to 1 then what would actually be logged would look like: "Machine booted from C:". If STAF/Service/<Name>/ResolveMessage was not defined or set to 0 then the original text of the message would be logged: "Machine booted from {STAF/Config/BootDrive}".

    Note: There are three places where message resolution can be affected. They are evaluated in the following order

    8.7.5 LOG

    Writes data to a log file.

    Syntax

    LOG <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level> MESSAGE <Message>
        [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    GLOBAL indicates you want to write to a global log. The global log is intended to facilitate multiple testcases on multiple machines all writing to a common log.

    MACHINE indicates you want to write to a machine log. The machine log is intended to facilitate multiple testcases on a single machine all writing to a common machine name log.

    HANDLE indicates you want to write to a handle log. The handle log is intended to facilitate each testcase writing to a separate log (no matter how many machines and processes are involved)

    LOGNAME contains the name of the log to which you want to write. This option will resolve variables.

    LEVEL determines the level that you want to log. This can be in the form of level type such as "FATAL", "ERROR", WARNING", etc. or a 32 byte binary string such as "00000000000000000000000000000001". This option will resolve variables. See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.

    MESSAGE contains the message (data) that you want to write to the log. This option will not resolve messages by default but can be configured to do so in the STAF configuration file or by using RESOLVEMESSAGE.

    RESOLVEMESSAGE causes the LOG service to call the STAF variable service to resolve any variables in the message before being written. This overrrides any other message resolution settings.

    NORESOLVEMESSAGE causes the LOG service to not call the STAF variable service. This overrrides any other message resolution settings.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from LOG are documented in 8.7.12, "Log Error Code Reference".

    Results

    The result buffer will contain no data on return from a LOG command.

    Examples

    LOG GLOBAL LOGNAME stresstst LEVEL fatal MESSAGE :33:Testcase aborted with error "255"
    LOG MACHINE LOGNAME stresstst LEVEL 10000000000000000000000000000000 MESSAGE Recovered
    LOG HANDLE LOGNAME stresstst LEVEL start MESSAGE "Step1 in Test1 initiated"

    8.7.6 QUERY

    Allows you to query records from a log based on a set of selection criteria.

    Note: A stand-alone utility also exists, called FmtLog, that can read a log file and write the data to an output file in a readable format. See 10.1, "Format Log Utility" for additional information.

    Syntax

    QUERY  <GLOBAL | [MACHINE <Machine> [HANDLE <Handle>]>  LOGNAME <Logname>
           [LEVELMASK <Mask>]  [QMACHINE <Machine> [QHANDLE <Handle>] ]
           [NAME <Name>]  [FIRST <Num> | LAST <Num> | ALL]  [TOTAL | STATS]
           [CONTAINS <String>]...  [CSCONTAINS <String>]...  
           [LEVELBITSTRING]  [FIELDSEP <Char>]
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
    

    GLOBAL indicates you want to query to a global log. The global log is intended to facilitate multiple testcases on multiple machines all writing to a common log.

    MACHINE indicates you want to query to a machine log. The machine log is intended to facilitate multiple testcases on a single machine all writing to a common log. This option will resolve variables.

    HANDLE indicates you want to query to a handle log. The handle log is intended to facilitate each testcase writing to a separate log. This option will resolve variables.

    LOGNAME contains the name of the log you want to query. All log files have the ".log" extension automatically added to the file name. This option will resolve variables.

    LEVELMASK determines the levels that are selected. This can be in the form of "FATAL ERROR WARNING" or a 32 byte bit string such as "00000000000000000000000000000111". This option will resolve variables.

    QMACHINE selects only those records that originated from a certain machine. This option will resolve variables.

    QHANDLE selects only those records that are associated with a certain handle. This option will resolve variables.

    NAME selects only those records with a certain registered name. This option will resolve variables.

    FIRST selects only the first <num> records. This option will resolve variables.

    LAST selects only the last <num> records. This option will resolve variables.

    ALL selects all the records that meet the query criteria.

    TOTAL display only the total number of records selected instead of the records themselves.

    STATS display the totals for each level instead of the records themselves.

    CONTAINS selects only those records that contain a specified string in the message. Note that this match is case insensitive. Multiple CONTAINS statements are handled as an "or" condition. This option will resolve variables.

    CSCONTAINS selects only those records that contain a specified string in the message. Note that this match is case sensitive. Multiple CSONTAINS statements are handled as an "or" condition. This option will resolve variables.

    LEVELBITSTRING displays the selected records with the level displayed as a 32 byte binary bit string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error. See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.

    FIELDSEP is the character that separates each record field, the default is "|". This option will resolve variables.

    FROM selects only those records that have a date and/or time from the specified format. This option will resolve variables.

    AFTER selects only those records that have a date and/or time after the specified format. This option will resolve variables.

    TO selects only those records that have a date and/or time to the specified format. This option will resolve variables.

    BEFORE selects only those records that have a date and/or time before the specified format. This option will resolve variables.

    Note: <Timestamp> format is date, @time, or date@time (e.g. 19980214, @16:30:45, 19980214@16:30:45)

    Note: The keyword TODAY can be used for the current date in the FROM, AFTER, TO, BEFORE options.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in 8.7.12, "Log Error Code Reference".

    Results

    The result buffer will contain data based on the QUERY command.

    Note: If the query criteria selects more records than allowed by the DefaultMaxQueryRecords parameter/setting (and none of the following options are specified: FIRST, LAST, ALL, TOTAL, or STATS), the return code will be set to 4010 and the result buffer will contain only the 'last' default maximum number of query records.

    Examples

    Assume this example log file called STRESSTST contains the following records:

    DATE     TIME     MACHINE  H  NAME    LEVEL   MESSAGE
    ----------------- -------- -- ------- ------- ----------------------------------
    19980210-18:04:00 automate 37 Test1A  Start   Stress Test 1A Initiated
    19980210-19:37:15 automate 37 Test1A  Trace   Step 1: processing time: 01:31:26
    19980210-19:39:09 automate 37 Test1A  Debug   Step 1: debug: files=23 threads=37
    19980210-22:20:34 automate 37 Test1A  Warning Step 2: File not ready, retry=3
    19980210-22:21:01 automate 37 Test1A  Info    Step 2: File ready on retry 3
    19980211-01:21:39 automate 37 Test1A  Trace   Step 2: processing time: 03:02:41
    19980211-01:21:58 automate 37 Test1A  Debug   Step 2: debug: files=31 threads=54
    19980210-01:37:25 crazy8s  41 Test2   Trace   Step 1: processing time: 03:11:53
    19980210-01:43:46 crazy8s  41 Test2   Debug   Step 1: debug: files=43 threads=67
    19980211-02:53:20 automate 37 Test1A  Error   Step 3: Sharing buffer exceeded
    19980211-02:54:22 automate 37 Test1A  User1   Step 3: Error recovery started
    19980211-04:32:53 automate 37 Test1A  User2   Step 3: Error recovery completed
    19980211-04:33:49 automate 37 Test1A  Trace   Step 3: processing time: 03:10:41
    19980211-04:34:07 automate 37 Test1A  Debug   Step 3: debug: files=78 threads=98
    19980211-08:46:22 automate 37 Test1A  Stop    Stress Test 1A Completed
    19980211-08:47:21 automate 37 Test1A  Pass    Stress Test 1A: Errors=1 Recover=1
    19980211-08:48:46 automate 37 Test1A  Status  Step1=P, Step2=P, Step3=W, TC=P
    ----------------- -------- -- ------- ------- ----------------------------------
    

    Note: The output for these examples are formated for ease of reading in this document, the actual format will vary depending on the field separator.

    Goal: Show me all the trace and debug entries for global log stresstst
    Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
    Results:
    DATE     TIME     MACHINE  H  NAME    LEVEL   MESSAGE
    ----------------- -------- -- ------- ------- ----------------------------------
    19980210-19:37:15 automate 37 Test1A  Trace   Step 1: processing time: 01:31:26
    19980210-19:39:09 automate 37 Test1A  Debug   Step 1: debug: files=23 threads=37
    19980211-01:21:39 automate 37 Test1A  Trace   Step 2: processing time: 03:02:41
    19980211-01:21:58 automate 37 Test1A  Debug   Step 2: debug: files=31 threads=54
    19980210-01:37:25 crazy8s  41 Test2   Trace   Step 1: processing time: 03:11:53
    19980210-01:43:46 crazy8s  41 Test2   Debug   Step 1: debug: files=43 threads=67
    19980211-04:33:49 automate 37 Test1A  Trace   Step 3: processing time: 03:10:41
    19980211-04:34:07 automate 37 Test1A  Debug   Step 3: debug: files=78 threads=98
    
    Goal: Show me all the errors
    Syntax: QUERY GLOBAL LOGNAME stresstst LEVELMASK "ERROR"
    Results:
    DATE     TIME     MACHINE  H  NAME    LEVEL   MESSAGE
    ----------------- -------- -- ------- ------- ----------------------------------
    19980211-02:53:20 automate 37 STest1A Error   Step 3: Sharing buffer exceeded
    
    Goal: How many log records are there?
    Syntax: QUERY GLOBAL LOGNAME stresstst total
    Results: 17
    Goal: Show me everything that happened after I left until I came in on machine AUTOMATE
    Syntax: QUERY GLOBAL LOGNAME stresstst FROM 19980210@19:00:00 QMACHINE automate to today@08:00:00
    Results:
    DATE     TIME     MACHINE  H  NAME    LEVEL   MESSAGE
    ----------------- -------- -- ------- ------- ----------------------------------
    19980210-19:37:15 automate 37 Test1A  Trace   Step 1: processing time: 01:31:26
    19980210-19:39:09 automate 37 Test1A  Debug   Step 1: debug: files=23 threads=37
    19980210-22:20:34 automate 37 Test1A  Warning Step 2: File not ready, retry=3
    19980210-22:21:01 automate 37 Test1A  Info    Step 2: File ready on retry 3
    19980211-01:21:39 automate 37 Test1A  Trace   Step 2: processing time: 03:02:41
    19980211-01:21:58 automate 37 Test1A  Debug   Step 2: debug: files=31 threads=54
    19980211-02:53:20 automate 37 Test1A  Error   Step 3: Sharing buffer exceeded
    19980211-02:54:22 automate 37 Test1A  User1   Step 3: Error recovery started
    19980211-04:32:53 automate 37 Test1A  User2   Step 3: Error recovery completed
    19980211-04:33:49 automate 37 Test1A  Trace   Step 3: processing time: 03:10:41
    19980211-04:34:07 automate 37 Test1A  Debug   Step 3: debug: files=78 threads=98
    
    Goal: Show me everything that happened after I left until I came in that has "THREADS" or "BUFFER" in the message
    Syntax: QUERY GLOBAL LOGNAME stresstst FROM 19980210@19:00:00 to today@08:00:00 CONTAINS threads CONTAINS buffer
    Results:
    DATE     TIME     MACHINE  H  NAME    LEVEL   MESSAGE
    ----------------- -------- -- ------- ------- ----------------------------------
    19980210-01:43:46 crazy8s  41 Test2   Debug   Step 1: debug: files=43 threads=67
    19980210-19:39:09 automate 37 Test1A  Debug   Step 1: debug: files=23 threads=37
    19980211-01:21:58 automate 37 Test1A  Debug   Step 2: debug: files=31 threads=54
    19980211-02:53:20 automate 37 Test1A  Error   Step 3: Sharing buffer exceeded
    19980211-04:34:07 automate 37 Test1A  Debug   Step 3: debug: files=78 threads=98
    
    Goal: Show the statistics for the file.
    Syntax: QUERY GLOBAL LOGNAME stresstst STATS
    Results:
    Error=1
    Warning=1
    Info=1
    Trace=4
    Debug=4
    Start=1
    Stop=1
    Pass=1
    Status=1
    User1=1
    User2=1
    

    8.7.7 LIST

    Allows you to list the names of the log files based on a global, machine, or handle location. Also allows you to list current operational settings

    Syntax

    LIST GLOBAL | MACHINES | MACHINE <Machine> [HANDLES | HANDLE <Handle>]
    
    or
    LIST SETTINGS
    

    GLOBAL indicates you want to list all global logs.

    MACHINES indicates you want to list all the machines which have created machine logs.

    MACHINE indicates you want to list all the machine logs for the specified machine. This option will resolve variables.

    HANDLES indicates you want to list all the handles that have created handle logs for the given machine.

    HANDLE indicates you want to list all the handle logs for the specified handle of the specified machine. This option will resolve variables.

    SETTINGS indicates you want to list the current operational settings.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in 8.7.12, "Log Error Code Reference"

    Results

    The result buffer will contain data based on the LIST command.

    Examples

    Goal: Show me all the global logs.
    Syntax: LIST GLOBAL
    Results:
    StressTST        19980210-14:17:00  Size=120823
    Suite100         19980211-15:45:00  Size=2622
    
    Goal: Show me all the machines that have created machine logs.
    Syntax: LIST MACHINES
    Results:
    aquadyne
    automate
    
    Goal: Show me all the machine logs for machine AUTOMATE.
    Syntax: LIST MACHINE automate
    Results:
    AutoGlob         19980210-10:54:00  Size=1168
    
    Goal: Show me all the handles for machine AUTOMATE that have created logs.
    Syntax: LIST MACHINE automate HANDLES
    Results:
    42
    43
    44
    45
    
    Goal: Show me all the handle logs for machine AUTOMATE and handle 43.
    Syntax: LIST MACHINE automate HANDLE 43
    Results:
    HandLog1         19980210-10:54:00  Size=19043
    HandLog2         19980211-18:23:00  Size=45264
    
    Goal: Show me the current operational settings.
    Syntax: LIST SETTINGS
    Results:
    Remote Logging           : Disabled
    Directory                : C:\STAF\data\log
    Max Record Size          : 100000
    Default Max Query Records:
    Resolve Message          : Disabled
    Return codes             : New
    Resolve Message Var      : Disabled
    

    8.7.8 DELETE

    Delete a log file.

    Syntax

    DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME<Logname> CONFIRM
    

    GLOBAL indicates you want to delete a global log.

    MACHINE indicates you want to delete a machine log. This option will resolve variables.

    HANDLE indicates you want to delete a handle log. This option will resolve variables.

    LOGNAME contains the name of the log you want to delete. This option will resolve variables.

    CONFIRM confirms you really want to delete the log file.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from DELETE are documented in 8.7.12, "Log Error Code Reference".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples 

    DELETE GLOBAL LOGNAME stresstst CONFIRM
    DELETE MACHINE automate LOGNAME autoglob CONFIRM
    DELETE MACHINE automate HANDLE 45 LOGNAME handlog5 CONFIRM

    8.7.9 PURGE

    Purge selected records from a log file. The purge command will lock the log file during the entire purge process. It is recommended that you refrain from logging records to a log file that is being purged.

    Syntax

    PURGE  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname> CONFIRM
           [LEVELMASK <Mask>]  [QMACHINE <Machine> [QHANDLE <Handle>] ]
           [NAME <Name>]  [FIRST <Num> | LAST <Num>] 
           [CONTAINS <String>]...  [CSCONTAINS <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
    

    GLOBAL indicates you want to purge a global log.

    MACHINE indicates you want to purge a machine log. This option will resolve variables.

    HANDLE indicates you want to purge a handle log. This option will resolve variables.

    LOGNAME contains the name of the log you want to purge. This option will resolve variables.

    CONFIRM confirms you really want to purge the log file.

    Purge allows almost the same selection options as Query. See 8.13.9, "QUERY" for a list of valid purge selection options with the exception of LAST, TOTAL, STATS, LEVELBITSTRING and FIELDSEP not allowed.

    Note: If your purge selection criteria selects every record in the log file, you will receive an error indicating you need to use DELETE.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from PURGE are documented in 8.7.12, "Log Error Code Reference".

    Results

    The result buffer will contain (number of records purged)/(total records).

    Examples 

    Goal: Purge all the trace and debug entries for global log stresstst
    Syntax: PURGE GLOBAL LOGNAME stresstst CONFIRM LEVELMASK "TRACE TRACE2 TRACE3 DEBUG DEBUG2 DEBUG3"
    Results: 8/17

    8.7.10 SET

    The SET command allows you to change the operation parameters of the Log service.

    Syntax

    SET  [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
         [OLDRETURNCODES | NEWRETURNCODES]
         [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
         [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    See section 8.7.3, "Parameters" for a description of these options.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in 8.7.12, "Log Error Code Reference".

    Results

    The result buffer will contain a description of the new settings.

    Examples 

    Goal: Change the maximum record size to 1024
    Syntax: SET MaxRecordSize 1024
    Results:
    Max Record Size          : 1024
    
    Goal: Change the default maximum number of records to return on a query to 100
    Syntax: SET DefaultMaxQueryRecords 100
    Results:
    Default Max Query Records: 100
    
    Goal: Turn on new return codes and message resolution
    Syntax: SET NewReturnCodes ResolveMessage
    Results:
    Resolve Message          : Enabled
    Return codes             : New
    

    8.7.11 Logging Levels Reference

    Logging levels consist of a 32 byte binary string that represents the level type of each record. You can use the 32 byte binary string or the description of the level type when referencing a level. The following are the valid logging levels along with their appropriate 32 byte binary string:


    Table 6. Logging Levels Reference
    Level Definition 32 Byte Bit String Representation
    Fatal 00000000000000000000000000000001
    Error 00000000000000000000000000000010
    Warning 00000000000000000000000000000100
    Info 00000000000000000000000000001000
    Trace 00000000000000000000000000010000
    Trace2 00000000000000000000000000100000
    Trace3 00000000000000000000000001000000
    Debug 00000000000000000000000010000000
    Debug2 00000000000000000000000100000000
    Debug3 00000000000000000000001000000000
    Start 00000000000000000000010000000000
    Stop 00000000000000000000100000000000
    Pass 00000000000000000001000000000000
    Fail 00000000000000000010000000000000
    Status 00000000000000000100000000000000
    <Reserved1> 00000000000000001000000000000000
    <Reserved2> 00000000000000010000000000000000
    <Reserved3> 00000000000000100000000000000000
    <Reserved4> 00000000000001000000000000000000
    <Reserved5> 00000000000010000000000000000000
    <Reserved6> 00000000000100000000000000000000
    <Reserved7> 00000000001000000000000000000000
    <Reserved8> 00000000010000000000000000000000
    <Reserved9> 00000000100000000000000000000000
    User1 00000001000000000000000000000000
    User2 00000010000000000000000000000000
    User3 00000100000000000000000000000000
    User4 00001000000000000000000000000000
    User5 00010000000000000000000000000000
    User6 00100000000000000000000000000000
    User7 01000000000000000000000000000000
    User8 10000000000000000000000000000000

    Note: The User1-8 logging levels have been set aside for the user of STAFLog to implement as deemed necessary. You may decide that for a testcase or test suite that you want to log a certain behavior as "User1" for example. This will enable you to easily extract log records associated with level "User1".

    Note: The <Reserved1-8> levels cannot be used and as the name implies, they are reserved by STAF for future use. If you would like to see a common logging level added to this list, please contact the document owners for discussion.

    8.7.12 Log Error Code Reference

    In addition to the common STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Log return codes are defined:

    Note: Error codes 4001, 4002, 4003, 4005, 4006, and 4009 are now deprecated and are no longer returned by the Log service. They are documented here for those still using an older version of the Log service.

    Table 7. Log Service Return Codes
    Error Code Meaning Comment
    4001 Invalid number: <input> An invalid number was specified, maybe for FIRST or LAST
    4002 Invalid date: <input> An invalid date format was specified, try YYYYMMDD, or MM/DD/YY
    4003 Invalid time: <input> An invalid time was specified, try HH:MM or HH:MM:SS
    4004 Invalid level specified An invalid logging level was specified, See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.
    4005 Unable to determine file location in configuration The STAF/Service/<Name>/Directory variable in the STAF configuration is invalid.
    4006 Error creating directory: <dir> Unable to create the directories for the log files.
    4007 Invalid file format Error reading the log data due to an error in the file format.
    4008 Failed attempting to purge all records, use DELETE Your purge criteria selected every record to be purged from a log file. Use DELETE if you really want to delete every record or modify your purge criteria.
    4009 No Remote Log Server Defined Remote Log could not find the STAF/Service/<Name>/LogServer variable definition in the STAF configuration file. This variable defines where the ultimate log server resides (e.g. fa1c.test.austin.ibm.com).
    4010 Exceeded default maximum query records Your query criteria selected more records than allowed by the DefaultMaxQueryRecords setting. Use the FIRST <Num> or LAST <Num> option to specify the number of records or the ALL option if you really want all of the records.


    8.8 Misc Service

    8.8.1 Description

    The MISC service is one of the internal STAF services. It provides a home for miscellaneous commands.

    8.8.2 MACHINE

    Given the long name of a machine (e.g. fa2a.test.austin.ibm.com), returns either the long or short name (STAF configuration dependent). This command is primarily used by other services (such as RLog).

    Syntax

    MACHINE <LongName>
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from MACHINE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain either the short or long name of the machine

    Examples

    Goal: Return the appropriate machine name.

    MACHINE fa2a.test.austin.ibm.com
    

    might result in the following

    fa2a
    

    8.8.3 VERSION

    VERSION will display the STAF version number that is currently running.

    Syntax

    VERSION
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from VERSION are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the version number.

    Examples

    Goal: Display the version of STAF running.

    VERSION
    

    might result in the following

    2.2.0
    

    8.8.4 TRACE

    TRACE allows you to interact with STAF tracing. You may enable or disable various STAF trace points, change the trace output destination, and list the current trace output destination and enable trace points.

    Note: If you enable one or more of the "service" tracepoints (e.g. ServiceRequest, ServiceResult, ServiceError, ServiceAccessDenied, or RemoteRequests), these trace messages will only be reported for the services you have enabled for tracing.

    The format of each trace message is the following

    <Timestamp>;<Thread>;<Trace Point>;<Message>
    

    <Timestamp> is the date/time of the message.

    <Thread> is the thread on which the message originated.

    <Trace Point> is the hexadecimal representation of the message's trace point. See table below.

    <Message> is the actual trace message.

    For example,

    19980512-16:20:50;1;00000010;Service HELP: Initializing
    

    Table 8. Trace point hexadecimal representation
    Hex Trace point
    00000001 Service Request
    00000002 Service Result
    00000004 Service Error
    00000008 Service Access Denied
    00000010 Service Management
    00000020 Remote Requests
    00000100 Error
    00000200 Registration
    00000400 Warning
    00000800 Info
    00001000 Deprecated

    Syntax

    TRACE <ON | OFF> [ServiceRequest] [ServiceResult] [ServiceError]
                     [ServiceAccessDenied] [ServiceManagement]
                     [Registration] [RemoteRequests]
                     [Error] [Warning] [Info] [Deprecated] [All]
    TRACE TO <STDOUT | STDERR | FILE <Filename> >
    TRACE [ALL] SERVICES [Service list]
    TRACE LIST
    

    ON indicates that you wish to enable certain trace points.

    OFF indicates that you wish to disable certain trace points.

    ServiceRequest indicates the trace point which causes a trace message to be generated for every incoming service request before it is processed by the service.

    ServiceResult indicates the trace point which causes a trace message to be generated for every incoming service request after it is processed by the service. This option overrides the ServiceError and ServiceAccessDenied options.

    ServiceError indicates the trace point which causes a trace message to be generated for every incoming service request which results in a non-zero error code. This option overrides the ServiceAccessDenied option.

    ServiceAccessDenied indicates the trace point which causes a trace message to be generated for every incoming service request which results in an "Insufficient Trust Level" (aka "Access Denied") error code.

    ServiceManagement indicates the trace point which causes a trace message to be generated for service management operations such as service initialization and termination.

    Registration indicates the trace point which causes a trace message to be generated for every registration or unregistration done by a process.

    RemoteRequests indicates the trace point which enables trace message to be generated for requests destined for other machines.

    Error indicates the trace point which causes a trace message to be generated for error conditions that STAF detects, such as broken communication connections and fatal REXX Service errors. The Error trace point is turned on by default.

    Warning indicates the trace point which causes a trace message to be generated for warning conditions that STAF detects.

    Info indicates the trace point which causes a trace message to be generated for information conditions that STAF detects.

    Deprecated indicates the trace point which causes a trace message to be generated for deprecated options that STAF detects. A deprecated option is not recommended for use, generally due to improvements, and a replacement option is usually given. Deprecated options may be removed in future implementations. The Deprecated trace point is turned on by default.

    All indicates all the aforementioned trace points.

    STDOUT indicates that trace messages should be sent to the standard output device (stdout).

    STDERR indicates that trace messages should be sent to the standard error device (stderr).

    FILE indicates that trace messages should be sent to the indicated file. Note that the path to the file must already exist. This option will resolve variables.

    SERVICES indicates which services should be enabled for tracing. The default is all services.

    ALL indicates that tracing should be enabled for all services.

    LIST indicates that you wish to see the current trace output destination as well as a list of the enabled trace points and services.

    Security

    TRACE LIST requires trust level 2. All other TRACE command require trust level 5.

    Return Codes

    All return codes from TRACE are documented in Appendix A, "API Return Codes".

    Results

    For TRACE LIST the result buffer will contain data formatted as follows.

    Tracing to: STDOUT
     
    Trace points enabled:
     
    ServiceAccessDenied
    Error
    Deprecated
     
    Services to trace:
     
    PROCESS
    VAR
    

    where Tracing to: indicates the current trace output destination, and there will be one line per enabled trace point following Trace points enabled: or None will be displayed if no trace points are enabled, and there will be one line per enabled service following Services to trace: or All will be displayed if tracing is enabled for all services..

    For all other TRACE commands the result buffer will be empty on successful return.

    Examples

    1. Goal: Send trace output to the standard error device

      Syntax: TRACE TO STDERR

    2. Goal: Send trace output to the file STAF.trc in the bin directory under {STAF/Config/STAFRoot}

      Syntax: TRACE TO FILE {STAF/Config/STAFRoot}\bin\STAF.trc

    3. Goal: Enable the service request and service management trace points

      Syntax: TRACE ON ServiceRequest ServiceManagement

    4. Goal: Disable the service result and error trace points

      Syntax: TRACE OFF ServiceResult Error

    5. Goal: Disable all trace points

      Syntax: TRACE OFF All

    6. Goal: Enable tracing for remote requests

      Syntax: TRACE ON RemoteRequests

    7. Goal: Enable the error, warning, info, and deprecated trace points

      Syntax: TRACE ON Error Warning Info Deprecated

    8. Goal: Enable tracing only for the PROCESS and QUEUE services

      Syntax: TRACE SERVICES "PROCESS QUEUE"

    9. Goal: Enable tracing for all services

      Syntax: TRACE ALL SERVICES

    10. Goal: Display the current tracing information

      Syntax: TRACE LIST


    8.9 Monitor Service

    8.9.1 Description

    The Monitor service is an external STAF service that provides the following functions: The purpose of the Monitor service is to give a test case the ability to write status messages. This allows someone to query a process or workload and easily get the current status. The Monitor service only keeps the last monitor message it receives from a particular machine and process. A "centralized network clipboard" is a term that could be used to describe the Monitor service.

    8.9.2 Registration

    The Monitor service is written in C and since it is an external service, it must be registered with the SERVICE configuration statement. The syntax is:
    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.

    Example

    service Monitor library STAFMon PARMS "RESOLVEMESSAGE OLDRETURNCODES"
    

    8.9.3 Variables

    The following variables are defined in the STAF configuration file and Monitor will query their values:
    STAF/Service/<Name>/ResolveMessage: Whether to resolve variables in the message

    STAF/Service/<Name>/ResolveMessage

    This flag determines if messages should be resolved before writing them. If message resolution is desired, then a call to the STAF variable service is made and all variables are resolved. If for any reason the resolution is unsuccessful (i.e. unbalanced braces {}, infinite recursion, etc.) then an error code will be returned.

    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.

    Example: var STAF/Service/<Name>/ResolveMessage=1
    Default: 0
    An example would be a monitor message of "Machine booted from {STAF/Config/BootDrive}", if STAF/Service/<Name>/ResolveMessage was set to 1 then what would actually be logged would look like: "Machine booted from C:". If STAF/Service/Monitor/ResolveMessage was set to 0 then the original text of the message would be logged: "Machine booted from {STAF/Config/BootDrive}".

    8.9.4 LOG

    Writes monitor data.

    Syntax

    LOG MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
    

    MESSAGE contains the message (data) that you want to write to the monitor. This option will not resolve messages by default but can be configured to do so in the STAF configuration file or by using RESOLVEMESSAGE.

    RESOLVEMESSAGE causes the MONITOR service to call the STAF variable service to resolve any variables in the message before being written.

    NORESOLVEMESSAGE causes the MONITOR service to not call the STAF variable service to resolve any variables in the message.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".

    Results

    The result buffer will contain no data on return from a LOG command.

    Examples

    LOG MESSAGE :33:Testcase aborted with error "255"
    LOG MESSAGE "Step1 in Test1 initiated on bootdrive {STAF/Config/BootDrive}"
    LOG MESSAGE Recovered

    8.9.5 QUERY

    Allows you to query a message from a monitor based on the machine and process handle that generated the monitor message.

    Syntax

    QUERY MACHINE <Machine> HANDLE <Handle>
    

    MACHINE determines what machine the monitor message originated from. This option will resolve variables.

    HANDLE determines the process handle that originated the message. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in 8.9.9, "Monitor Error Code Reference".

    Results

    The result buffer will contain data based on the QUERY command.

    Examples

    Goal: Show me the monitor message from machine automate and process handle 12
    Syntax: QUERY MACHINE automate HANDLE 12
    Results:
    19980210-19:37:15 Testcase aborted with error "255"
    

    8.9.6 LIST

    Allows you to list Monitor settings, the names of the machines that have logged monitor data, or the monitor information for a given machine.

    Syntax

    LIST MACHINES | MACHINE <Machine> | SETTINGS
    

    MACHINES indicates you want list all the machine names that have created monitor data.

    MACHINE indicates you want to list the monitor data for the specified machine. This option will resolve variables.

    SETTINGS returns the Monitor settings.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".

    Results

    The result buffer will contain data based on the LIST command.

    Examples

    Goal: Show me all the machines that have written monitor data.
    Syntax: LIST MACHINES
    Results:
    aquadyne
    automate
    
    Goal: Show me all the monitor information (Handle) for machine automate.
    Syntax: LIST MACHINE automate
    Results:
    6........................  19980922-02:17:00  Size=43
    21.......................  19980930-15:08:00  Size=148
    45.......................  19981001-18:38:00  Size=41
    
    Goal: Show me all the Monitor settings.
    Syntax: LIST SETTINGS
    Results:
    Max Record Size    : 512
    Resolve Message    : Enabled
    Return codes       : New
    Resolve Message Var: Disabled
    

    8.9.7 DELETE

    The DELETE command will delete monitor files and directories.

    Syntax

    DELETE [BEFORE <Timestamp>] CONFIRM
    

    BEFORE specifies that you only want to delete monitor data recorded prior to the specified timestamp. If BEFORE is not specified, all monitor data will be removed. The keyword TODAY can be used for <Timestamp> to delete all data prior to the current system date.

    CONFIRM confirms you really want to delete the monitor data.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".

    Results

    The result buffer will contain no data on return from a DELETE command.

    8.9.8 SET

    Sets monitor service options.

    Syntax

    SET  [RESOLVEMESSAGE | NORESOLVEMESSAGE]
         [OLDRETURNCODES | NEWRETURNCODES] [MAXRECORDSIZE <Size>]
         [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
    

    RESOLVEMESSAGE causes the MONITOR service to call the STAF variable service to resolve any variables in Monitor Log messages before being written.

    NORESOLVEMESSAGE causes the MONITOR service to not call the STAF variable service to resolve any variables in Monitor Log messages before being written. This is the default.

    OLDRETURNCODES specifies that the MONITOR service should return the old error codes used prior to STAF 2.1. See 8.9.9, "Monitor Error Code Reference" for more information.

    NEWRETURNCODES specifies that the MONITOR service should return the error codes newly defined in STAF 2.1. See 8.9.9, "Monitor Error Code Reference" for more information. This is the default.

    MAXRECORDSIZE <Size> sets the Maximum record size for Monitor data. The default is 1024 bytes.

    ENABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to be queried for every Monitor Log command, to determine if variables in the Monitor Log command should be resolved.

    DISABLERESOLVEMESSAGEVAR causes STAF/Service/<Name>/ResolveMessage variable to not be queried for every Monitor Log command. This is the default.

    The highest priority in defining whether variables in a Monitor Log command are to be resolved will be the RESOLVEMESSAGE/NORESOLVEMESSAGE specified directly in the Log command. If the Monitor Log command contains neither option, then if ENABLERESOLVEMESSAGEVAR is set, the variable STAF/Service/<Name>/ResolveMessage will be examined to determine whether to resolve the message. If DISABLERESOLVEMESSAGEVAR is set, then the RESOLVEMESSAGE/NORESOLVEMESSAGE option (set via the PARMS options or by use of the SET RESOLVEMESSAGE/NORESOLVEMESSAGE Monitor command) will be honored.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from MONITOR are documented in 8.9.9, "Monitor Error Code Reference".

    Results

    The result buffer will contain the option requested to be set.

    Examples

    SET RESOLVEMESSAGE
    Results:
    Resolve Message    : Enabled
    
    SET OLDRETURNCODES MAXRECORDSIZE 512
    Results:
    Max Record Size    : 512
    Return codes       : Old
    

    8.9.9 Monitor Error Code Reference

    In addition to STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Monitor return codes are defined:

    Note: Error codes 4005, 4006, and 4007 are now deprecated and are no longer returned by the Monitor service. They are documented here for those still using an older version of the Monitor service.

    Table 9. Monitor Service Return Codes
    Error Code Meaning Comment
    4005 Unknown/invalid drive specified The STAF/Service/<Name>/Directory variable in the STAF configuration file is invalid. Insure a valid drive and path is specified.
    4006 Error creating directory Unable to create the directories for the monitor files. Insure a valid drive and path is specified.
    4007 Invalid file format Error reading the monitor message due to an error in the file format


    8.10 Ping Service

    8.10.1 Description

    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.

    8.10.2 PING

    Syntax

    PING
    

    Security

    This command requires trust level 1.

    Return Codes

    All return codes from PING are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain PONG on a successful return from a PING command.

    Examples

    Goal: See if STAFProc is running on a given machine.

    PING
    


    8.11 Process Service

    8.11.1 Description

    The PROCESS service is one of the internal STAF services. It provides the following commands

    8.11.2 START

    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.

    Syntax

    START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>]  [WORKDIR <Directory>]
          [VAR <Variable=Value>]  [ENV <Variable=Value>] [USEPROCESSVARS]
          [WORKLOAD <Name>]  [TITLE <Title>]  [WAIT [<Timeout>] | ASYNC]
          [STOPUSING <Method>] [NEWCONSOLE | SAMECONSOLE]
          [USERNAME <User name> [PASSWORD <Password>]]
          [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STATICHANDLENAME <Name>]
          [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
          [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
          [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
          [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>]  [MACHINE <Machine>]
          [PRIORITY <Priority>] [KEY <Key>]]
    

    WORKLOAD allows you to specify the name of the workload for which this process is a member. This may be useful in conjunction with other PROCESS commands. The default is no workload name. This option will resolve variables.

    TITLE allows you to specify the program title of the process. Unless overridden by the process, the TITLE will be the text that is displayed on the title bar of the application.

    COMMAND specifies the actual command that you want to start. If the path to the command is not specified, the system PATH will be searched for the command. Only actual executable files, such as .EXEs, can be STARTed. Rexx files cannot be STARTed directly. On OS/2, they need to be started through a command processor, such as cmd.exe. On Win32 systems, they need to be started through REXX.EXE. This option will resolve variables.

    PARMS specifies any parameters that you wish to pass to the command. This option will resolve variables.

    SHELL specifies that COMMAND should be started via a separate shell. Using a separate shell allows complex commands involving pipelines to be readily executed. Note, if COMMAND and PARMS are both specified they will be concatenated with a space between them, and the resulting string is what will be executed. Note that on Windows 95/98/Me, when a process is started with the SHELL option, the process's return code will always be zero, even if the process ended with a non-zero return code. On Windows NT/2000/XP/2003, the actual return code of the process will be returned. You may specify an optional shell, which overrides any defaults specified in the STAF configuration file. See 4.6, "Operational parameters" for more information on how to specify the shell. This option will resolve variables.

    WORKDIR specifies the directory from which the command should be executed. If you do not specify WORKDIR, the command will be started from whatever directory STAFProc is currently in. This option will resolve variables.

    WAIT specifies that the START command should not return until the process has finished executing. You may specify an optional timeout, in milliseconds, after which the submit call should return. By default, the submit call will block indefinitely. If the WAIT does not timeout, the process termination information will not be saved after the process ends, and no FREE is necessary. This option will resolve variables.

    ASYNC specifies that the process should be started asynchronously, and that the START command should return to the caller as soon as the processes has begun execution. In this case, the process termination will be saved after the process ends, and will later need to be FREE'd. This is the default.

    VAR allows you to specify variables that go into the process specific variable pool.

    ENV allows you to specify environment variables that will be set for the process. Environment variables may be mixed case, however most programs assume environment variable names will be uppercase, so, in most cases, ensure that your environment variable names are all in uppercase. This option will resolve variables.

    USEPROCESSVARS specifies that variable references should try to be resolved from the variable pool associated with the process being started first. If the variable is not found in this pool, the global variable pool should then be searched.

    STOPUSING allows you to specify the method by which this process will be STOPed, if not overridden on the STOP command. See 8.11.3, "STOP" for more information. This option will resolve variables.

    NEWCONSOLE specifies that the process should get a new console window. This option only has effect on Win32. This is the default for Win32 and OS/2 systems.

    SAMECONSOLE specifies that the process should share the STAFProc console. This option only has effect on Win32. This is the default for Unix systems.

    USERNAME specifies the username under which the process should be started.

    Note: The PROCESSAUTHMODE operational parameter must be enabled in the STAF configuration file on the system where the process is run under a different username. See 4.6, "Operational parameters" for more information on how to enable the PROCESSAUTHMODE operational parameter. There are additional requirements that must be met to run a process under a different username on a Windows system. See "Starting a Process Under a Different User on Windows" for more information.

    PASSWORD specifies the password with which to authenticate the user specified with USERNAME.

    DISABLEDAUTHISERROR specifies that an error should be returned if a USERNAME/PASSWORD is specified but authentication has been disabled. This option overrides any default specified in the STAF configuration file.

    IGNOREDISABLEDAUTH specifies that any USERNAME/PASSWORD specified on the request is ignored if authentication is disabled. This option overrides any default specified in the STAF configuration file.

    STATICHANDLENAME specifies that a static handle should be created for this process. The name specified for this option will be the registered name of the static handle. Using this option will also cause the environment variable STAF_STATIC_HANDLE to be set appropriately for the process. See "Using the STAF command from shell-scripts" for more information on static handles.This option will resolve variables.

    STDIN specifies the name of the file from which standard input will be read.

    STDOUT specifies the name of the file to which standard output will be redirected. If the file already exists, it will be replaced.

    STDOUTAPPEND specifies the name of the file to which standard output will be redirected. If the file already exists, the process' standard output will be appended to it.

    STDERR specifies the name of the file to which standard error will be redirected. If the file already exists, it will be replaced.

    STDERRAPPEND specifies the name of the file to which standard error will be redirected. If the file already exists, the process' standard error will be appended to it.

    STDERRTOSTDOUT specifies that standard error should be redirected to the same file to which standard output is being redirected. This option is valid only if STDOUT or STDOUTAPPEND or RETURNSTDOUT is specified.

    RETURNSTDOUT specifies that the contents of the file to which standard output was redirected should be returned when the process completes. If STDOUT is not specified, standard output will be redirected to a temporary file. If STDERRTOSTDOUT is specified, the file returned will contain both standard output and standard error. This information is only available if using the WAIT or NOTIFY options.

    RETURNSTDERR specifies that the contents of the file to which standard error was redirected should be returned when the process completes. If STDERR is not specified, standard error will be redirected to a temporary file. This information is only available if using the WAIT or NOTIFY options.

    RETURNFILE specifies that the contents of the specified file should be returned when the process completes. This information is only available if using the WAIT or NOTIFY options. This option will resolve variables.

    NOTIFY ONEND specifies that you wish to send a notification when this process ends. See 8.11.6, "NOTIFY REGISTER/UNREGISTER" for the content of the notification message.

    MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    KEY specifies a key that will be included in the notification message. This option will resolve variables.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables.

    Note: On Win32 systems, if you are redirecting stdin/out/err and are not using SAMECONSOLE, it is recommended that you redirect all three input/output streams. If you any one or two streams are redirected, but not all three, the non-redirected streams will not be available to the application. For example, if stdout and stderr are redirected, but not stdin, then the application will receive errors if it tries to read from standard input. As another example, if stdin and stdout are redirected, but not stderr, then you will not see any of the standard error output displayed in the console window. This problem only occurs when using NEWCONSOLE, which is the default. You may freely redirect any combination of stdin, stdout, and stderr when using SAMECONSOLE. This problem is due to a known limitation in the Win32 API.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from START are documented in Appendix A, "API Return Codes".

    Results

    If WAIT was specified and the submit call did not timeout, the result buffer will contain the return code from the process, the KEY (if one was specified with the NOTIFY ONEND option), as well as any files specified by RETURNSTDOUT, RETURNSTDERR, RETURNFILE. The format of the result buffer in this case will look like the following.

    <Process return code>[;KEY=key][;<# of files returned>;{<File N return code>:<File N length>:<File N data>}]
    

    Files we be returned in the order of standard output, then standard error, then any files specified with RETURNFILE. The <File N return code> is a standard STAF return code indicating the success or failure of retrieving the file's contents. As an example, assume that the standard output of a process was simply "a", and that the standard error of a process was simply "b", and that you asked for both of these to be returned. The STAF result buffer would look like the following.

    0;2;0:1:a0:1:b
    

    If WAIT was specified but the submit call did timeout, the result buffer will contain the handle of the started process. Note, you will also receive a Timeout error code in this case.

    If ASYNC was specified, or defaulted to, the result buffer will contain the handle of the started process.

    Examples

    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.

    The following examples show the goal and the syntax of the request to submit to the PROCESS service but not the results.

    Starting a Process Under a Different User on Windows

    To start a process under a different user name on a Windows system, the following requirements must be met:

    1. The PROCESSAUTHMODE operational parameter must be set to WINDOWS on the system where the process is run. See 4.6, "Operational parameters" for more information on how to enable the PROCESSAUTHMODE operational parameter.

    2. The Windows system where the process is run must be WinNT/2000/XP/2003 or higher.

    3. The user currently logged on the system where the process is specified to run must be a member of the Administrators group and must have the following user rights: See "Changing User Rights Assignments" for more information on how to change user rights assignments.

    4. On Windows XP systems, the user name specified when starting a process must have a password.

    There are operating system limitations on how many processes can run concurrently under a different user in the same desktop. If you get RC 10 with result 1816, and the user name that the process is being run under is not a member of the Administrator group, then you may want to give it the "Increase quotas" user right so that more processes can run concurrently. See "Changing User Rights Assignments" for more information on how to change user rights assignments.

    If you are having problems starting a process under a different user name, use the Misc service to enable error and warning trace points to see if you get more information.

    Changing User Rights Assignments

    This information is provided to help you change user rights assignments as needed to start a process under a different user name.

    On Windows XP systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:

    1. Open the Control Panel, from the Classic view, double click on "Administrative Tools".
    2. Double click on "Local Security Policy".
    3. Click on "User Rights Assignment".
    4. Double click on the user right you want to view or modify.
    5. Add any users or groups you require.
    6. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.
    On Windows 2000 systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:
    1. Click on Start -> Settings -> Control Panel and double click on "Administrative Tools".
    2. Double click on "Local Security Policy" and double click on "Local Policies".
    3. Double click on "User Rights Assignment".
    4. Double click on the user right you want to view or modify.
    5. Add any user names you require.
    6. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.
    On Windows NT systems, to view or modify user rights assignments in the local security policy, when logged on as an administrator, perform the following:
    1. Click on Start -> Programs -> Administrative Tools (Common) -> User Manager.
    2. On the User Manager's menu bar, click on Policies -> User Rights.
    3. Check the "Show Advanced User Rights" box.
    4. Display the list of Rights.
    5. Double click on the user right in the list that you want to view or modify.
    6. The users and groups who have this right are displayed in the "Grant to:" list.
    7. Add any user names you require.
    8. If the rights for a user currently logged on are changed, the user must logoff for the changes to take effect.

    8.11.3 STOP

    STOP allows you to stop a process that was started via START. You may stop a single process, all processes that are part of a given workload, or all processes started by STAF.

    Syntax

    STOP <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
    

    ALL specifies that you want to stop all running processes that STAF has STARTed. If you wish to do this, you must also specify the CONFIRM option.

    WORKLOAD specifies that you want to stop all processes that are part of a given workload. This option will resolve variables.

    HANDLE specifies that only the specified handle should be stopped.

    USING specifies the method used to stop the process. This option will resolve variables. The following methods are supported:

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from STOP are documented in Appendix A, "API Return Codes".

    Results

    When stopping ALL or a WORKLOAD, the result buffer will contain two numbers separated by a space. First, the number of processes actually stopped. Second, the total number of processes, if ALL was specified, or the number of processes in the workload, if WORKLOAD was specified. These two numbers will be different if some of the processes have already been stopped or have completed execution. For example, if the result buffer contained "2 3" after stopping all processes, it would indicated that one process had already been stopped or had completed execution on its own.

    When stopping a specific handle, the result buffer will be empty.

    Examples

    Goal: Stop process with handle 42.

    STOP HANDLE 42
    

    Goal: Stop all processes in the Web Tests workload.

    STOP WORKLOAD "Web Tests"
    

    Goal: Stop all processes currently running via STAF.

    STOP ALL CONFIRM
    

    Goal: Gracefully stop process with handle 113 using the SIGTERM method.

    STOP HANDLE 113 USING SIGTERM
    

    Goal: Unconditionally stop process with handle 17.

    STOP HANDLE 17 USING SIGKILL
    

    8.11.4 QUERY

    QUERY allows you to obtain information about all of the processes started via STAF, only those processes associated with a certain workload, or only information about a particular process. You may get information about any process started in WAIT mode that is still running and about any process started in ASYNC mode that has not yet been freed.

    Syntax

    QUERY <ALL | WORKLOAD <Name> | HANDLE <Handle>>
    

    ALL specifies that you want information for all current processes.

    WORKLOAD specifies that you want information for all processes that are part of a given workload.

    HANDLE specifies that you only want information for the specified handle.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    When specifying ALL or WORKLOAD, the result buffer will contain information formatted like this

    Handle  WorkLoad     Command      Status
    ------- ------------ ------------ ---------------------------------------------
         43 Web Tests    cmd.exe      Running since 19980215-14:51:23
         56 <Unknown>    tc1.exe      Completed at  19980215-14:59:37 RC: 3
    

    If the process was started with no workload name, the workload column will display <Unknown>.

    If a specific handle was queried, the result buffer will contain information formatted like this

    Handle    : 3
    Name      :
    Workload  :
    Shell     : <No Shell>
    Command   : TestA.exe
    Parms     :
    WorkDir   : D:/Tests
    Start Mode: Async
    Start Date: 19980215
    Start Time: 14:51:23
    End Date  : 19980215
    End Time  : 14:59:37
    RC        : 0
    

    The End Date, End Time, and RC fields will only be filled in if the process has been stopped or run to completion.

    Examples

    Goal: Query the process with handle 42.

    QUERY HANDLE 42
    

    Goal: Query all the processes in the Web Tests workload.

    QUERY WORKLOAD "Web Tests"
    

    Goal: Query all processes in STAF.

    QUERY ALL
    

    8.11.5 FREE

    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.

    Syntax

    FREE <ALL | WORKLOAD <Name> | HANDLE <Handle>>
    

    ALL specifies that you want to free the termination information for all stopped processes.

    WORKLOAD specifies that you want to free the termination information for all processes that are part of a given workload.

    HANDLE specifies that only the termination information for the specified handle should be freed.

    Security

    This command requires trust level 4.

    Return Codes

    All return codes from FREE are documented in Appendix A, "API Return Codes".

    Results

    When specifying ALL or a WORKLOAD, the result buffer will contain two numbers separated by a space. First, the number of processes for which termination information was actually freed. Second, the total number of processes, if ALL was specified, or the number of processes in the workload, if WORKLOAD was specified. These two numbers will be different if some of the processes have not yet been stopped or have not completed execution. For example, if the result buffer contained "2 3" after freeing all termination information, it would indicated that one process had not yet been stopped or had not completed execution on its own.

    When freeing the termination information for a specific handle, the result buffer will be empty.

    Examples

    Goal: Free the termination information for process with handle 42.

    FREE HANDLE 42
    

    Goal: Free the termination information for all the processes in the "Web Tests" workload.

    FREE WORKLOAD "Web Tests"
    

    Goal: Free the termination information for all stopped processes in STAF.

    FREE ALL
    

    8.11.6 NOTIFY REGISTER/UNREGISTER

    NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when a given process ends.

    Syntax

    NOTIFY <REGISTER | UNREGISTER> ONENDOFHANDLE <Handle> [MACHINE <Machine>]
           [PRIORITY <Priority>]  [HANDLE <Handle> | NAME <Name>]
    

    REGISTER indicates you want to register for a notification when a process ends. The content of the message will be of the format STAF/PROCESS/END <Handle>;<Timestamp>;<Return Code>[;<Returned file data>]. For example, STAF/PROCESS/END 43;19980427-15:13:26;0. The <Returned file data> is provided if any of RETURNSTDOUT, RETURNSTDERR, or RETURNFILE were specified when the process was started. The format of this data is discussed in the "Results" section of the START command.

    UNREGISTER indicates you want to unregister a process end notification.

    ONENDOFHANDLE indicates the handle of the process for which you wish to receive the notification. This option will resolve variables.

    MACHINE specifies the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables.

    Security

    These commands require trust level 3.

    Return Codes

    All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.

    Examples

    Goal: Register the current process for a priority 1 notification when the process with handle 14 ends.

    NOTIFY REGISTER ONENDOFHANDLE 14 PRIORITY 1
    

    Goal: Register to have a process end notification sent to all processes with registered name ProcessHandler on machine EventController when process with handle 43 ends.

    NOTIFY REGISTER ONENDOFHANDLE 43 MACHINE EventController NAME ProcessHandler
    

    Goal: Unregister the event notification for handle 43 which is to be sent when process with handle 12 ends.

    NOTIFY UNREGISTER ONENDOFHANDLE 12 HANDLE 43
    

    8.11.7 NOTIFY LIST

    NOTIFY LIST allows you to view the process end notification list for a given process.

    Syntax

    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.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a list of all the registered notifiees. Each entry will either have the format <Priority>:<Machine>:NAME:<Name> or <Priority>:<Machine>:HANDLE:<Handle>, depending on whether the particular notifiee is to be notified by name or handle. For example,

    5:EventController:NAME:ProcessHandler
    1:Client2:HANDLE:23
    

    Examples

    Goal: Retrieve the list of process end notifiees for the process with handle 57.

    NOTIFY LIST ONENDOFHANDLE 57
    


    8.12 Queue Service

    8.12.1 Description

    The QUEUE service is one of the internal STAF services. It provides the following commands

    8.12.2 QUEUE

    QUEUE allows you to queue a message to a given process handle or to any process registered with a given name.

    Syntax

    QUEUE [HANDLE <Handle> | NAME <Name>]  [PRIORITY <Priority>]  MESSAGE <Message>
    

    HANDLE specifies the process handle to which the message should be queued. If the request is made locally, the default is the handle which originated the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the message should be queued. This option will resolve variables.

    Note: If the request is made to a remote machine then you must specify either HANDLE or NAME.

    PRIORITY specifies the priority of the message to be queued. The default is 5. This option will resolve variables.

    MESSAGE specifies the message to be queued. This option will not resolve variables.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from QUEUE are documented in Appendix A, "API Return Codes".

    Results

    If HANDLE was specified, or defaulted to, the result buffer will contain no data upon return from the submit call.

    If NAME was specified, the result buffer will contain the number of processes to which the message was queued.

    Examples

    Goal: Queue the priority 3 message "Hello World" to yourself.

    QUEUE PRIORITY 3 MESSAGE "Hello World"
    

    Goal: Queue the priority 1 message CONTROL/STAGE2 to all processes with registered name EventController.

    QUEUE NAME EventController PRIORITY 1 MESSAGE CONTROL/STAGE2
    

    Goal: Queue the message Ok to handle 17 using default priority 5.

    QUEUE HANDLE 17 MESSAGE Ok
    

    8.12.3 GET/PEEK

    GET allows you to retrieve and remove an element from the queue. PEEK will retrieve an element from the queue without removing it from the queue.

    Syntax

    GET  [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
         [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]... [WAIT [Timeout] ]
     
    PEEK [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
         [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]... [WAIT [Timeout] ]
    

    PRIORITY specifies that you want to retrieve/remove a message with the given priority. The default is the highest priority message (i.e., the one with the lowest priority number). You may specify this option multiple times. This option will resolve variables.

    MACHINE specifies that you want to retrieve/remove a message originating from the given machine. The default is any machine. You may specify this option multiple times. This option will resolve variables.

    NAME specifies that you want to retrieve/remove a message originating from a process with the given registered name. The default is any name. You may specify this option multiple times. This option will resolve variables.

    HANDLE specifies that you want to retrieve/remove a message originating from a process with the given handle. The default is any handle. You may specify this option multiple times. This option will resolve variables.

    CONTAINS specifies that you want to retrieve/remove a message containing the given string. The search is case sensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    ICONTAINS specifies that you want to retrieve/remove a message containing the given string. The search is case insensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    WAIT specifies that the submit call should not return until an appropriate message is available. You may specify an optional timeout, in milliseconds, after which the submit call should return. If no timeout is specified, the call will block indefinitely. This option will resolve variables.

    Security

    These commands are only valid with respect to the submitting process' queue and if submitted to the local machine.

    Return Codes

    All return codes from GET/PEEK are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain the desired message in the following format

    <Priority>;<Timestamp>;<Machine>;<Name>;<Handle>;<Message>
    

    For example,

    3;19980416-13:56:10;Client2;STAF_Process;1;STAF/START
    

    Examples

    Goal: Wait for, retrieve, and remove the highest priority message in the queue.

    GET WAIT
    

    Goal: Wait for and retrieve, but do not remove, the highest priority message from machine Server1.

    PEEK WAIT MACHINE Server1
    

    Goal: Wait for, retrieve, and remove the highest priority message containing the string STAF/START. Wait a maximum of 30 seconds.

    GET WAIT 30000 CONTAINS STAF/START
    

    Goal: Retrieve a priority 3 message from machine Client3 and registered process name JavaTest1 containing the message referenced by variable TestString.

    PEEK PRIORITY 3 MACHINE Client3 NAME JavaTest1 CONTAINS {TestString}
    

    Goal: Wait for, retrieve, and remove the highest priority message containing either STAF/START or STAF/SHUTDOWN from machine Client1, Client2, or Client3

    GET WAIT CONTAINS STAF/START CONTAINS STAF/SHUTDOWN MACHINE Client1 MACHINE Client2 MACHINE Client3
    

    8.12.4 DELETE

    DELETE allows you to delete a set of messages from the queue.

    Syntax

    DELETE [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
           [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]...
    

    PRIORITY specifies that you want to delete messages with the given priority. The default is any priority. You may specify this option multiple times. This option will resolve variables.

    MACHINE specifies that you want to delete messages originating originating from the given machine. The default is any machine. You may specify this option multiple times. This option will resolve variables.

    NAME specifies that you want to delete messages originating from a process with the given registered name. The default is any name. You may specify this option multiple times. This option will resolve variables.

    HANDLE specifies that you want to delete messages originating from a process with the given handle. The default is any handle. You may specify this option multiple times. This option will resolve variables.

    CONTAINS specifies that you want to delete messages containing the given string. The search is case sensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    ICONTAINS specifies that you want to delete messages containing the given string. The search is case insensitive. The default is any message. You may specify this option multiple times. This option will resolve variables.

    Security

    This command is only valid with respect to the submitting process' queue and if submitted to the local machine.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the number of messages deleted.

    Examples

    Goal: Delete all messages from machine Client2.

    DELETE MACHINE Client2
    

    Goal: Delete all priority 3 messages from processes with registered name JavaTest1

    DELETE PRIORITY 3 NAME JavaTest1
    

    Goal: Delete all priority 3 and 4 messages from the machines referenced by variables Mach1 and Mach2 containing the string STAF/START or the the string referenced by variable StringTest1.

    DELETE PRIORITY 3 PRIORITY 4 MACHINE {Mach1} MACHINE {Mach2}
           CONTAINS STAF/START CONTAINS {StringTest1}
    

    Goal: Delete all messages in the queue.

    DELETE
    

    8.12.5 LIST

    LIST allows you to retrieve the contents of the queue of a given process.

    Syntax

    LIST [HANDLE <Handle>]
    

    HANDLE specifies the handle of the process for which you want the queue contents. The default is the handle of the submitting process. This option may only default if the request was submitted locally. This option will resolve variables.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a list of queue messages in the following format sorted in ascending order by priority.

    <Priority>;<Timestamp>;<Machine>;<Name>;<Handle>;<Message>
    

    For example,

    1;19980416-13:56:10;Client1;STAF_Process;1;STAF/START
    3;19980416-14:01:52;Client3;JavaTest1;36;CONTROL/STAGE2
    3;19980416-14:02:17;Client2;STAF_Process;1;STAF/START
    5;19980416-13:57:36;Client3;JavaTest1;36;CONTROL/STAGE1
    

    Examples

    Goal: Retrieve the contents of the submitting process' queue.

    LIST
    

    Goal: Retrieve the contents of the process with handle 39.

    LIST HANDLE 39
    


    8.13 Resource Pool (ResPool) Service

    8.13.1 Description

    The Resource Pool service is an external STAF service that allows you to manipulate resource pools and contents of the resource pools via the following functions.: The purpose of the Resource Pool service is to manage exclusive access to the entries within resource pools. For example, if you had a group of VM UserIDs and passwords for a particular VM system that needed to be shared amongst numerous testcases, you could create a resource pool for them and then testcases that required a logon to that VM system could request a UserID and password from this resource pool, perform the test, and then release the UserID and password back to the resource pool.

    8.13.2 Registration

    The Resource Pool service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    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.

    Example

    service respool library STAFPool
    service respool library STAFPool parms OldReturnCodes
    service respool library STAFPool parms "Directory {STAF/Config/BootDrive}\STAF\ResPool"
    

    8.13.3 Parameters

    The Resource Pool service accepts a parameter string in the following format:

    [DIRECTORY <Resource Pool Directory Root>] [OLDRETURNCODES | NEWRETURNCODES]
    

    DIRECTORY specifies the root directory under which resource pool files are stored. The default is {STAF/Config/STAFRoot}\data\respool.

    Note: Previously, in STAF 2.2 and earlier, the default root directory for the old REXX version of the Resource Pool service was {STAF/Config/BootDrive}\STAF\ResPool and that the root directory could be changed by setting a Variable named STAF/Service/<Name>/Directory. So, if you want to continue to use these resource pools with the current version of STAF, move the resource pool files to the new default root directory or specify the old root directory for the DIRECTORY parameter.

    OLDRETURNCODES specifies that the Resource Pool service should return the old error codes used prior to STAF 2.3. See 8.13.12, "Resource Pool Error Code Reference" for more information.

    NEWRETURNCODES specifies that the Resource Pool service should return the error codes newly defined in STAF 2.3. See 8.13.12, "Resource Pool Error Code Reference" for more information. This is the default.

    8.13.4 LIST

    LIST displays a list of resource pools and their descriptions.

    Syntax

    LIST
    

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer for LIST will contain a list of resource pools and their descriptions in the following format:

    <Pool Name> - <Pool Description>
      ...
      ...
    

    For example,

    AUSVMR - UserIDs and Passwords for VM System AUSVMR
    AutoTester_Licenses - License numbers for AutoTester
    

    Examples

    Goal:List all of the resource pools

    LIST
    

    8.13.5 CREATE

    Creates a resource pool.

    Syntax

    CREATE POOL <Name> DESCRIPTION <Description>
    

    POOL specifies the name of the resource pool you want to create.

    DESCRIPTION specifies the description of the resource pool.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", CREATE also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from a CREATE command.

    Examples

    Goal: Create a resource pool called AUSVMR with the description "UserIDs and Passwords for VM System AUSVMR"

    CREATE POOL AUSVMR DESCRIPTION "UserIDs and Passwords for VM System AUSVMR"
    

    8.13.6 DELETE

    Deletes a resource pool and all its entries.

    Syntax

    DELETE POOL <Name> CONFIRM [FORCE]
    

    POOL specifies the name of the resource pool you want to delete.

    CONFIRM confirms you really want to delete the resource pool.

    FORCE allows you to force the deletion of the resource pool, even if there are pending requests. If this option is not specified, you will receive an error if you try to delete a resource pool which has pending requests.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", DELETE also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from a DELETE command.

    Examples

    Goal:Delete resource pool AUSVMR, but only if there are no pending requests

    DELETE POOL AUSVMR CONFIRM
    

    Goal:Delete resource pool AUSVM1, even if there are pending requests

    DELETE POOL AUSVM1 CONFIRM FORCE
    

    8.13.7 ADD

    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.

    Syntax

    ADD POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
    

    POOL specifies the name of the resource pool to which you want to add a resource entry.

    ENTRY specifies the actual entry to be added to the resource pool.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", ADD also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the ADD command.

    Examples

    Goal:Add the entries "User1 Password1" and "User2 Password2" to resource pool AUSVMR

    ADD POOL AUSVMR ENTRY "User1 Password1" ENTRY "User2 Password2"
    

    Goal:Add entry 1047923 to resouce pool AutoTester_Licenses

    ADD POOL AutoTester_Licenses ENTRY 1047923
    

    8.13.8 REMOVE

    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.

    Syntax

    REMOVE POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
    

    POOL specifies the name of the resource pool from which you want to remove an entry.

    ENTRY specifies the actual entry to be removed.

    CONFIRM confirms you really want to remove the resource entry.

    FORCE allows you to force the removal of a resource entry which is currently owned. By default, you may only remove a resource entry if it is not currently owned.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", REMOVE also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the REMOVE command.

    Examples

    Goal:Remove entry "User1 Password1" from resource pool AUSVMR, but only if the entry is not currently owned.

    REMOVE POOL AUSVMR ENTRY "User1 Password1" CONFIRM
    

    Goal:Remove entries 1137849 and 1075234 from resource pool AutoTester_Licenses regardless of whether the are currently owned

    REMOVE POOL AutoTester_Licenses ENTRY 1137849 ENTRY 107523 CONFIRM FORCE
    

    8.13.9 QUERY

    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.

    Syntax

    QUERY POOL <Name>
    

    POOL specifies the name of the resource pool you want to query.

    Security

    This command requires trust level 2.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", QUERY also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer for QUERY will contain a list of the entries in the specified pool and indicate whether the resource is available and show the number of pending requests for an entry in the specified pool, if any, and list the pending requests. If the resource is available, the word "Available" will be shown by an entry, otherwise the word "Owned" will be shown by an entry followed by "Owned By" information including the date/time the entry was acquired. The format of the result buffer for QUERY follows:

    Description: <Description>
     
    Pending requests: <Number of pending requests>
     
    Request <Number>: <Machine>;<Process>;<Handle>;<Timestamp>
     
    Resources:
     
    <Resource>;<Owned|Available>[;<Machine>;<Process>;<Handle>;<Timestamp>;<Acquired Timestamp>]
    
    For example,
    Description: UserIDs and Passwords for VM System AUSVMR
     
    Pending requests: 2
     
    Request 1: cd5d;CM2_1;8;19980825-13:07:05
    Request 2: cf2a;JCSHOD;23;19980825-13:07:12
     
    Resources:
     
    RDJSV01 RDJSV01;Owned;cf3c;CM2_1;13;19980825-12:58:05;19980825-12:58:30
    RDJSV02 RDJSV02;Owned;cd1a;JCSHOD;7;19980825-13:02:29;19980825-13:02:51
    RDJSV03 RDJSV03;Owned;cd5a;JCSHOD;25;19980825-13:06:31;19980825-13:06:45
    
    or
    Description: UserIDs and Passwords for VM System AUSVMR
     
    Pending requests: 0
     
    Resources:
     
    RDJSV01 RDJSV01;Owned;cf3c;CM2_1;13;19980825-11:58:05;19980825-11:58:30
    RDJSV02 RDJSV02;Owned;cd1a;JCSHOD;7;19980825-11:59:29;19980825-11:59:51
    RDJSV03 RDJSV03;Available
    RDJSV04 RDJSV03;Available
    RDJSV05 RDJSV05;Available
    

    Examples

    Goal:Query resource pool AUSVMR

    QUERY POOL AUSVMR
    

    8.13.10 REQUEST

    Obtains exclusive access to an entry from the resource pool.

    Syntax

    REQUEST POOL <Name> [TIMEOUT <Timeout>] [FIRST | RANDOM]
    

    POOL specifies the name of the resource pool from which you are requesting a resource.

    TIMEOUT specifies the amount of time in milliseconds that you want to wait for a resource. If no timeout is specified, the request will wait indefinitely.

    FIRST specifies that the first available entry in the resource list should be returned.

    RANDOM specifies that a random available entry should be returned. This is the default.

    Security

    This command requires trust level 3.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", REQUEST also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    On successful return, the result buffer will contain the entry given to the process.

    Examples

    Goal:Request, and wait indefinitely for, the first available entry from resource pool AUSVMR.

    REQUEST POOL AUSVMR FIRST
    

    Goal:Request a random entry from resource pool AutoTester_Licenses. If no entry is available within five minutes (300 seconds), timeout.

    REQUEST POOL AutoTester_Licenses TIMEOUT 300000
    

    8.13.11 RELEASE

    RELEASE allows you to release exclusive access of a resource entry in a resource pool.

    Syntax

    RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
    

    POOL specifies the name of the resource pool to which you are releasing exclusive access of an entry.

    ENTRY specifies the actual entry to which you are releaseing exlusive access.

    FORCE allows you to force the release of the resource entry. By default, only the process that REQUESTED the entry may RELEASE the entry.

    Security

    Command RELEASE requires trust level 3.

    Command RELEASE FORCE requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", RELEASE also returns the return codes documented in 8.13.12, "Resource Pool Error Code Reference".

    Results

    The result buffer will contain no data upon return from the RELEASE command.

    Examples

    Goal:Release exclusive access of entry "User2 Password2" to resource pool AUSVMR

    RELEASE POOL AUSVMR ENTRY "User2 Password2"
    

    Goal:Force the release of entry 1137849 which is a member of resource pool AutoTester_Licenses.

    RELEASE POOL AutoTester_Licenses ENTRY 1137849 FORCE
    

    8.13.12 Resource Pool Error Code Reference

    In addition to STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Resource Pool return codes are defined:

    Note: Error codes 4001, 4002, 4003, and 4004 are now obsolete and are no longer returned by the Resource Pool service. They are documented here for those still using an older version of the Resource Pool service.

    Table 10. Resource Pool Service Return Codes
    Error Code Meaning Comment
    4001 Pool already exists The resource pool you are trying to CREATE already exists.
    4002 Pool does not exist The resource pool you specified does not exist. Use LIST to determine the available resource pools.
    4003 Entry does not exist A resource pool entry you specified does not exist. Use QUERY to determine the valid resource pool entries.
    4004 Entry already exists A resource pool entry you tried to ADD already exists. Resource pool entries must be unique within a given resource pool.
    4005 Not entry owner You are not the owner of the entry you are trying to RELEASE. Use the FORCE option if you are sure that the correct entry is specified.
    4006 Pool has pending requests The resource pool you are trying to DELETE has pending requests. If necessary, use the FORCE option.
    4007 No entries available The resource pool has no entries.
    4008 Create pool path error The directory specified by the DIRECTORY parameter when registering the service or the default directory could not be created.
    4009 Invalid pool file format An error occurred reading the resource pool file due to an error in the file format. If you are using the latest version of the Resource Pool service, contact the STAF authors.
    4010 Entry is owned A resource pool entry you specified to REMOVE is owned. Use the FORCE option if you are sure that the correct entry is specified.


    8.14 Remote Log Service (RLog)

    8.14.1 Description

    This service is now depricated. Its functionality has been moved into the remote logging capabilities of the Log Service (see section 8.7, "Log Service"). This section is here to remind existing RLog service users of the change. This section will be removed in a later version of STAF.


    8.15 Semaphore (SEM) Service

    8.15.1 Description

    The SEM service is one of the internal STAF services. It provides the following commands

    8.15.2 MUTEX

    MUTEX allows you to manipulate a mutex sempahore. A mutex semaphore allows you to synchronize access to a particular resource. You may request exclusive access of the semaphore, release exclusive access of the semaphore, query the semaphore, and delete the semaphore.

    Syntax

    MUTEX <Name> <REQUEST [Timeout]  | RELEASE [FORCE]  | DELETE | QUERY>
    

    MUTEX specifies the name of the mutex semaphore in which you are interested. This option will resolve variables.

    REQUEST specifies that you want exclusive access to the semaphore. Your request is blocked until all prior pending REQUESTs have been RELEASEd. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait to gain access to the semaphore. If no timeout is specified, the request will block indefinitely. The semaphore is created if it does not exist. This option will resolve variables.

    RELEASE specifies that you wish to release exclusive access to the semaphore. Normally, only the owning process may RELEASE the semaphore. Specifying FORCE allows you to force the release of the semaphore.

    Note: Any thread in the owning process may RELEASE the semaphore. This is in contrast to other semaphore systems, where only the REQUESTing thread may release the semaphore.

    DELETE specifies that you wish to delete the semaphore. The semaphore may only be deleted if there are no pending REQUESTs.

    QUERY specifies that you wish to get information on the semaphore, such as, the current owner and pending REQUESTs.

    Security

    Subcommand QUERY requires trust level 2.

    Subcommands REQUEST and RELEASE require trust level 3.

    Subcommands RELEASE FORCE and DELETE require trust level 4.

    Return Codes

    All return codes from MUTEX are documented in Appendix A, "API Return Codes".

    Results

    If REQUEST, RELEASE [FORCE] , or DELETE were specified, the result buffer will contain no data upon return from the submit call.

    If QUERY was specified, the result buffer will contain the word, Unowned, if the semaphore is currently unowned, otherwise it will contain information in the following format,

    Owned by: <Machine>;<Process>;<Handle>;<Timestamp>
    Acquired: <Timestamp>
     
    Pending requests: <Number>
     
    Request <Number>: <Machine>;<Process>;<Handle>;<Timestamp>
    ...
    

    For example,

    Owned by: crankin3;STAF_REXX_Client;7;19980322-21:37:36
    Acquired: 19980322-21:37:36
     
    Pending requests: 0
    

    or

    Owned by: crankin3;STAF_REXX_Client;7;19980322-21:37:36
    Acquired: 19980322-21:40:06
     
    Pending requests: 2
     
    Request 1: automate;SemTest;13;19980322-21:38:58
    Request 2: automate;Server1;27;19980322-21:39:22
    

    Examples

    Goal: Gain exclusive access to semaphore Printers/Printer1.

    MUTEX Printers/Printer1 REQUEST
    

    Goal: Release exclusive access to semaphore Printers/Printer1.

    MUTEX Printers/Printer1 RELEASE
    

    Goal: Gain exclusive access to semaphore DataSource1, but only wait for 30 seconds.

    MUTEX DataSource1 REQUEST 30000
    

    Goal: Delete the Printers/Printer1 semaphore.

    MUTEX Printers/Printer1 DELETE
    

    Goal: Query the information about semaphore DataSource1.

    MUTEX DataSource1 QUERY
    

    8.15.3 EVENT

    EVENT allows you to manipulate an event semaphore. An event sempahore is a signalling mechansim used to synchronize two or more tasks. You may post an event semaphore to signal that the event has happened, reset an event semaphore in preparation for the next event, pulse the event semaphore (which performs an atomic post and reset on the semaphore), wait on an event semaphore, delete an event semaphore, and query an event sempahore.

    Syntax

    EVENT <Name> <POST | RESET | PULSE | WAIT [Timeout]  | DELETE | QUERY>
    

    EVENT specifies the name of the event semaphore in which you are interested. This option will resolve variables.

    POST specifies that you wish to post the event semaphore. It is valid to post a semaphore that is already posted.

    RESET specifies that you wish to reset the event semaphore. It is valid to reset a semaphore that is already reset.

    PULSE specifies that you wish to post and then reset the event semaphore as a single atomic action. It is valid to pulse a semaphore regardless of whether it is currently posted or reset. The semaphore will be in the reset state after the pulse.

    WAIT specifies that you wish to wait for the event semaphore. You may specify a timeout, in milliseconds, indicating the longest you are willing to wait for the event semaphore. If no timeout is specified, the request will block indefinitely. This option will resolve variables.

    DELETE specifies that you wish to delete the event semaphore. The semaphore may only be deleted if there are no processes WAITing for it.

    QUERY specifies that you wish to retrieve information about the event semaphore, such as, whether the semaphore is posted or reset.

    Security

    Subcommand QUERY requires trust level 2.

    Subcommands POST, RESET, PULSE, and WAIT require trust level 3.

    Subcommand DELETE require trust level 4.

    Return Codes

    All return codes from EVENT are documented in Appendix A, "API Return Codes".

    Results

    If POST, RESET, PULSE, WAIT, or DELETE were specified, the result buffer will contain no data upon return from the submit call.

    If QUERY was specified, the result buffer will contain information in the following format

    State: <Posted | Reset>
     
    Last posted: <Machine>;<Process>;<Handle>;<Timestamp>
    Last reset : <Machine>;<Process>;<Handle>;<Timestamp>
    

    If the semaphore is currently in a reset state, the result buffer will contain addtional information in the following format

    Number of waiters: <Number>
     
    Waiter <Number>: <Machine>;<Process>;<Handle>;<Timestamp>
    ...
    

    For example,

    State: Posted
     
    Last posted: crankin3;STAF_REXX_CLient;17;19980322-21:37:43
    Last reset : crankin3;STAF_REXX_Client;15;19980322-21:36:35
    

    or

    State: Reset
     
    Last posted: crankin3;SemTest;26;19980322-21:40:22
    Last reset : automate;SemTest;59;19980322-21:41:01
     
    Number of waiters: 2
     
    Waiter 1: Server1;STAFClnt;39;19980322-21:43:19
    Waiter 2: Client2;STAF_REXX_Client;61;19980322-21:45:46
    

    Examples

    Goal: Wait for event semaphore Server1/LAN_Started

    EVENT Server1/LAN_Started WAIT
    

    Goal: Post event semaphore Server1/LAN_Started

    EVENT Server1/LAN_Started POST
    

    Goal: Reset the event semaphore Coffee/Ready

    EVENT Coffee/Ready RESET
    

    Goal: Pulse the event semaphore Race/StartLap

    EVENT Race/StartLap PULSE
    

    Goal: Wait a maximum of 20 seconds for event semaphore Coffee/Ready

    EVENT Coffee/Ready WAIT 20000
    

    Goal: Delete the event semaphore Shutdown_The_Lab

    EVENT Shutdown_The_Lab DELETE
    

    Goal: Query information about event semaphore Server1/LAN_Started

    EVENT Server1/LAN_Started QUERY
    

    8.15.4 LIST

    LIST allows you to obtain a list of the mutex or event semaphores.

    Syntax

    LIST <MUTEX | EVENT>
    

    MUTEX specifies that you want a list of the mutex sempahores.

    EVENT specifies that you want a list of the event sempahores.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain a list of the desired semaphores. If MUTEX was specified the information will be in the following format

    <Name>: <Unowned | Owned - <Number> pending request(s)>
    

    For example,

    DataSource1: Unowned
    Printers/Printer1: Owned - 2 pending request(s)
    

    If EVENT was specified the information will be in the following format

    <Name>: <Posted | Reset - <Number> waiter(s)>
    

    For example,

    Coffee/Ready: Posted
    Server1/LAN_Started: Reset - 5 waiter(s)
    Shutdown_The_Lab: Reset - 0 waiter(s)
    

    Examples

    Goal: Obtain a list of the of mutex semaphores.

    LIST MUTEX
    

    Goal: Obtain a list of the of event semaphores.

    LIST EVENT
    


    8.16 Service Service

    8.16.1 Description

    The SERVICE service is one of the internal STAF services. It provides the following commands.

    8.16.2 LIST

    LIST will display information about the services or service loaders available on the machine or requests that have been submitted on the machine.

    Syntax

    LIST [SERVICES | SERVICELOADERS | REQUESTS [PENDING] [COMPLETE]]
    

    SERVICES specifies that you want a list of services.

    SERVICELOADERS specifies that you want a list of the service loaders.

    REQUESTS specifies that you want a list of requests.

    PENDING specifies that the request list should include pending requests, i.e. requests which are still being processed.

    COMPLETE specifies that the request list should inlude completed requests which have not yet been FREEd.

    If neither PENDING nor COMPLETE is specified the default is PENDING.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    On successful return, for Services and Service Loaders, the result buffer will contain a listing of the available services, and service specific information. For Requests, the result buffer will contain information about the request in the following format:

    <#>;<State>;<OMachine>;<OProcess>;<OHandle>;<StartTimestamp>;<TMachine>;<Service>;<Request>[;<RC>;<Result>]
    

    # is the request number.

    State is the state of the request. This will be either pending or complete.

    OMachine, OProcess, and OHandle are the machine name, registered process name, and handle of the process that originated the request.

    StartTimestamp is the timestamp when the request started.

    TMachine is the machine to which the request was sent, i.e. the target machine.

    Service is the service to which the request was sent.

    Request is the request which was sent.

    RC is the return code from the request. This will only be displayed if the request State is complete.

    Result is the result buffer from the request. This will only be displayed if the request State is complete.

    Examples

    Goal: List all the services available on a machine.

    LIST SERVICES
    

    might result in the following

    DELAY: Internal
    DIAG: Internal
    ECHO: Internal
    EVENT: External library JSTAF, exec C:\STAF\services\STAFEvent.jar
    FS: Internal
    HANDLE: Internal
    HELP: Internal
    LOG: External library STAFLog
    MISC: Internal
    MONITOR: External library STAFMon
    PING: Internal
    PROCESS: Internal
    QUEUE: Internal
    RESPOOL: External library STAFPool
    RLOG: Delegated to RLOG on ev3c
    SEM: Internal
    SERVICE: Internal
    SHUTDOWN: Internal
    STAX: External library JSTAF, exec C:\STAF\services\STAX.jar
    TRUST: Internal
    VAR: Internal
    ZIP: External library STAFZip
    

    Goal: List all the service loaders available on a machine.

    LIST SERVICELOADERS
    

    might result in the following

    STAF/SERVICELOADER/1: External library STAFDSLS
    STAF/SERVICELOADER/2: External library JSTAF, exec C:\STAF\services\CustomServiceLoader.jar
    

    Goal: List all the pending and complete requests on a machine.

    LIST REQUESTS PENDING COMPLETE
    

    might result in the following

    10;pending;testMachineA;STAF/Client;10;20021228-18:59:55;testMachineX;delay;delay 20000
    11;complete;testMachineA;STAF/Client;8;20021228-18:59:58;testMachineA;misc;version;0;2.1.0
    15;pending;testMachineX;STAF/Client;8;20021228-19:02:24;testMachineA;monitor;help
    18;pending;testMachineA;STAF/Client;11;20021228-19:02:43;testMachineA;service;list requests
    

    8.16.3 ADD

    ADD will add (register and initialize) the specified external service and make it available on the machine.

    Syntax

    ADD SERVICE <Service Name> LIBRARY <Library Name> [EXECUTE <Executable>]
        [OPTION <Name[=Value]>]... [PARMS <Parameters>]
    

    SERVICE specifies the name by which this service will be known on this machine.

    LIBRARY specifies the name of the shared library / DLL which implements the service or acts as a proxy for the service. See the information for each external service to determine the appropriate value for this option.

    EXECUTE is used by service proxy libraries / DLLs to specify what the proxy library should execute. For example, this might be the name of the Java jar file or REXX script which actually implements the service. This option has no significance for non-proxy service libraries. See sections 4.4.2, "RXSTAF service proxy library" and 4.4.3, "JSTAF service proxy library" for information regarding the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documentation provided by the service proxy library.

    OPTION specifies a configuration option that will be passed on to the service library / DLL. This is typically used by service proxy libraries to further control the interface to the actual service implementation. You may specify multiple OPTIONs for a given service. See sections 4.4.2, "RXSTAF service proxy library" and 4.4.3, "JSTAF service proxy library" for acceptable options for the RXSTAF and JSTAF service proxy libraries. Otherwise, see the documentation provided with the service (proxy) library.

    PARMS specifies optional parameters that will be passed to the service during initialization.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from ADD are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain nothing.

    Examples

    Goal: Add the Monitor service, an external C++ service.

    ADD SERVICE Monitor LIBRARY STAFMon
    

    Goal: Add the STAX service, an external Java service, specifying a parameter.

    ADD SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\STAX.jar PARMS "NUMTHREADS 8"
    

    8.16.4 REMOVE

    REMOVE will remove (unregister and terminate) the specified external service, making it no longer available on the machine.

    Syntax

    REMOVE SERVICE <Service Name>
    

    SERVICE specifies the name of the service to remove.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from REMOVE are documented in Appendix A, "API Return Codes".

    Results

    On successful return, the result buffer will contain nothing.

    Examples

    Goal: Remove the Event service.

    REMOVE SERVICE Event
    

    8.16.5 QUERY

    QUERY will return information about requests that have been submitted on the machine.

    Syntax

    QUERY REQUEST <Request Number>
    

    REQUEST indicates the request number to be queried.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from QUERY are documented in Appendix A, "API Return Codes".

    Results

    On successful return the result buffer will contain information about the request in the following format:

    Request Number: 
    Request Status: 
    Source Machine: 
    Source Process: 
    Source Handle : 
    Started       :
    Target Machine:
    Service       :
    Request       :
    Return Code   :
    Result        :
    

    Examples

    Goal: Query the information for request 16.

    QUERY REQUEST 16
    

    might result in the following

    Request Number: 16
    Request Status: pending
    Source Machine: testSystemC
    Source Process: STAF/Client
    Source Handle : 16
    Started       : 20021228-18:59:58
    Target Machine: dave2268
    Service       : delay
    Request       : delay 30000
    Return Code   :
    Result        :
    

    8.16.6 FREE

    FREE returns the results of completed requests that were submitted using the kSTAFReqQueue or kSTAFReqQueueRetain options (see 6.1.5, "STAFSubmit2" for more information). This command also removes the request from the request list.

    Syntax

    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.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from FREE are documented in Appendix A, "API Return Codes".

    Results

    On successful return the result buffer will contain information in the following format

    <Return Code>:<Result>
    

    Return Code is the return code of the request.

    Result is the result buffer of the request.

    Examples

    Goal: Free request 16. Let's assume this which was a "VERSION" request to the MISC service.

    FREE REQUEST 16
    

    might result in the following

    0;2.1.0
    


    8.17 Shutdown Service

    8.17.1 Description

    The SHUTDOWN service is an internal STAF service. It provides the following commands.

    8.17.2 SHUTDOWN

    SHUTDOWN, as the name implies, shuts down the STAFProc program.

    Syntax

    SHUTDOWN
    

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SHUTDOWN are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a SHUTDOWN command.

    8.17.3 NOTIFY REGISTER/UNREGISTER

    NOTIFY REGISTER/UNREGISTER allow you to either register or unregister to receive a notification when the STAF Process is SHUTDOWN.

    Syntax

    NOTIFY <REGISTER | UNREGISTER> [MACHINE <Machine>]  [PRIORITY <Priority>]
           [HANDLE <Handle> | NAME <Name>]
    

    REGISTER indicates you want to register a shutdown notification. The content of the notification message will be STAF/SHUTDOWN.

    UNREGISTER indicates you want to unregister a shutdown notification

    MACHINE specifes the machine to which the notification should be sent. The default is the machine submitting the request. This option will resolve variables.

    PRIORITY specifies the priority of the notification message. The default is 5. This option will resolve variables.

    HANDLE specifies the handle to which the notification should be sent. The default is the handle of the process submitting the request. This option will resolve variables.

    NAME specifies the registered name of the process(es) to which the notification should be sent. This option will resolve variables.

    Security

    These commands require trust level 3.

    Return Codes

    All return codes from NOTIFY REGISTER/UNREGISTER are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a NOTIFY REGISTER/UNREGISTER command.

    Examples

    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
    

    8.17.4 NOTIFY LIST

    NOTIFY LIST allows you to view the shutdown notification list.

    Syntax

    NOTIFY LIST
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from NOTIFY LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain a list of all the registered notifiees. Each entry will either have the format <Priority>:<Machine>:NAME:<Name> or <Priority>:<Machine>:HANDLE:<Handle>, depending on whether the particular notifiee is to be notified by name or handle. For example,

    5:EventSrv1:NAME:ShutdownCatcher
    3:Client2:HANDLE:14
    

    Examples

    Goal: Retrieve the list of shutdown notifiees.

    NOTIFY LIST
    


    8.18 Trust Service

    8.18.1 Description

    The TRUST Service is one of the internal STAF services. It allows you to query and set the trust definitions for the machine. It provides the following commands.

    8.18.2 SET

    SET will set the default trust level or the trust level for a specific machine.

    Syntax

    SET <MACHINE <Machine> | DEFAULT> LEVEL <Level>
    

    MACHINE specifies that you want to set the trust level for the specified machine.

    DEFAULT specifies that you want to set the default trust level.

    LEVEL specifies the level of trust you wish to set.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a SET command.

    Examples

    Goal: Set the trust level for machine client1 to 3.

    SET MACHINE client1 LEVEL 3
    

    Goal: Set the default trust level to 1.

    SET DEFAULT LEVEL 1
    

    8.18.3 GET

    GET will return the effective trust level of a given machine. If the machine has an explicit trust definition then the effective trust level is the level specified in the trust definition. Otherwise, the effective trust level is the default trust level.

    Syntax

    GET MACHINE <Machine>
    

    MACHINE specifies the machine for which to return the effective trust level.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the effective trust level of the given machine.

    Examples

    For the following examples, assume the trust definitions for the machine are as follows

    Default: 2
     
    client1: 3
    client2: 0
    client3: 5
    

    Request: GET MACHINE client1

    Result: 3

    Request: GET MACHINE client2

    Result: 0

    Request: GET MACHINE client3

    Result: 5

    Request: GET MACHINE client4

    Result: 2

    8.18.4 LIST

    LIST will return the default trust level and a list of the explicit trust definitions.

    Syntax

    LIST
    

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the default level followed by a blank line followed by the list of explicit trust definitions. Each trust definition is of the format <Machine>: <Trust Level>. For example,
    Default: 2
     
    client1: 3
    client2: 0
    client3: 5
    

    Examples

    Goal: Retrieve the list of trust definitions.

    LIST
    

    8.18.5 DELETE

    DELETE will remove the explicit trust definition for the specified machine.

    Syntax

    DELETE MACHINE <Machine>
    

    MACHINE specifies the machine for which you wish to delete the specific trust definition.

    Security

    This command requires trust level 5.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples

    Goal: Delete the trust definition for machine client1.

    DELETE MACHINE client1
    


    8.19 Variable (VAR) Service

    8.19.1 Description

    The Variable Service, called VAR, is one of the internal STAF services. It allows you to manage the global and per-process variable pools. It provides the following commands.

    8.19.2 SET

    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.

    Syntax

    [GLOBAL | HANDLE <Handle>] SET <Name=Value> [SET <Name=Value>]...
    

    GLOBAL specifies that you want to set the value of the variable in the global variable pool.

    HANDLE indicates that you want to set the value of the variable in the variable pool associated with the specified handle.

    If neither GLOBAL nor HANDLE is specified, the variable will be set in the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be set in the global variable pool.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from SET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a SET command.

    Examples

    Goal: Set the global WebServer variable to testsrv1.test.austin.ibm.com.

    GLOBAL SET WebServer=testsrv1.test.austin.ibm.com
    

    Goal: In the process local variable pool, set variable "Good String" to "Command completed successfully", and set variable "Bad String" to "SYS3175"

    SET :42:Good String=Command completed successfully SET "Bad String=SYS3175"
    

    Goal: Set the variable STAF/Service/Log/Mask to "FATAL ERROR WARNING" in the variable pool associated with handle 37

    HANDLE 37 SET "STAF/Service/Log/Mask=FATAL ERROR WARNING"
    

    8.19.3 GET

    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.

    Syntax

    [GLOBAL | HANDLE <Handle>] GET <Name>
    

    GLOBAL specifies that you want to get the value of the variable from the global variable pool.

    HANDLE indicates that you want to get the value of the variable from the variable pool associated with the specified handle.

    If neither GLOBAL nor HANDLE is specified, the value of the variable will be retrieved from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be retrieved from the global variable pool.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from GET are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the value of the variable.

    Examples

    Goal: Get the value of the variable WebServer from the global variable pool

    GLOBAL GET WebServer
    

    Goal: Get the value of the variable "Good String" from the process local variable pool

    GET "Good String"
    

    Goal: Get the value of the variable ConfigData from the variable pool associated with handle 59

    HANDLE 59 GET ConfigData
    

    8.19.4 LIST

    LIST will return a list of all variables and their values.

    Syntax

    [GLOBAL | HANDLE <Handle> | ONLYHANDLE <Handle>] LIST
    

    GLOBAL specifies that you want the list of variables from the global variable pool only.

    HANDLE indicates that you want a combined list of variables from the global variable pool and the variable pool associated with the specified handle. If the same variable is set in both pools, the value from the specified handle's variable pool will be returned.

    ONLYHANDLE indicates that you want the list of variables from the variable pool associated with the specified handle only.

    If you do not specify GLOBAL or HANDLE or ONLYHANDLE, you will receive a combined list of variables from the global variable pool and the variable pool associated with the handle of the process that submitted the request, with the process-level variable's value being returned in the case where the variable exists in both pools, unless the request came from another machine, in which case only a list of the global variables will be returned.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from LIST are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain the list of variables formatted like this
    Bad String=SYS3175
    Good String=Command completed successfully
    STAF/Config/BootDrive=C:
    STAF/Config/EffectiveMachine=automate
    STAF/Config/Machine=automate.austin.ibm.com
    STAF/Config/Memory/Physical/Bytes=49938432
    STAF/Config/Memory/Physical/KB=48768
    STAF/Config/Memory/Physical/MB=47
    STAF/Config/OS/MajorVersion=20
    STAF/Config/OS/MinorVersion=40
    STAF/Config/OS/Name=OS2
    STAF/Config/OS/Revision=0
    STAF/Config/Sep/File=\
    STAF/Config/Sep/Line=
     
    STAF/Config/Sep/Path=;
    STAF/Config/STAFRoot=D:\STAF\BIN
    STAF/Service/Monitor/Directory={STAF/Config/BootDrive}\STAF\Monitor
    STAF/Service/Monitor/MaxRecordSize=256
    STAF/Service/Monitor/ResolveMessage=1
    STAF/Service/Monitor/Retry=3
    WebServer=testsrv1.test.austin.ibm.com
    

    Examples

    Goal: Retrieve the list of global variables

    GLOBAL LIST
    

    Goal: Retrieve the combined list of global and process local variables

    LIST
    

    Goal: Retrieve the combined list of global variables and variables associated with handle 62

    HANDLE 62 LIST
    

    Goal: Retrieve the list of variables associated with handle 48

    ONLYHANDLE 48 LIST
    

    8.19.5 RESOLVE

    RESOLVE allows you to have all variable references in a string resolved to their values. A variable reference is denoted by surrounding the variable in curly braces, for example, {WebServer}. Recursive and compound variable references are allowed (see the examples).

    Note that you may RESOLVE multiple strings with a single request.

    Because of this special significance of "{", if you do not want variable substitution performed, use a caret, "^", as an escape character for "{" and "^". However, a caret cannot be used as an escape character within a variable reference (see the examples).

    Syntax

    [GLOBAL | HANDLE <Handle>] RESOLVE <String> [RESOLVE <String>]... [DELIMIT <Delimiter>]
    

    GLOBAL specifies that only variables from the global variable pool should be used to resolve a variable reference.

    HANDLE indicates that variable references should try to be resolved from the variable pool assicatied with the specified handle first. If the variable is not found in this pool, the global variable pool should then be searched.

    If neither GLOBAL nor HANDLE is specified, variable references will try to be resolved from the variable pool associated with the handle of the process that submitted the request first, and then, if not found, from the global variable pool, unless the request came from another machine, in which case only the global variable pool will be used to resolve variable references.

    DELIMIT specifies the delimiter to use between results when resolving multiple strings. The default is the NULL character (0x00). This options is ignored if you are only resolving one string.

    Security

    This command requires trust level 2.

    Return Codes

    All return codes from RESOLVE are documented in Appendix A, "API Return Codes".

    Results

    If only one string is being resolved, the result buffer will contain the input string with all variable references resolved.

    If you are resolving mutliple strings the result buffer will contain a string in the following format

    <Return code 1>:<Result 1><Delimiter>[<Return code 2>:<Result 2><Delimiter>]...
    

    where <Return code N> is the return code from the N'th string to be resolved, and <Result N> is the result from resovling the N'th string.

    Examples

    For the following examples, assume the following variables are in the global variable pool

    12=Fun
    a=You
    b=Me
    c=1
    d=2
    e=a
    f={a}
    
    the following variables are in the process local variable pool
    a=Dogs
    b=Cats
    
    and the following variables are in the variable pool associated with handle 71
    a=Don
    b=Charles
    

    Request: GLOBAL RESOLVE {a}
    Result: You

    Request: GLOBAL RESOLVE "{a} and {b}"
    Result: You and Me

    Request: RESOLVE "{a} and {b} are {12}"
    Result: Dogs and Cats are Fun

    Request: RESOLVE {c}{d}
    Result: 12

    Request: RESOLVE {1{d}}
    Result: Fun

    Request: RESOLVE {{c}{d}}
    Result: Fun

    Request: RESOLVE {{e}}
    Result: Dogs

    Request: RESOLVE {f}
    Result: Dogs

    Request: RESOLVE {a} RESOLVE {b} RESOLVE {q} DELIMIT |
    Result: 0:Dogs|0:Cats|13:q|

    Request: HANDLE 71 RESOLVE "{f} and {b}"
    Result: Don and Charles

    The following examples show the use of a caret (^) as an escape character for "{" and "^". Assume the following variables are in the global variable pool for these examples:

    h=Hi
    Hi=HI
    ^Hi=Hello
    

    Request: GLOBAL RESOLVE "^{{h}, ^{{h}}, {{h}}, ^^{{h}}, and ^{^{h}}
    Result: {Hi, {Hi}, HI, ^HI, and {{h}}

    Request: GLOBAL RESOLVE "{^{h}}"
    Result: Hello

    Note that {^{h}} shows that a caret cannot be used as an escape character within a variable reference.

    8.19.6 DELETE

    DELETE will remove the given variable from the appropriate variable pool.

    Note that you may DELETE multiple variables with a single request.

    Syntax

    [GLOBAL | HANDLE <Handle>] DELETE <Name> [DELETE <Name>]...
    

    GLOBAL specifies that you want to delete the variable from the global variable pool.

    HANDLE indicates that you want to delete the variable from the variable pool associated with the specified handle.

    If neither GLOBAL nor HANDLE is specified, the variable will be deleted from the variable pool associated with the handle of the process that submitted the request unless the request came from another machine, in which case the variable will be deleted from the global variable pool.

    Security

    This command requires trust level 3.

    Return Codes

    All return codes from DELETE are documented in Appendix A, "API Return Codes".

    Results

    The result buffer will contain no data on return from a DELETE command.

    Examples

    Goal: Delete the variable WebServer from the global variable pool.

    GLOBAL DELETE WebServer
    

    Goal: Delete the variable "Bad String" from the process local variable pool.

    DELETE "Bad String"
    

    Goal: Delete the variable ConfigData from the variable pool associated with handle 59

    HANDLE 59 DELETE ConfigData
    


    8.20 Zip Service

    8.20.1 Description

    The Zip service is an external STAF service that provides the following functions:

    The purpose of the Zip service is to allow a test case to easily work with Zip archives.

    By using of Zlib compression library, the Zip service can create, extract, delete and manage PKZip, WinZip and Jar compatible archives.

    The Zip service supports the following features: create / extract PKZip, WinZip, and Jar compatible archives; save / restore owner, group and permission information on files and directories; delete file(s) from an Zip archive; list content of an Zip archive, append file / directory to an existing Zip archive, etc.

    The syntax and results for requests to the ZIP service are subject to change.

    8.20.2 Registration

    The Zip service is an external service and must be registered with the SERVICE configuration statement. The syntax is:
    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".

    Example

    service ZIP library STAFZip
    

    8.20.3 ZIP

    Zip a file or directory into a Zip archive. If the Zip archive does not exist, it will create it and add the file or directory to it. If the Zip archive already exists, it will add the file or directory to it.

    Syntax

    ZIP ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
        [RELATIVETO <Directory>]
    

    ZIPFILE contains the fully qualified ZIP archive name.

    ADD indicates you want to add files to the ZIP archive.

    FILE contains the fully qualified file name you want to zip into the ZIP archive.

    DIRECTORY contains the fully qualified directory name you want to zip info the ZIP archive.

    RELATIVETO contains the prefix to be excluded from the fully qualified file name or directory name that is to be zipped into the ZIP archive.

    RECURSE indicates that the all the files and subdirectories in the given directory will be zipped recursively.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", Zip also returns codes documented in 8.20.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a ZIP command.

    Examples

    Goal: Add file C:/file.txt to Zip archive D:/myzip.zip.
    Syntax: ZIP ADD ZIPFILE D:/myzip.zip FILE C:/file.txt
    Goal: Add directory /opt/mydir to Zip archive, relative to directory /opt.
    Syntax: ZIP ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RELATIVETO /opt
    Goal: Add directory /opt/mydir and all its subdirectories and files to Zip archive, relative to directory /opt.
    Syntax: ZIP ADD ZIPFILE /myzip.zip DIRECTORY /opt/mydir RECURSE RELATIVETO /opt

    8.20.4 UNZIP

    Extract files from a Zip archive to a specified directory.

    Syntax

    UNZIP  ZIPFILE <Name> TODIRECTORY <Name>
           [FILE <Name>]... [RESTOREPERMISSION] [REPLACE]
    

    ZIPFILE contains the fully qualified ZIP archive name.

    TODIRECTORY contains the fully qualified output directory name.

    FILE contains the fully qualified file name to be unzipped.

    RESTOREPERMISSION indicates that the owner, group and permission attributes of the file will be restored.

    REPLACE indicates that the file will be over written if it already exists in the specified directory.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", UNZIP also returns codes documented in 8.20.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a UNZIP command.

    Examples

    Goal: Unzip an archive myzip.zip to folder D:/mydata
    Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY D:/mydata/
    Goal: Unzip the file myjava/Hello.java from myzip.zip to folder /usr/lpp/mydata and restore permission, replace existing file if there is any:
    Syntax: UNZIP ZIPFILE /opt/myzip.zip TODIRECTORY /usr/lpp/mydata/ FILE myjava/Hello.java RESTOREPERMISSION REPLACE

    8.20.5 LIST

    List content of a ZIP archive.

    Syntax

    LIST ZIPFILE <Name>
    

    ZIPFILE contains the fully qualified ZIP archive name.

    Security

    This command requires trust level 3.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", LIST also returns codes documented in 8.20.7, "Zip Error Code Reference"

    Results

    On successful return, the result buffer will contain a listing of the contents of the Zip archive. The data will be formatted as follows with one line for every entry in the Zip archive.

    Examples

    Goal: Show me the content of a ZIP archive.
    Syntax: LIST ZIPFILE /opt/myzip.zip
    Results:
     
    Length    Method    Size    Ratio    Date    Time    CRC-32    Name
    ------    ------    ----    -----    ----    ----    ------    ----
    16118     Defl-X    4330     26%   12-12-03 13:20   9a1de6ee   myjava/Hello.java
    792874    Defl-X   261648    33%   12-12-03  14:46  7e2f5bc8   bin/run
     
    The Length column contains the uncompressed size of the file.
    The Method column contains the compression method "-" compression level 
    used to compress the file. For example "Defl-X", "Defl" stands for "Deflated", 
    "X" stands for "Maximum compression". Compression level can also contain the following
    values: "N" stands for "Normal compression", "F" stands for "Fast and Super fast 
    compression". Compression method can also contain the following values: "Stored" stands
    for "No compression", "Unkn." stands for "Unknow compression method".
    The Size column contains the compressed size of the file.
    The Ratio column contains the compression ratio of the file.
    The Date column contains the date stamp of the original file.
    The Time column contains the time stamp of the original file.
    The CRC-32 column contains the CRC-32 value of the file.
    The Name column contains the relative name of the file.
    

    8.20.6 DELETE

    Delete files from ZIP archive.

    Syntax

    DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
    

    ZIPFILE contains the fully qualified ZIP archive name.

    FILE contains the fully qualified file name to be deleted.

    CONFIRM confirms you really want to delete the file from zip archive.

    Security

    This command requires trust level 4.

    Return Codes

    In addition to the return codes documented in Appendix A, "API Return Codes", Delete also returns codes documented in 8.20.7, "Zip Error Code Reference".

    Results

    On a successful return, the result buffer will contain no data on return from a DELETE command.

    Examples 

    Goal: Delete file myjava/Hello.java from Zip archive D:/myzip.zip.
    Syntax: DELETE ZIPFILE D:/myzip.zip FILE myjava/Hello.java CONFIRM
    Goal: Delete file myjava/Hello.java and bin/run from Zip archive /opt/myzip.zip.
    Syntax: DELETE ZIPFILE /opt/myzip.zip FILE myjava/Hello.java FILE bin/run CONFIRM

    8.20.7 Zip Error Code Reference

    In addition to the common STAF return codes (see Appendix A, "API Return Codes" for additional information), the following Zip return codes are defined:

    Table 11. Zip Service Return Codes
    Error Code Meaning Comment
    4001 General zip error An general error occured, additional error message can be found in result buffer.
    4002 Not enough memory There is not enough memory in the system.
    4003 Change file size error: <file> Error changing the file size.
    4004 Error creating directory: <dir> Error creating directory in the file system.
    4005 Invalid zip file: <file> Invalid zip file format.
    4006 Bad CRC Bad CRC in the zip archive.
    4007 Invalid owner group Invalid owner / group on the system when restore permission.
    4008 Invalid file mode Invalid file mode.


    9.0 Generic Workload Processor

    The Generic Workload Processor, GenWL (pronounced Jen-Wall), allows you to define a workload based on a set of machines, processes, and variables, and then provides a means to start, stop, and query the workload.


    9.1 GenWL Syntax

    The syntax for the Generic Workload Processor is

    GenWL <Workload Definition File> -<Start[:<Actions>] | Stop | Query | Free>
          [-<Include | Exclude>:<MACHINE | PROCESS>:<List>]
          [-Quiet | -Verbose]
    

    The <Workload Definition File> defines the workload and is discussed in the next section. The default file extension is .gwl.

    -Start is used to start the workload. The processes are started asynchronously in the order that they are defined in the <Workload Definition File> You may optionally specify which actions will take place when you start a workload. These are specified in a comma separated list in place of <Actions> above. No spaces should be used between the commas and the actions. The following are the valid actions:

    -Stop is used to stop the workload.

    -Query is used to query the workload.

    -Free is used to free the termination information for the workload.

    -Include and -Exclude allow you to specify that a certain set of machines or processes should be included or excluded from processing. The list of machines or processes is separated by commas and may contain a trailing *, as a wildcard, on any value. No spaces should be used between the commas and the values. These lists are used in place of <List> above. -Includes are processed before -Excludes.

    -Quiet supresses all informational messages while processing

    -Verbose provides additional informational messages while processing

    Examples

    Note: GenWL is a REXX program. On non-OS/2 systems, you will need to preface the following examples with REXX.

    Goal: Start the workload defined in WebTests.gwl

    GenWL WebTests -Start
    

    Goal: Query the workload defined in Ogre.cfg

    GenWL Ogre.cfg -Query
    

    Goal: Set all global variables defined in MyTest.gwl on machines client1, client2, and client3.

    GenWL MyTest -Start:GlobalVar -Include:MACHINE:client1,client2,client3
    

    Goal: Query the workload defined in MyTest.gwl, but exclude machines whose names begin with bad.

    GenWL MyTest -Query -Exclude:MACHINE:bad*
    

    Goal: Stop the processes named Test1 and Test2 on machines client1 and client2 that are defined in workload MyTest.gwl

    GenWL MyTest -Stop -Include:MACHINE:client1,client2 -Include:PROCESS:Test1,Test2
    

    9.2 Workload Definition File

    The workload definition file defines the various machines, processes, and variables that will be used in the workload. The language used in these files consists of the following elements, which will be discussed below.

    Blank lines in the file are ignored.

    9.2.1 Comment

    A comment begins with a pound sign, #, and continues through to the end of the line.

    Examples

    WORKLOAD "Web Tests"      # Set the workload name
    

    9.2.2 Workload statement

    The WORKLOAD statement defines the name of the workload.

    Syntax

    WORKLOAD <Name>
    

    Examples

    WORKLOAD "Web Tests"
    WORKLOAD Ogre
    

    You must have a WORKLOAD statement in your workload definition file. If you have more than one, the last one takes precedence.

    9.2.3 Variable statement

    A variable statement allows you to specify a variable and its value. A variable statement inside of a process block is local to that particular process. A variable statement inside of a machine block, but outside of a process block, is global to that machine. A variable statement outside of a machine block is a workload variable, and is set as a global variable on all the machines defined in the workload definition file.

    Syntax

    VAR <Name=Value>
    

    Examples

    VAR WebServer=testsrv1.test.austin.ibm.com
    VAR "Good String=Command completed successfully"
    

    9.2.4 Machine block

    A machine block defines a machine you wish to use in the workload as well as any global variables on that machine and any processes to run on that machine.

    Syntax

    MACHINE <Name>
        [One or more variable statements]
        [One or more process blocks]
        [One or more process references]
    END
    

    Examples

    MACHINE Client1
     
        VAR LogDirectory=d:\logs
        VAR MonitorDirectory=d:\monitor
     
        PROCESS
            COMMAND d:\testcase\tc1.exe
        END
     
        PROCREF tc2
    END
    

    9.2.5 Process block

    A process block defines a process. If the process is defined within a machine block then the process is specific to that machine. If the process is defined outside of a machine block, then the process is global in nature and may be referenced by any machine block using a PROCREF statement (see 9.2.6, "Process reference").

    Syntax

    PROCESS
        [NAME <Name>]
        COMMAND <Command>
        [WORKDIR <WorkDir>]
        [TITLE <Title>]
        [ENV <Name=Value>]  [ENV <Name=Value>] ...
        [One or more variable statements]
    END
    

    NAME specifies the name of the process. This is used to refer back to the process via a PROCREF.

    COMMAND, PARMS, WORKDIR, TITLE, and ENV are defined as in 8.11, "Process Service".

    Examples

    PROCESS
        NAME WebTest1
        COMMAND cmd.exe
        PARMS "/c d:\\webtests\\webtest1.cmd"
        WORKDIR d:\webtests
        TITLE "Web Test 1"
        ENV USEHOSTS=1
        VAR WebServer=testsrv2.test.austin.ibm.com
    END
     
    PROCESS COMMAND d:\webtests\webtest2.exe END
    

    9.2.6 Process reference

    A process reference is a reference to a previously defined process. It is used inside a machine block to indicate that the previously defined process is to be executed by this machine.

    Examples

    PROCREF WebTest1
    PROCREF "Big bad stress test"
    

    9.3 Notes on querying a workload

    When you query a workload, you will see a section for each machine as defined in the workload definition file. In this section there will be one line of information per process defined on that machine. Each line contains the handle of the process, with the registered name of the process in parentheses. Following this information is either any available MONITOR data, if the process is still running, or completion information, if the process is no longer running.

    9.3.1 Examples

    Client1
    -------
    42(WebTest1) - 19980215-13:12:17 Starting loop 123
    43(WebTest2) - 19980215-13:10:39 ERROR: invalid internal html link
     
     
    Client2
    -------
    35(WebTest1) - Completed at 19980205-10:19:48, RC: 0
    43(WebTest3) - 19980215-13:11:26 Entering JavaScript verification phase
    

    You may also receive warning messages if there are a greater or lesser number of processes running under the context of the workload on a given machine than are defined in the workload definition file. For example, if Client1 is running three processes with the workload name "Web Tests", but only two are defined in the workload definition file, you will get a warning indicating that there is one more process running than defined.


    9.4 GenWL Example

    9.4.1 GenWL Input

    # This is a  generic workload definition file for use with test environment 08
    # It makes use of the sitloop command file to start test cases.
     
    Workload "ST08 Environment Tests"
     
    #
    # Define a workload variable
    #
     
    VAR WorkLoadID=ST08T5
     
    VAR Success_msg="Command completed successfully"
    VAR LogDirectory={STAF/Config/BootDrive}\ITLUTIL\STAFLog
    VAR MonitorDirectory={STAF/Config/BootDrive}\ITLUTIL\STAFMon
     
    #
    # Define some processes for later use
    #
     
    PROCESS
        NAME VACPP02
        TITLE VACPP02
        COMMAND cmd.exe
        PARMS "/c sitloop /lc=1 /lt=600 /tc=vacpp02 /cmd=vacpp02_staf.cmd c: c:"
    END
    PROCESS
        NAME VACPP03
        TITLE VACPP03
        COMMAND cmd.exe
        PARMS "/c sitloop /lc=1 /lt=600 /tc=vacpp03 /cmd=vacpp03_staf.cmd c: c:"
    END
     
    #--------
    # ST08S04
    #--------
    Machine cd1b
        PROCESS
            TITLE L123G_1
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=600 /tc=L123G_1 /cmd=sitl123g_staf.cmd /p=s04held"
        END
    End  # End of the machine block
     
    #--------
    # ST08R01
    #--------
    Machine cd1c
        PROCESS
            TITLE DB2_1
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=DB2_1 /cmd=sitdb2r_staf.cmd /c=1"
        END
        PROCESS
            TITLE EXER_CCC
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_ccc /cmd=exer_ccc_staf.cmd /S-ST08S04"
        END
        PROCESS
            TITLE INTEROPA
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=INTEROPA /staf /cmd=sitls01.cmd /alias=s05util"
        END
        PROCESS
            TITLE NW_1
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=20 /lt=600 /tc=NW_1 /cmd=itlnw211_staf.cmd"
        END
        PROCESS
            TITLE L123G_1
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=5 /lt=600 /tc=L123G_1 /cmd=sitl123g_staf.cmd /p=s04held"
        END
    End  # End of the machine block
     
    #--------
    # ST08R02
    #--------
    Machine cf2b
        PROCESS
            TITLE EXER_WEB
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_web /cmd=exer_web_staf.cmd /ID-WEB"
        END
        PROCESS
            TITLE INTEROPB
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=INTEROPB /staf /cmd=sitls01.cmd /alias=s01util"
        END
        PROCESS
            TITLE Notes_TestNSF
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=4 /lt=600 /tc=notes_testnsf /cmd=sittnsf_staf.cmd"
        END
        PROCESS
            TITLE BAPCO_3
            COMMAND cmd.exe
            PARMS "/c bapstart03_staf /lh=2"
        END
        PROCREF VACPP02
        PROCREF VACPP03
    End  # End of the machine block
     
    #--------
    # ST08R09
    #--------
    Machine cd3b
        PROCESS
            TITLE EXER_WEB
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=10 /lt=60 /tc=exer_web /cmd=exer_web_staf.cmd /WS-ST08R09 /h-cd1b /ms-600 /ID-WEB"
        END
        PROCESS
            TITLE ITLPing01
            COMMAND cmd.exe
            PARMS "/c sitloop /hours=2 /lc=20 /lt=60 /tc=itlping01 /cmd=itlping01_staf.cmd cf2c"
        END
    End  # End of the machine block
    

    9.4.2 GenWL Output

    cd1b
    ----
    5(nw_1) - 19980428-19:31:09 ST08T5---COMPLETED PASS: 18, SLEEP FOR 448SEC
     
    cd1c
    ----
    84(DB2_1) - Completed at 19980428-17:41:29, RC: 1
    85(exer_ccc) - 19980428-19:31:04 ST08T5---STARTING PASS: 27
    86(INTEROPA) - 19980428-19:31:00 SITLS01---PASS 19: COPY 8MB.DAT FROM REMOTE COMPLETE
    87(NW_1) - 19980428-19:27:37 ST08T5---COMPLETED PASS: 19, SLEEP FOR 446SEC
    88(L123G_1) - Completed at 19980428-18:55:39, RC: 1
     
    cf2b
    ----
    Warning: There were 6 more processes running on this machine than were
             defined in st08.gwl
    2(exer_web) - Completed at 19980417-18:07:08, RC: 0
    3(INTEROPB) - 19980417-14:36:32 SITLS01---PASS 1: COPY 8MB.DAT TO REMOTE COMPLETE
    4(notes_testnsf) - Completed at 19980417-15:14:25, RC: 1
    5(bapco_3) - Completed at 19980417-14:51:16, RC: 0
    6(vacpp02) - 19980417-14:28:44 ST08T5---STARTING PASS: 1
    7(vacpp03) - 19980417-14:28:44 ST08T5---STARTING PASS: 1
    10(exer_web) - 19980428-19:26:20 ST08T5---STARTING PASS: 14
    11(INTEROPB) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
    12(notes_testnsf) - 19980428-19:24:19 ST08T5---COMPLETED PASS: 3, SLEEP FOR 237SEC
    13(bapco_3) - 19980401-14:04:27 COMPLETED PASS: 1
    14(vacpp02) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
    15(vacpp03) - 19980428-17:35:17 ST08T5---STARTING PASS: 1
     
    cd3b
    ----
    6(exer_web) - 19980428-19:27:04 ST08T5---STARTING PASS: 11
    7(itlping01) - 19980428-19:30:44 ST08T5---COMPLETED PASS: 103, SLEEP FOR 53SEC
    


    10.0 Utilities

    Utilities are provided to assist in the usage and flexibility of STAF. For each utility the following sections are listed.


    10.1 Format Log Utility

    10.1.1 Description

    The FmtLog utility will read a log file and format and write the data to an output file in a readable format.

    10.1.2 FORMAT

    Format data from a log file to an output file in a readable (non-compressed) format. Note that this utility does not interact with STAF (i.e. STAF does not have to be running on the machine).

    Syntax

    FmtLog FORMAT LOGFILE <Logfile> NEWFILE <Newfile> [LEVELBITSTRING]  [FIELDSEP <Char>]
    

    LOGFILE contains the name of the log you want to read. This must be the complete path and filename.

    NEWFILE contains the name of the output file where you want to write the results. This must be the complete path and filename.

    LEVELBITSTRING displays the selected records with the level displayed as the 32 byte binary bit string, e.g. 00000000000000000000000000000001 instead of the standard level text e.g. Error. See 8.7.11, "Logging Levels Reference" for a complete list of logging levels.

    FIELDSEP is the character that separates each record field, the default is "|".

    Directory Structure

    If the log directory was defined as D:\STAF\LOGGING then the following is an example of how the log directory structure could look:
    D:\STAF\LOGGING\                               <-Global Top
    D:\STAF\LOGGING\GLOBAL\                        <--Global Dir
      STRESSTST.LOG                                <---Global Log
      SUITE100.LOG                                 <---Global Log
    D:\STAF\LOGGING\MACHINE\                       <-Machine Top
    D:\STAF\LOGGING\MACHINE\AQUADYNE\              <--AQUADYNE Top
    D:\STAF\LOGGING\MACHINE\AQUADYNE\GLOBAL\       <---AQUADYNE Global Top
      TESTLOG1.LOG                                 <----AQUADYNE Global Logs
    D:\STAF\LOGGING\MACHINE\AQUADYNE\HANDLE\       <--AQUADYNE Handle Top
    D:\STAF\LOGGING\MACHINE\AQUADYNE\HANDLE\100\   <---Handle 100 Top
      TESTLOG2.LOG                                 <---Handle 100 Log
    D:\STAF\LOGGING\MACHINE\AUTOMATE\              <--AUTOMATE Top
    D:\STAF\LOGGING\MACHINE\AUTOMATE\GLOBAL\       <---AUTOMATE Global Top
      AUTOGLOB.LOG                                 <----AUTOMATE Global Log
    D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\       <---AUTOMATE Handle Top
    D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\42\    <----Handle 42 Top
      HANDLOG1.log                                 <-----Handle 42 Log
    D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\43\    <----Handle 43 Top
      HANDLOG2.log                                 <-----Handle 43 Log
      HANDLOG3.log                                 <-----Handle 43 Log
    D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\44\    <----Handle 44 Top
      HANDLOG4.log                                 <-----Handle 44 Log
    D:\STAF\LOGGING\MACHINE\AUTOMATE\HANDLE\45\    <----Handle 45 Top
      HANDLOG5.log                                 <-----Handle 45 Log
    


    11.0 STAF V3.0 Migration Preparation

    In STAF 3.0, commands that return a "multi-valued" result will have a new result format and the syntax of some commands will be changed to follow the STAF standardization rules. To help current STAF 2.x customers prepare for migrating from STAF 2.x to 3.0, a new DIAG (Diagnostics) internal service is provided which allows for the recording of diagnostics data. The DIAG service is being used to track any invocation of a command that will be changing in STAF 3.0. The DIAG service will record the diagnostic trigger (in this case, the service/request that will be changing in STAF 3.0) along with the source of the trigger (the machine/handle/handle name that originated the request). By running with diagnostics enabled, users are able to identify which test cases, applications, and services they have written will need to be updated to work with STAF 3.0.

    11.0.1 Prerequisites

    You must install STAF V2.6.1 or later (but < V3.0.0) to take advantage of this migration aid. Note that STAF V2.6.4 contains the most up-to-date migration aid.

    In addition, the following external Java services have been instrumented to record STAF V3.0 migration diagnostics data. If you use any of the following external services, you should also install the new versions of these services:

    Note: The above versions of Java services require STAF 2.6.0 (or a later 2.x version).

    11.0.2 Enabling/Disabling Recording Diagnostics

    To record diagnostics for STAF-enabled test cases, applications, or services that you have written, you will need to enable diagnostics on the machines involved. To enable diagnostics, you can use the ENABLE request for the DIAG service. See 8.2.5, "ENABLE" for more information on using enabling diagnostics dynamically. Or, you can enable diagnostics automatically when STAF starts via the ENABLEDIAG operational setting in the STAF configuration file. See 4.6, "Operational parameters" for more information on using this operational setting. After you have completed running the STAF-enabled testcases, applications, and/or services, and diagnostics have been recorded, you can disable diagnostics on the machines involved. See 8.2.6, "DISABLE" for more information on disabling diagnostics.

    Notes:

    1. Enabling diagnostics slows down the performance of STAF commands that have been instrumented to record diagnostics, so only enable diagnostics if you're planning to use the diagnostics data and remember to disable diagnostics when you're done collecting the diagnostics data.

    2. When STAF shuts down, any diagnostics data that has been collected is no longer available. Diagnostics data is not persistent.

    3. You can clear the diagnostics data that has been collected using the RESET request for the DIAG service. See 8.2.4, "RESET" for more information on resetting diagnostics.

    11.0.3 STAF V3.0 Migration Diagnostic Triggers

    This section contains a list of the triggers for all STAF commands owned by the STAF Development team that will be changing in STAF 3.0 due to one or both of the following reasons:

    1. The result can "logically" return more than one value so the format of the result will be changing to allow for easier parsing of the result.

      Note that many results vary depending on the request options specified, with results for some requests sometimes containing multiple values and at other times only containing one value.

    2. The syntax of the STAF command is changing in STAF 3.0. For example, we're going to create a new TRACE service in STAF 3.0 and move the TRACE commands from the MISC service to a new TRACE service so the syntax for all TRACE commands will be changing. As another example, we're standardizing the syntax for requests in STAF 3.0. As a result of this, the syntax for all requests to the VAR service are changing.

    Trigger Syntax

    The format of the trigger recorded by STAF services to aid in migrating to STAF 3.0 is:

    STAF/V3.0-Mig/<Service> <Request>
    
    where:

    Source Syntax

    The format of the source recorded by STAF services to aid in migrating to STAF 3.0 is:

    <Handle Name>;<Machine Name>;<Handle#>
    
    where:


    Table 12. STAF V3.0 Migration Diagnostics Triggers
    Trigger Meaning
    STAF/V3.0-Mig/CRON LIST This indicates a LIST request to the CRON service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/EVENT LIST This indicates a LIST request to the EVENT service. The result and syntax for the request will change in STAF V3.0.

    The syntax changes include:

    • LIST REGCLIENTS -> LIST REGISTRATIONS
    • LIST EVENTIDS -> LIST EVENTIDS LONG
    • LIST TYPES -> LIST TYPES LONG
    • LIST TYPE -> LIST TYPES
    • LIST TYPE <Type> -> LIST SUBTYPES TYPE <Type>
    • LIST EVENTID <EventID> -> QUERY EVENTID <EventID> LONG
    • LIST EVENTIDS -> LIST EVENTIDS LONG
    STAF/V3.0-Mig/EVENT QUERY This indicates a QUERY request to the EVENT service. The result and syntax for the request will change in STAF V3.0.

    The syntax changes include:

    • QUERY TYPE <Type> -> LIST REGISTRATIONS LONG TYPE <Type>
    • QUERY LONG TYPE <Type> [SUBTYPE <Subtype>] -> LIST REGISTRATIONS LONG TYPE <Type> [SUBTYPE <SubType>]
    STAF/V3.0-Mig/EVENTMANAGER LIST This indicates a LIST request to the EVENTMANAGER service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FS COPY DIRECTORY (no IGNOREERRORS) This indicates a COPY DIRECTORY request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FS DELETE (no IGNOREERRORS) This indicates a DELETE request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FS GET ENTRY SIZE This indicates a GET ENTRY request to the FS service, with the SIZE option specified. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FS LIST This indicates a LIST request to the FS service. The result for the request will change in STAF V3.0. Also, changed the request syntax: the FORMAT option will change to the DETAILS option in STAF V3.0. Also, note that the default format when using the LONG option is different in STAF V3.0.
    STAF/V3.0-Mig/FS QUERY This indicates a QUERY request to the FS service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FSEXT COMPAREDIR (No EXISTS) This indicates a COMPARDIR request to the FSEXT service that does not specify the EXISTS option. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FSEXT FILECONTAINS NOT This indicates a FILECONTAINS request to the FSEXT service with the NOT option specified. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/FSEXT LINECONTAINS This indicates a LINECONTAINS request to the FSEXT service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HANDLE QUERY This indicates a QUERY request to the HANDLE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HELP ERROR This indicates a ERROR request to the HELP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HELP LIST This indicates a LIST request to the HELP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HTTP FOLLOW LINK This indicates a FOLLOW LINK request to the HTTP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HTTP LIST This indicates a LIST request to the HTTP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HTTP REQUEST|POST|DOGET This indicates a REQUEST, POST, or DOGET request to the HTTP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HTTP QUERY This indicates a QUERY request to the HTTP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/HTTP SUBMIT FORM This indicates a SUBMIT FORM request to the HTTP service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/LOG LIST This indicates a LIST request to the LOG service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/LOG PURGE This indicates a PURGE request to the LOG service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/LOG QUERY This indicates a QUERY request to the LOG service. The result for the request will change in STAF V3.0.

    In addition, there are some changes to the request syntax in STAF V3.0:

    • The FIELDSEP option has been removed since it is no longer needed with the way multi-valued results are handled in STAF V3.0.

    • There is now a DefaultMaximumQueryRecords parameter/setting in STAF V3.0 that is set by default to 100. You may need to add the ALL option to your QUERY request in STAF V3.x if you really want all of the records even if the number of records matching the query criteria exceeds the default maximum query records.
    STAF/V3.0-Mig/LOG SET This indicates a SET request to the LOG service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/MISC MACHINE This indicates a MACHINE request to the MISC service. This request does not exist in STAF V3.0 as it is no longer needed since there a USELONGNAMES operational setting no longer exists (e.g. the effective machine name and machine name are now the same).
    STAF/V3.0-Mig/MISC TRACE This indicates any TRACE request to the MISC service, other than a TRACE LIST request. The syntax for the request will change in STAF V3.0 due to moving the TRACE requests from the MISC service to a new TRACE service.
    STAF/V3.0-Mig/MISC TRACE LIST This indicates a LIST request to the MISC service. The result for the request will change in STAF V3.0, as well as the syntax.
    STAF/V3.0-Mig/MONITOR LIST This indicates a LIST request to the MONITOR service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/MONITOR QUERY This indicates a QUERY request to the MONITOR service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/MONITOR SET This indicates a SET request to the MONITOR service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/NAMEDCOUNTER LIST This indicates a LIST request to the NAMEDCOUNTER service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/PROCESS FREE ALL|WORKLOAD This indicates a FREE ALL or FREE WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/PROCESS NOTIFY LIST This indicates a NOTIFY LIST request to the PROCESS service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/PROCESS QUERY This indicates a QUERY request to the PROCESS service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/PROCESS START WAIT This indicates a START request to the PROCESS service with the option WAIT specified. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/PROCESS STOP ALL|WORKLOAD This indicates a STOP ALL or STOP WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/QUEUE GET|PEEK This indicates a GET or PEEK request to the QUEUE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/QUEUE LIST This indicates a LIST request to the QUEUE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/RESPOOL LIST This indicates a LIST request to the RESPOOL service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/RESPOOL QUERY This indicates a QUERY request to the RESPOOL service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM EVENT DELETE This indicates an EVENT DELETE request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM EVENT POST|PULSE This indicates an EVENT POST or PULSE request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM EVENT QUERY This indicates an EVENT QUERY request to the SEM service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM EVENT RESET This indicates an EVENT RESET request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM EVENT WAIT This indicates an EVENT WAIT request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM LIST This indicates a LIST request to the SEM service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM MUTEX DELETE This indicates a MUTEX DELETE request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM MUTEX QUERY This indicates a MUTEX QUERY request to the SEM service. The syntax and the result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM MUTEX RELEASE This indicates a MUTEX RELEASE request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SEM MUTEX REQUEST This indicates a MUTEX REQUEST request to the SEM service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SERVICE FREE This indicates a FREE request to the SERVICE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SERVICE LIST This indicates a LIST request to the SERVICE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SERVICE QUERY This indicates a QUERY request to the SERVICE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SHUTDOWN NOTIFY LIST This indicates a NOTIFY LIST request to the SHUTDOWN service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/STAX EXECUTE TEST RETURNDETAILS This indicates a TEST request to the STAX service specifying option RETURNDETAILS. The result for the request will change in STAF V3.0. Note that RETURNDETAILS is an undocumented option and is for use by STAF developers only.
    STAF/V3.0-Mig/STAX EXECUTE WAIT RETURNRESULT This indicates an EXECUTE request to the STAX service specifying options WAIT and RETURNRESULT. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/STAX LIST This indicates a LIST request to the STAX service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/STAX QUERY This indicates a QUERY request to the STAX service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/STAX SET This indicates a SET request to the STAX service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/SXE EXECUTE This indicates an EXECUTE request to the SXE service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/TIMER LIST This indicates a LIST request to the TIMER service. The syntax and result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/TRUST LIST This indicates a LIST request to the TRUST service. The result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/VAR DELETE This indicates a DELETE request to the VAR service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/VAR GET This indicates a GET request to the VAR service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/VAR LIST This indicates a LIST request to the TRUST service. The syntax and result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/VAR RESOLVE This indicates a RESOLVE request to the VAR service, specifying one RESOLVE option. The syntax for the request will change in STAF V3.0. Not only has the syntax been restructured, but the DELIMIT option for resolving multiple variables will be removed in STAF V3.0 as it is no longer needed due to the new format for multi-valued results.
    STAF/V3.0-Mig/VAR RESOLVE (Multiple) This indicates a RESOLVE request to the VAR service, specifying more than one RESOLVE option such that the result returns the resolved value for more than one STAF variable. The syntax and result for the request will change in STAF V3.0.
    STAF/V3.0-Mig/VAR SET This indicates a SET request to the VAR service. The syntax for the request will change in STAF V3.0.
    STAF/V3.0-Mig/ZIP LIST This indicates a LIST request to the ZIP service. The result for the request will change in STAF V3.0.

    Note: The above table is subject to change.

    11.0.4 Viewing STAF V3.0 Migration Diagnostics

    To view the diagnostics data that has been recorded, use the LIST request for the DIAG service. See 8.2.3, "LIST" for more information.

    Notes

    1. STAF-enabled applications provided by the STAF Development team may also record STAF V3.0 migration diagnostics data. For example, the STAX Monitor will record STAF V3.0 migration diagnostics data because it submits QUERY requests to the STAX service and GET/PEEK requests to the QUEUE service. Diagnostics data recorded by the STAX Monitor have a source that starts with STAX/JobMonitor/ or STAX/Job/. The STAF development team will be updating the STAX Monitor for STAF V3.0.

    2. If a STAF request that is changing in STAF V3.0 originates from the STAF executable, its source recorded in the diagnostics map will start with STAF/Client since that's the handle name for any STAF command submitted at the command line.

    11.0.5 New Format for Queued Messages

    Messages queued by STAF V3.x and it's services have a different format than in STAF V2.x. A new TYPE option was added in STAF V3.0 to identify the type of message being queued. STAF V3.x and it's services specify a type for all the message that they generate because queued messages can contain various marshalled data structures, such as a map, so the type let's you know the structure of the message.

    Here's a table showing the new format of the messages queued by STAF V3.0 and it's services, as well as showing the format of these messages queued by STAF V2.x clients to a STAF V3.0 machine.

    Table 13. STAF V3.0 Queued Messages
    Queued Messages from STAF V3.x Queued Messages from STAF V2.x
    TYPE: STAF/RequestComplete
    MESSAGE: A map containing the request completion information as follows:
    {
      requestNumber: <Request #>
      rc           : <Request return code>
      result       : <Request result buffer>
    }
    
    TYPE: <None>
    MESSAGE: A string containing request completion information as follows:

    STAF/RequestComplete <Request #>;<Request return code>;<Request result buffer>

    TYPE: STAF/Process/End
    MESSAGE: A map containing the process completion information as follows:
    {
      handle      : <Handle #>
      endTimestamp: <YYYMMDD-HH:MM:SS>
      rc          : <Process Return Code>
      key         : <Key> | <None>
      fileList    : [
        {
          rc  : <Returned File #1 RC>
          data: <Returned File #1 Data>
        }
      ]
    }
    
    TYPE: <None>
    MESSAGE: A string containing process completion information as follows:

    STAF/PROCESS/END <Handle>;<Timestamp>;<Return Code>[;<Returned file data>]

    TYPE: STAF/Start
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAF/START.
    TYPE: STAF/Shutdown
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAF/SHUTDOWN.
    TYPE: STAF/Service/Event
    MESSAGE: A map containing the event information as follows:
    {
      eventID         : <Event ID>
      eventServiceName: <Event Service Name>
      handle          : <Handle #>
      handleName      : <Handle Name>
      machine         : <Machine>
      propertyMap     : {
        <Name>: <Value>
        ...
      }
      subtype         : <Subtype>
      timestamp       : <YYYYDDMM-HH:MM:SS>
      type            : <Type>
    }
    
    TYPE: <None>
    MESSAGE: A string containing the event information as follows:

    STAF/SERVICE/<Event Service Name>/;<Event ID>;<Generating Machine>;<Generating Process>;<Generating Handle>;<TimeStamp>;<Type>;<Subtype>; [<Name>=<Value>;]...

    TYPE: STAF/Service/EventManager/End
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing EventManager/End.
    TYPE: STAF/Service/Cron/End
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing Cron/End.
    TYPE: STAF/Service/STAX/End
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAX/End.
    TYPE: STAF/Service/STAX/JobWaitComplete/<JobID>
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAX/Job/Wait/Complete/<JobID>.
    TYPE: STAF/STAXMonitor/End
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAXMonitorJob/End or STAXJobMonitor/End.
    TYPE: STAF/Service/Timer
    MESSAGE: A map containing the timer information as follows:
    {
      timerServiceName: <Timer Service Name>
      type            : <Timer Type>
      timestamp       : <YYYYDDMM-HH:MM:SS>
    }
    
    TYPE: <None>
    MESSAGE: A string containing the timer information as follows:

    STAF/SERVICE/<Timer Service Name>;<Type>;<Timestamp>;

    TYPE: STAF/Service/Timer/End
    MESSAGE: A string containing QUIT.
    TYPE: <None>
    MESSAGE: A string containing QUIT
    TYPE: STAF/STAFDemo/Stop
    MESSAGE: Blank
    TYPE: <None>
    MESSAGE: A string containing STAFDemo/End.


    Appendix A. API Return Codes

    Note: In some shell environments, return codes above 255 may be returned modulo 256. This can, in particular, cause service return codes (which range from 4000 upward) to be mistaken for (possibly) non-existant common STAF return codes. For example, if a service returned the return code 4010, this might appear to be the return code 170 (4010 modulo 256) in a shell environment.

    Table 14. STAF API Return Codes
    Error Code Meaning Comment
    0 No error
    1 Invalid API This indicates that a process has tried to call an invalid internal STAF API. If this error occurs, report it to the authors.
    2 Unknown Service You have tried to submit a request to a service that is unknown to STAFProc. Verify that you have correctly registered the service.
    3 Invalid Handle You are passing an invalid handle to a STAF API. Ensure that you are using the handle you received when you registered with STAF.
    4 Handle already exists This indicates that you are trying to register a process with one name when that process has already been registered with a different name. If you register the same process multiple times, ensure that you use the same name on each registration call.

    Note: If you receive this error code when trying to perform an operation other than registering a service, report it to the authors.

    5 Handle does not exist You are trying to perform an operation on a handle that does not exist. For example, you may be trying to stop a process, but you are specifying the wrong handle.
    6 Unknown Error An unknown error has occurred. This error is usually an indication of an internal STAF error. If this error occurs, report it the authors.
    7 Invalid Request String You have submitted an improperly formatted request to a service. See the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.

    Note: Additional information regarding the exact syntax error may be provided in the result passed back from the submit call.

    8 Invalid Service Result This indicates an internal error with the service to which a request was submitted. If this error occurs, report it to the authors and the service provider.
    9 Rexx Error This indicates an internal error in an external Rexx service. If this error occurs, report it to the authors and the service provider.

    Note: The actual Rexx error code will be returned in the result passed back from the submit call.

    10 Base OS Error This indicates that a base operating system error was encountered.

    Note: The actual base operating system error code will be returned in the result passed back from the submit call.

    11 Process Already Complete You are trying to perform an invalid operation on a process that has already completed. For example, you may be trying to stop the process or register for a process end notification.
    12 Process Not Complete You are trying to free process information for a process that is still executing.
    13 Variable Does Not Exist You are trying to get, remove, or resolve a variable that does not exist. Remember that variables are case sensitive. The name of the variable that does not exist will be in the result passed back from the submit call.
    14 UnResolvable String You have requested to resolve a string that cannot be resolved. This indicates that you have exceeded the resolution depth of the VAR service. The most common cause of this is recursive variables definitions.
    15 Invalid Resolve String The string you requested to be resolved has a non-matching left or right curly brace. Ensure that all variable references have both left and right curly braces.
    16 No Path To Machine This indicates that STAFProc was not able to submit the request to the requested machine. This error usually indicates that you have not configured any network interfaces, or that STAF is not running on the target machine. Alternatively, you may need to increase your CONNECTTIMEOUT value and/or increase your CONNECTATTEMPTS value in your STAF.cfg file
    17 File Open Error This indicates that there was an error opening the requested file. Some possible explanations are that the file/path does not exist, contains invalid characters, or is locked.

    Note: Additional information regarding which file could not be opened may be provided in the result passed back from the submit call.

    18 File Read Error This indicates that there was an error while trying to read data from a file.

    Note: Additional information regarding which file could not be read from may be provided in the result passed back from the submit call.

    19 File Write Error This indicates that there was an error while trying to write data to a file.

    Note: Additional information regarding which file could not be written to may be provided in the result passed back from the submit call.

    20 File Delete Error This indicates that there was an error while trying to delete a file or directory.

    Note: Additional information regarding which file or directory could not be deleted may be provided in the result passed back from the submit call.

    21 STAF Not Running This indicates that STAF is not running on the local machine. Verify that STAFProc.exe is running.
    22 Communication Error This indicates an error transmitting data across the network, or to the local STAF process. For example, you would receive this error if STAFProc.exe was terminated in the middle of a service request, or if a bridge went down in the middle of a remote service request.
    23 Trustee Does Not Exist You have requested to delete a trustee, and the trustee does not exist. Verify that you have specified the correct trustee.
    24 Invalid Trust Level You have attempted to set a machine or default trust level to an invalid level. The valid trust levels are from zero to five.
    25 Insufficient Trust Level You have submitted a request from a machine which does not have the required trust level to perform the request.
    26 STAF Registration Error This indicates that an external service encountered a problem when trying to register with STAF. Ensure that STAF has been properly installed and configured.
    27 Service Configuration Error This indicates an error with the configuration of an external service. If this error occurs, report it the authors.
    28 Queue Full This indicates that you are trying to queue a message to a handle's queue, but the queue is full. The maximum queue size can be increased by using the MAXQUEUESIZE statement in the STAF Configuration File.
    29 No Queue Element This indicates that you tried to GET or PEEK a particular element in a queue, but no such element exists, or the queue is empy.
    30 Notifiee Does Not Exist This indicates that you are trying to remove a message notification for a machine/process/priority combination which does not exist in the notification list.
    31 Invalid API Level This indicates that a process has tried to call an invalid level of an internal STAF API. If this error occurs, report it to the authors.
    32 Service Not Unregisterable This indicates that you are trying to unregister a service that is not unregisterable. Note that internal services are not unregisterable.
    33 Service Not Available This indicates that the service you requested is not currently able to accept requests. The service may be in the process of initializing or terminating.
    34 Semaphore Does Not Exist This indicates that you are trying to release, query, or delete a semaphore that does not exist.
    35 Not Semaphore Owner This indicates that you are trying to release a semaphore for which your process is not the current owner.
    36 Semaphore Has Pending Requests This indicates that you are trying to delete either a mutex semaphore that is currently owned or an event semaphore that has waiting processes.
    37 Timeout This indicates that you submitted a request with a timeout value and the request did not complete within the requested time.
    38 Java Error This indicates an error performing a Java native method call. A description of the error will be returned in the result passed back from the submit call.
    39 Converter Error This indicates an error performing a codepage conversion. The most likely cause of this error is that STAF was not properly installed. However, it is possible that you are currently using a codepage that was not present or specified during STAF installation.
    40 Service Already Exists This indicates that the specified Service already exists.

    Note: Additional information regarding the service which already exists may be provided in the result passed back from the submit call.

    41 Invalid Object This indicates that an invalid object was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
    42 Invalid Parm This indicates that an invalid parameter was specified to a STAF API. If you receive this return code via a standard STAFSubmit call, report it to the authors and the service provider.
    43 Request Number Not Found This indicates that the specified Request Number was not found. The specified Request Number may be invalid, or the request's information may no longer be available from the Service Service (for example, if the SERVICE FREE command had previously been issued for the request number).
    44 Invalid Asynch Option This indicates that an invalid Asynchronous submit option was specified.
    45 Request Not Complete This indicates that the specified request is not complete. This error code would be returned, for example, if you requested the result of a request which has not yet completed.
    46 Process Authentication Denied This indicates that the userid/password you specified could not be authenticated. The userid/password may not be valid or authentication may be disabled.
    47 Invalid Value This indicates that an invalid value was specified. This is closely related to the Invalid Request String return code, but indicates that a specific value in the request is invalid. For example, you may not have specified a number where a number was expected.

    Note: Additional information regarding which value is invalid may be provided in the result passed back from the submit call.

    48 Does Not Exist This indicates that the item you specified does not exist.

    Note: Additional information regarding which item could not be found may be provided in the result passed back from the submit call.

    49 Already Exists This indicates that the item you specified already exists.

    Note: Additional information regarding which item already exists may be provided in the result passed back from the submit call.

    50 Directory Not Empty This indicates that you have tried to delete a directory, but that directory is not empty.

    Note: Additional information specifying the directory which could not be deleted may be provided in the result passed back from the submit call.

    51 Directory Copy Error This indicates that you have tried to copy a directory, but errors occured during the copy.

    Note: Additional information specifying the entries which could not be copied may be provided in the result passed back from the submit call.

    52 Diagnostics Not Enabled This indicates that you tried to record diagnostics data, but diagnostics have not been enabled. You must enable diagnostics before you can record diagnostics data.
    4000+ Service Defined Error codes of 4000 and beyond are service specific error codes. Either see the appropriate section in this document for the syntax of the service's requests, or contact the provider of the service.


    Appendix B. Service Command Reference


    Table 15. STAF Service Command Reference
    Command Syntax
    DELAY Delay (or sleep) a number of milliseconds.

    DELAY <milliseconds>
    
    DIAG Allows diagnostics to be recorded, listed, enabled, disabled, and reset.

    RECORD TRIGGER <Trigger> SOURCE <Source>
     
    LIST   < [TRIGGER <Trigger> | SOURCE <Source> | TRIGGERS | SOURCES]
             [SORTBYCOUNT | SORTBYTRIGGER | SORTBYSOURCE] > |
           SETTINGS
           
    RESET  FORCE
     
    ENABLE
     
    DISABLE
     
    HELP
    
    ECHO Echo a return string from other STAF clients.

    ECHO <message>
    
    FS Allows you to manipulate files and directories.

    COPY   FILE <Name> [TOFILE <Name>] [TOMACHINE <Machine>]
           [TEXT [FORMAT <Format>]]
           [FAILIFEXISTS | FAILIFNEW]
     
    COPY   DIRECTORY <Name> [TODIRECTORY <Name>]  [TOMACHINE <Machine>]
           [NAME <Pattern>]  [EXT <Pattern>] [CASESENSITIVE | CASEINSENSITIVE]
           [TEXTEXT <Pattern>... [FORMAT <Format>]]
           [RECURSE [KEEPEMPTYDIRECTORIES | ONLYDIRECTORIES]]
           [IGNOREERRORS] [FAILIFEXISTS | FAILIFNEW]
     
    GET    FILE <Name> [[TEXT | BINARY] [FORMAT <Format>]]
     
    GET    ENTRY <Name> <TYPE | SIZE | MODTIME>
     
    QUERY  ENTRY <Name>
     
    CREATE DIRECTORY <Name> [FULLPATH] [FAILIFEXISTS]
     
    LIST   DIRECTORY <Name> [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
           [SORTBYNAME | SORTBYSIZE | SORTBYMODTIME]
           [CASESENSITIVE | CASEINSENSITIVE] [LONG [FORMAT]]
     
    DELETE ENTRY <Name> [CHILDREN [NAME <Pattern>] [EXT <Pattern>] [TYPE <Types>]
           [CASESENSITIVE | CASEINSENSITIVE]] [RECURSE] [IGNOREERRORS] CONFIRM
     
    HELP
    
    HANDLE Query information on various process handles and manage static handles.

    CREATE HANDLE NAME <Handle Name>
     
    DELETE HANDLE <Number>
     
    QUERY [ALL | NAME <Handle Name>] [PENDING] [REGISTERED] [INPROCESS] [STATIC]
     
    HELP
    
    HELP List and query STAF return codes. Allows services to register their own return codes.

    REGISTER   SERVICE <Name> ERROR <Number> INFO <String> DESCRIPTION <String>
     
    UNREGISTER SERVICE <Name> ERROR <Number>
     
    [SERVICE <Name>] ERROR <Number>
     
    LIST SERVICES | [SERVICE <Name>] ERRORS
     
    HELP
    
    LOG Allows for robust data-logging and log file querying and manipulation.

    LOG    <GLOBAL | MACHINE | HANDLE> LOGNAME <Logname> LEVEL <Level>
           MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    QUERY  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>] LOGNAME <Logname>
           [LEVELMASK <Mask>] [QMACHINE <Machine> [QHANDLE <Handle>]]
           [NAME <Name>] [FIRST <Num> | LAST <Num> | ALL] [TOTAL | STATS]
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [LEVELBITSTRING] [FIELDSEP <Char>]
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>]
     
    LIST   GLOBAL | MACHINES | MACHINE <Machine> [HANDLE <Handle> | HANDLES] |
           SETTINGS
     
    DELETE <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]>
            LOGNAME <Logname> CONFIRM
     
    PURGE  <GLOBAL | MACHINE <Machine> [HANDLE <Handle>]> LOGNAME <Logname>
           [LEVELMASK <Mask>] [QMACHINE <Machine>] [QHANDLE <Handle>]
           [NAME <Name>] [FIRST <Num> | LAST <Num>]
           [CONTAINS <String>]... [CSCONTAINS <String>]...
           [FROM <Timestamp> | AFTER <Timestamp>]
           [BEFORE <Timestamp> | TO <Timestamp>] CONFIRM
     
    SET    [MAXRECORDSIZE <Size>] [DEFAULTMAXQUERYRECORDS <Number>]
           [OLDRETURNCODES | NEWRETURNCODES]
           [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
           [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    VERSION
     
    HELP
    
    MISC Miscellaneous services such as VERSION, TRACE, and MACHINE information.

    VERSION
     
    MACHINE <Machine>
     
    TRACE <ON | OFF> [ServiceRequest] [ServiceResult] [ServiceError]
                     [ServiceAccessDenied] [ServiceManagement]
                     [Registration] [RemoteRequests]
                     [Error] [Warning] [Info] [All]
     
    TRACE [ALL] SERVICES [Service list]
     
    TRACE TO <STDOUT | STDERR | FILE <Filename> >
     
    TRACE LIST
     
    HELP
    
    MONITOR Allows test cases the ability to log and query status messages.

    LOG    MESSAGE <Message> [RESOLVEMESSAGE | NORESOLVEMESSAGE]
     
    QUERY  MACHINE <Machine> HANDLE <Handle>
     
    LIST   <MACHINES | [MACHINE <Machine>&.rbrk. | SETTINGS>
     
    DELETE [BEFORE <Timestamp>] CONFIRM
     
    SET    [RESOLVEMESSAGE | NORESOLVEMESSAGE]
           [OLDRETURNCODES | NEWRETURNCODES] [MAXRECORDSIZE <Size>]
           [ENABLERESOLVEMESSAGEVAR | DISABLERESOLVEMESSAGEVAR]
     
    VERSION
     
    HELP
    
    PING Allows you to ping other STAF clients.

    PING
    
    PROCESS Allows you to start, stop, and manage processes.

    START [SHELL [<Shell>]] COMMAND <Command> [PARMS <Parms>] [WORKDIR <Directory>]
          [VAR <Variable>=<Value>] [ENV <Variable>=<Value>] [USEPROCESSVARS]
          [WORKLOAD <Name>] [TITLE <Title>] [WAIT [Timeout] | ASYNC]
          [STOPUSING <Method>] [NEWCONSOLE | SAMECONSOLE]
          [USERNAME <User name> [PASSWORD <Password>]]
          [DISABLEDAUTHISERROR | IGNOREDISABLEDAUTH] [STATICHANDLENAME <Name>]
          [STDIN <File>] [STDOUT <File> | STDOUTAPPEND <File>]
          [STDERR <File> | STDERRAPPEND <File> | STDERRTOSTDOUT]
          [RETURNSTDOUT] [RETURNSTDERR] [RETURNFILE <File>]...
          [NOTIFY ONEND [HANDLE <Handle> | NAME <Name>] 
          [MACHINE <Machine>] [PRIORITY <Priority>] [KEY <Key>]]
     
    STOP  <ALL CONFIRM | WORKLOAD <Name> | HANDLE <Handle>> [USING <Method>]
     
    QUERY <ALL | WORKLOAD <Name> | HANDLE <Handle>>
     
    FREE  <ALL | WORKLOAD <Name> | HANDLE <Handle>>
     
    NOTIFY REGISTER   ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
                      [MACHINE <Machine>] [PRIORITY <Priority>]
     
    NOTIFY UNREGISTER ONENDOFHANDLE <Handle> [HANDLE <Handle> | NAME <Name>]
                      [MACHINE <Machine>] [PRIORITY <Priority>]
     
    HELP
    
    QUEUE Allows you to manipulate and manage queues.

    QUEUE  [HANDLE <Handle>] | [NAME <Name>] [PRIORITY <Priority>]
           MESSAGE <Message>
     
    GET    [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
           [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]...
           [WAIT [Timeout]]
     
    PEEK   [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
           [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]...
           [WAIT [Timeout]]
     
    DELETE [PRIORITY <Priority>]... [MACHINE <Machine>]... [NAME <Name>]...
           [HANDLE <Handle>]...     [CONTAINS <String>]... [ICONTAINS <String>]... 
     
    LIST   [HANDLE <Handle>]
     
    HELP
    
    RESPOOL Allows you to manage exclusive access to entries within resource pools.

    CREATE  POOL <PoolName> DESCRIPTION <Pooltext>
     
    DELETE  POOL <PoolName> CONFIRM [FORCE]
     
    QUERY   POOL <PoolName>
     
    REQUEST POOL <PoolName> [TIMEOUT <Timeout>] [FIRST | RANDOM]
     
    RELEASE POOL <PoolName> ENTRY <Value> [FORCE]
     
    ADD     POOL <PoolName> ENTRY <Value> [ENTRY <Value>]...
     
    REMOVE  POOL <PoolName> ENTRY <Value> [ENTRY <Value>]... CONFIRM [FORCE]
     
    LIST
     
    VERSION
     
    HELP
    
    SEM Allows you to manipulate and manage mutex and event semephores.

    MUTEX <Name> <REQUEST [Timeout] | RELEASE [FORCE] | DELETE | QUERY>
     
    EVENT <Name> <POST | RESET | PULSE | WAIT [Timeout] | DELETE | QUERY>
     
    LIST <MUTEX | EVENT>
     
    HELP
    
    SERVICE Allows you to manage STAF services and requests.

    LIST    [SERVICES | REQUESTS [PENDING] [COMPLETE]]
     
    QUERY   REQUEST <Request Number>
     
    FREE    REQUEST <Request Number> [FORCE]
     
    ADD     SERVICE <Service Name> LIBRARY <Library Name>
            [EXECUTE <Executable>] [OPTION <Name=[=Value]>]...
            [PARMS <Parameters>]
            
    REMOVE  SERVICE <Service Name>
          
    HELP
    
    SHUTDOWN Allows you to manage the STAFProc daemon process.

    SHUTDOWN
     
    NOTIFY REGISTER   [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
                      [PRIORITY <Priority>]
     
    NOTIFY UNREGISTER [MACHINE <Machine>] [HANDLE <Handle> | NAME <Name>]
                      [PRIORITY <Priority>]
     
    NOTIFY LIST
     
    HELP
    
    TRUST Allows you to manipulate and manage trust levels (security).

    SET <MACHINE <Machine> | DEFAULT> LEVEL <Level>
     
    GET MACHINE <Machine>
     
    DELETE MACHINE <Machine>
     
    LIST
     
    HELP
    
    VAR Allows you to manipulate and manage global and process specific variable pools.

    [GLOBAL | HANDLE <Handle>] SET <Name=Value> [SET <Name=Value>] ...
     
    [GLOBAL | HANDLE <Handle>] GET <Name>
     
    [GLOBAL | HANDLE <Handle>] DELETE <Name> [DELETE <Name>] ...
     
    [GLOBAL | HANDLE <Handle> | ONLYHANDLE <Handle>] LIST
     
    [GLOBAL | HANDLE <Handle>] RESOLVE <String> [RESOLVE <String>]..
     
    HELP
    
    ZIP Allows for zipping, unzipping, deleting entries in Zip archives which are PKZip, WinZip and Jar compatible.

    ZIP    ADD ZIPFILE <Name> < FILE <Name> | DIRECTORY <Name> [RECURSE] >
           [RELATIVETO <Directory>] 
     
    UNZIP  ZIPFILE <Name> TODIRECTORY <Name>
           [FILE <Name>]... [RESTOREPERMISSION] [REPLACE]
     
    LIST   ZIPFILE <Name>
     
    DELETE ZIPFILE <Name> FILE <Name> [FILE <Name>]... CONFIRM
     
    VERSION
     
    HELP
    


    Appendix C. Samples Descriptions


    Table 16. STAF Sample Code
    Name Description Comments
    D.1.1, "Java Sample 1" Java Ping Sample This sample uses the STAF Ping command to ping a STAF client and measure the throughput.
    D.2.1, "Rexx Sample 1" Rexx Synchronous Process Sample This sample loads the STAF Functions, registers to STAF, queries a global variable from STAF, inititates a synchronous process which is a chkdsk of the boot drive, then unregisters.
    D.2.2, "Rexx Sample 2" Rexx Asynchronous Process Sample This sample loads REXX and STAF Functions, registers to STAF, sets a global variable, inititates an asynchronous PMSEEK process, list variables, queries process status, stops PMSEEK, queries process status again, frees the process, queries the global variable previously set, then unregisters.
    D.2.3, "Rexx Sample 3" Rexx Monitor Sample This sample loads STAF Functions, registers to STAF, writes a monitor message and then queries it, this is done 10 times, then it unregisters. The size of the monitor messages written is based on a random number generated.
    D.2.4, "Rexx Sample 4" Rexx Log Sample This sample loads STAF Functions, registers to STAF, writes and queries 10 log messages to a global log called LOGTEST, then unregisters. The size of the log messages written is based on a random number generated.
    D.2.5, "Rexx Sample 5" Rexx Ping Sample This sample uses the STAF Ping command to ping a STAF client and measure the throughput.
    D.3.1, "C Sample 1" C Log Sample This sample logs a message via the STAF LOG service.
    D.4.1, "C++ Sample 1" C++ Log Sample This sample logs a message via the STAF LOG service.


    Appendix D. Code Samples and Snipets


    D.1 Java

    D.1.1 Java Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    //===========================================================================
    // JPing - A multi-threaded STAF PING test
    //===========================================================================
    // Accepts: Where to PING
    //          Optionally, the number of threads to use (default = 5)
    //          Optionally, the number of loops per thread (default = 10000)
    //          Optionally, the display modulus (default = 250)
    //
    // Returns: 0 , on success
    //          >0, if an error is encountered
    //===========================================================================
    // Date        Who           Comment
    // ----------  ------------  ------------------------------------------
    // 04/25/1998  C. Rankin     File Created
    //===========================================================================
     
    import com.ibm.staf.*;
    import java.util.Date;
    import java.util.Calendar;
    import java.text.DateFormat;
     
    public class JPing implements Runnable
    {
        // Constructor
     
        public JPing(int numLoops, int displayModulus, int myThreadNum)
        {
            loopCount = numLoops;
            modulus = displayModulus;
            threadNum = myThreadNum;
            errors = 0;
        }
     
        // This is the main command line entry point
     
        public static void main(String [] argv)
        {
            // Verify the command line arguments
     
            if ((argv.length < 1) || (argv.length > 4))
            {
                System.out.println();
                System.out.println("Usage: java JPing <Where> [# Threads] " +
                                   "[# Loops per thread] [Display Modulus]");
                System.out.println();
                System.out.println("Defaults:");
                System.out.println();
                System.out.println("  # Threads          = 5");
                System.out.println("  # Loops per thread = 10000");
                System.out.println("  Display Modulus    = 250");
                System.out.println();
                System.out.println("Examples:");
                System.out.println();
                System.out.println("java JPing local");
                System.out.println("java JPing SomeServer 3 1000 100");
                System.exit(1);
            }
     
            // Register with STAF
     
            try
            {
                handle = new STAFHandle("Java_Ping_Test");
            }
            catch (STAFException e)
            {
                System.out.println("Error registering with STAF, RC: " + e.rc);
                System.exit(1);
            }
     
            // Initialize variables
     
            timeFormatter = DateFormat.getTimeInstance(DateFormat.MEDIUM);
     
            where = argv[0];
            int numThreads = 5;
            int numLoops = 10000;
            int displayModulus = 250;
     
            if (argv.length > 1) numThreads = Integer.parseInt(argv[1]);
            if (argv.length > 2) numLoops = Integer.parseInt(argv[2]);
            if (argv.length > 3) displayModulus = Integer.parseInt(argv[3]);
     
            JPing [] pingers = new JPing[numThreads];
            Thread [] threads = new Thread[numThreads];
     
            System.out.println("(0)" + timeFormatter.format(new Date()) +
                               " - Started");
            long startSecs = (new Date()).getTime();
     
            // Start the threads
     
            for(int i = 0; i < numThreads; ++i)
            {
                pingers[i] = new JPing(numLoops, displayModulus, i + 1);
                threads[i] = new Thread(pingers[i]);
                threads[i].start();
            }
     
            // Wait for all the threads to finish
     
            for(int i = 0; i < numThreads; ++i)
            {
                try
                {
                    threads[i].join();
                }
                catch (Exception e)
                {
                    System.out.println("Exception: " + e);
                    System.out.println(e.getMessage());
                }
            }
     
            // Output final pings/sec
     
            long stopSecs = (new Date()).getTime();
            System.out.println("(0)" + timeFormatter.format(new Date()) +
                               " - Ended");
     
            System.out.println("Average: " + ((numLoops * numThreads * 1000) /
                               (stopSecs - startSecs)) + " pings/sec");
     
            // Unregister with STAF
     
            try
            {
                handle.unRegister();
            }
            catch (STAFException e)
            {
                System.out.println("Error unregistering with STAF, RC: " + e.rc);
                System.exit(1);
            }
        }
     
        // This is the method called when each thread starts
     
        public void run()
        {
            for(int i = 1; i <= loopCount; ++i)
            {
                STAFResult result = handle.submit2(where, "PING", "PING");
     
                // If we get a non-zero return code, or a response of something
                // other than "PONG", display an error
     
                if (result.rc != 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Loop #" + i + ", Error #" +
                                       ++errors + ", RC: " + result.rc);
                }
                else if (result.result.compareTo("PONG") != 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Loop #" + i + ", Error #" +
                                       ++errors + ", RESULT = " + result.result);
                }
     
                // If we are at our display modulus display a status message
     
                if ((i % modulus) == 0)
                {
                    System.out.println("(" + threadNum + ")" +
                                       timeFormatter.format(new Date()) +
                                       " - Ended Loop #" + i + ", Errors = " +
                                       errors);
                }
            }
        }
     
        private static STAFHandle handle;
        private static String where;
        private static DateFormat timeFormatter;
     
        private int loopCount;
        private int modulus;
        private int threadNum;
        private int errors;
    }
    

    D.2 Rexx

    D.2.1 Rexx Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample1.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample loads the STAF Functions, registers to STAF, queries  */
    /* a global variable from STAF, inititates a synchronous process     */
    /* which is a chkdsk of the boot drive, then unregisters.            */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 02/01/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register to STAF */
    call STAFRegister "STAF_REXX_Sample1"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/BootDrive}")
    if STAFRC = 0 then
      bootdrive = STAFResult
    else
    do
      say "Unable to determine boot drive!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    /* Build the process start request with a work load name of STAFSample */
    request = "START WAIT COMMAND chkdsk.com WORKLOAD STAFSample"
     
    /* Pass the boot drive parameter to chkdsk */
    parms = "PARMS" bootdrive
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/Sep/File}")
    if STAFRC = 0 then
      filesep = STAFResult
    else
    do
      say "Unable to determine file seperator!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    /* Set the working directory */
    workdir = "WORKDIR" bootdrive||filesep
     
    /* Submit the request to STAF */
    say "Attempting to CHKDSK bootdrive" bootdrive
    STAFRC = STAFSubmit("local", "process", request parms workdir)
    say "Submit Return Code="STAFRC ", Result="STAFResult
     
    /* Unregister */
    call STAFUnRegister
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister
      EXIT 1
    

    D.2.2 Rexx Sample 2

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample2.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample loads REXX and STAF Functions, registers to STAF,     */
    /* inititates an asynchronous PMSEEK process, queries, stops,        */
    /* queries again then frees the process, then unregisters.           */
    /*                                                                   */
    /* Note that this example explictly uses STAFHandle in all calls     */
    /* and additional error checking is needed.                          */
    /*                                                                   */
    /* Returns: 0,  on success                                           */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 02/02/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load system functions */
    call RxFuncAdd "SysLoadFuncs", "REXXUTIL", "SysLoadFuncs"
    call SysLoadFuncs
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register Sample to STAF */
    call STAFRegister "STAF_REXX_Sample2", "STAFHandle"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Set a global variable for start timestamp */
    request = " GLOBAL SET Start="||DATE('s')||'-'||TIME()
    STAFRC = STAFSubmit(STAFHandle, "local", "VAR", request)
     
    /* Build the process start request with a work load name of STAFSample2 */
    request = "START COMMAND pmseek.exe WORKLOAD STAFSample2"
     
    /* Submit the request to STAF */
    STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
    if STAFRC = 0 then
    do
      PROCHandle = STAFResult
      STAFRC = STAFSubmit(STAFHandle, "local", "VAR", "LIST")
      say STAFResult
      say "Press <Enter> to continue"
      pull response
     
      request = "query handle" PROCHandle
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
      say STAFResult
      say "Press <Enter> to stop PMSEEK"
      pull response
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "STOP HANDLE" PROCHandle)
      call SysSleep 1
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", request)
      say STAFResult
     
      STAFRC = STAFSubmit(STAFHandle, "local", "PROCESS", "FREE HANDLE" PROCHandle)
     
      STAFRC = STAFSubmit(STAFHandle, "local", "var", "resolve {Start}")
      if (STAFRC = 0) & (STAFResult \= '') then Start = STAFResult
     
      say "Start =" Start
      say "End   =" DATE('s')||'-'||TIME()
    end
     
    /* Unregister */
    call STAFUnRegister STAFHandle
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister STAFHandle
      EXIT 1
    

    D.2.3 Rexx Sample 3

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample3.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample writes a monitor message and then queries it, this    */
    /* is done 10 times.  A size of the string written is based on a     */
    /* random number generated.                                          */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 03/01/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register Sample to STAF */
    call STAFRegister "STAF_REXX_Sample3"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "resolve {STAF/Config/EffectiveMachine}")
    if STAFRC = 0 then machine = STAFResult
    else
    do
      say "Unable to determine effective machine name!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    service = "monitor"
    times = 10
    wait = 0
    string = "Software Testing Automation Framework (STAF) (C) Copyright IBM Corp.",
             "1998 All Rights Reserved"
     
    do times
      message = substr(string,1,1 + random(99))
      msglen = length(message)
      data = "LOG MESSAGE :"msglen":"message
      STAFRC = STAFSubmit("local", service, data)
      if STAFRC \= 0 then
        say "Monitor Log Error: " STAFRC STAFResult
     
      data = "query machine" machine "handle" STAFHandle
      STAFRC = STAFSubmit("local", service, data)
      if STAFRC = 0 then
        say STAFResult
      else
        say "Monitor Query Error: " STAFRC STAFResult
    end
     
    /* Unregister */
    call STAFUnRegister
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister
      EXIT 1
     
    

    D.2.4 Rexx Sample 4

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample4.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample writes 10 log messages to a global log file called    */
    /* LOGTEST and then queries them.  The size of the string written is */
    /* based on a random number generated.                               */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 03/02/1998  D. Randall    File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    /* Load STAF functions */
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    /* Register Sample to STAF */
    call STAFRegister "STAF_REXX_Sample4"
    if RESULT \= 0 then
    do
      say "Error registering to STAF:" RESULT
      RETURN RESULT
    end
     
    /* Query STAF for a variable */
    STAFRC = STAFSubmit("local", "var", "global resolve {STAF/Config/Machine}")
    if STAFRC = 0 then machine = STAFResult
    else
    do
      say "Unable to determine machine name!"
      call STAFUnRegister
      RETURN STAFRC
    end
     
    service = "LOG"
    times = 10
    count = 0
    level = error
    logtype = "log global logname "
    logname=LogTest
    string = "Software Testing Automation Framework (STAF) (C) Copyright IBM Corp.",
             "1998. All Rights Reserved"
     
    say  "Settings:" logtype logname "level" level "(times="  times ")"
    do count = 1 for times
      message = substr(string,1,1 + random(99))
      msglen = length(message)
      data = "LOG GLOBAL LOGNAME" logname "LEVEL" level "MESSAGE :"msglen":"message
      STAFRC = STAFSubmit("LOCAL", service, data)
      if STAFRC \= 0 then
        say "Log Error: " STAFRC STAFResult
      say count "of" times "Logged"
    end
     
    say "Querying last 10 log records..."
    data = "QUERY GLOBAL LOGNAME" logname "LAST 10"
    STAFRC = STAFSubmit("local", service, data)
    say STAFResult
     
    /* Unregister */
    call STAFUnRegister
    RETURN 0
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
      call STAFUnRegister
    EXIT 1
    

    D.2.5 Rexx Sample 5

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    /*********************************************************************/
    /* Sample5.cmd - Rexx sample program using STAF                      */
    /*********************************************************************/
    /* This sample uses the STAF Ping command to ping a STAF client and  */
    /* and measure the throughput.                                       */
    /*                                                                   */
    /* Accepts: [Machine] [LoopCount] [DisplayModulus]                   */
    /*                                                                   */
    /* Returns: 0, on success                                            */
    /*         >0, if an error is encountered                            */
    /*********************************************************************/
    /* Date        Who           Comment                                 */
    /* ----------  ------------  --------------------------------------- */
    /* 03/02/1998  C. Rankin     File Created                            */
    /*********************************************************************/
    SIGNAL ON HALT NAME STAFAbort
     
    parse arg Machine LoopCount DisplayModulus
     
    if (Machine = "?") | (Machine = "/?") | (Machine = "-?") then
    do
        say
        say "Usage: PingTest [Machine] [LoopCount] [DisplayModulus]"
        RETURN 1
    end
     
    if Machine = "" then Machine = "LOCAL"
    if LoopCount = "" then LoopCount = 999999999
    if DisplayModulus = "" then DisplayModulus = 1000
     
    call RxFuncAdd "STAFLoadFuncs", "RXSTAF", "STAFLoadFuncs"
    call STAFLoadFuncs
     
    call STAFRegister "STAF_PING_Test", "STAFHandle"
    if RESULT \= 0 then
    do
        say "Error registering with STAF, RC:" RESULT
        RETURN 1
    end
     
    say TIME() "- Started"
     
    startDate = DATE('B')
    startTime = TIME('S')
    errors = 0
     
    do i=1 to LoopCount
        call STAFSubmit STAFHandle, Machine, "PING", "PING"
     
        if RESULT \= 0 then
        do
            errors = errors + 1
            say TIME() "- Loop #"i", Error #"errors", RC:" RESULT
        end
        else if STAFResult \= "PONG" then
        do
            errors = errors + 1
            say TIME() "- Loop #"i", Error #"errors", STAFResult =" STAFResult
        end
     
        if i // DisplayModulus = 0 then
            say TIME() "- Ended Loop #"i", Errors =" errors
    end
     
    call AtEnd
     
    RETURN 0
     
     
    /*********************************************************************/
    /* AtEnd - Unregister from STAF and calculate final PING throughput. */
    /*********************************************************************/
    AtEnd:
     
        call STAFUnRegister STAFHandle
        say TIME() "- Ended"
     
        endTime = TIME('S')
        endDate = DATE('B')
     
        endSecs = ((endDate - 720000) * 86400) + endTime
        startSecs = ((startDate - 720000) * 86400) + startTime
     
        say "Average:" FORMAT((i / (endSecs - startSecs)), 3, 2) "pings/sec"
     
        RETURN 0
     
     
    /*********************************************************************/
    /* STAFAbort - If user aborts, make sure STAF unregister occurs.     */
    /*********************************************************************/
    STAFAbort:
     
        call AtEnd
        EXIT 1
    

    D.3 C

    D.3.1 C Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    #include <string.h>
    #include <stdio.h>
    #include "STAF.h"
     
    unsigned int logIt(char *type, char *name, char *level, char *message);
     
    // This could be a handy macro.
    // Just set gLogType and gLogName to the appropriate values.
    // Then you can use the macro as follows
    //    LOGIT("INFO", "This is some data I want to log");
     
    #define LOGIT(level, message) logIt(gLogType, gLogName, level, message)
     
    char *gLogType = "GLOBAL";
    char *gLogName = "MyLog";
     
    char *gRegName = "Logit";
    STAFHandle_t gHandle = 0;
     
    int main(int argc, char **argv)
    {
        unsigned int rc = 0;
     
        if (argc != 5)
        {
            printf("Usage: %s <Type> <Name> <Level> <Message>\n", argv[0]);
            return 1;
        }
     
        if ((rc = STAFRegister(gRegName, &gHandle)) != 0)
        {
            printf("Error registering with STAF, RC: %d\n", rc);
            return rc;
        }
     
        if ((rc = logIt(argv[1], argv[2], argv[3], argv[4])) != 0)
        {
            printf("Error logging data to STAF, RC: %d\n", rc);
            return rc;
        }
     
        if ((rc = STAFUnRegister(gHandle)) != 0)
        {
            printf("Error unregistering with STAF, RC: %d\n", rc);
            return rc;
        }
     
        return rc;
    }
     
    unsigned int logIt(char *type, char *name, char *level, char *message)
    {
        static char *where = "LOCAL";
        static char *service = "LOG";
        static char buffer[4000] = { 0 };
        char *resultPtr = 0;
        unsigned int resultLength = 0;
        unsigned int rc = 0;
     
        sprintf(buffer, "LOG %s LOGNAME %s LEVEL %s MESSAGE :%d:%s", type, name,
                level, strlen(message), message);
     
        rc = STAFSubmit(gHandle, where, service, buffer, strlen(buffer),
                        &resultPtr, &resultLength);
     
        STAFFree(gHandle, resultPtr);
     
        return rc;
    }
    

    D.4 C++

    D.4.1 C++ Sample 1

    /*****************************************************************************/
    /* Software Testing Automation Framework (STAF)                              */
    /* (C) Copyright IBM Corp. 2001                                              */
    /*                                                                           */
    /* This software is licensed under the Common Public License (CPL) V1.0.     */
    /*****************************************************************************/
     
    #include "STAF.h"
    #include "STAF_iostream.h"
    #include "STAFString.h"
     
    STAFResultPtr logIt(const STAFString &type, const STAFString &name,
                        const STAFString &level, const STAFString &message);
     
    // This could be a handy macro.
    // Just set gLogType and gLogName to the appropriate values.
    // Then you can use the macro as follows
    //    LOGIT("INFO", "This is some data I want to log");
     
    #define LOGIT(level, message) logIt(gLogType, gLogName, level, message)
     
    STAFString gLogType("GLOBAL");
    STAFString gLogName("MyLog");
    STAFString gRegName("Logit");
    STAFHandlePtr gHandle;
     
    int main(int argc, char **argv)
    {
        if (argc != 5)
        {
            cout << "Usage: LogIt <Type> <Name> <Level> <Message>" << endl;
            return 1;
        }
     
        unsigned int rc = STAFHandle::create(gRegName, gHandle);
     
        if (rc != 0)
        {
            cout << "Error registering with STAF, RC: " << rc << endl;
            return rc;
        }
     
        STAFResultPtr result = logIt(argv[1], argv[2], argv[3], argv[4]);
     
        if (result->rc != 0)
        {
            cout << "Error logging to STAF, RC: " << result->rc
                 << " RESULT: " << result->result << endl;
        }
     
        return result->rc;
    }
     
    STAFResultPtr logIt(const STAFString &type, const STAFString &name,
                        const STAFString &level, const STAFString &message)
    {
        static STAFString where("LOCAL");
        static STAFString service("LOG");
     
        STAFString request("LOG " + type + " LOGNAME " + name + " LEVEL " +
                           level + " MESSAGE " + STAFHandle::wrapData(message)); 
     
        return gHandle->submit(where, service, request);
    }
    

    Index

    A C D E F G H I J L M N O P Q R S T U V W Z
    A
  • API Reference (109)
  • C
  • C API
  • Other APIs (144)
  • STAFFree (139)
  • STAFRegister (113)
  • STAFRegisterUTF8 (120)
  • STAFSubmit (129)
  • STAFSubmit2UTF8 (137)
  • STAFSubmitUTF8 (135)
  • STAFUnRegister (124)
  • C code (597)
  • C++ classes
  • STAFHandle (148)
  • STAFResult (149)
  • C++ code (602)
  • codepage
  • concepts (19)
  • command reference (584)
  • commands
  • CSTAF (108)
  • FmtLog.cmd (575)
  • STAF (102)
  • STAF.cmd (105)
  • STAFProc (99)
  • configuration
  • example (90)
  • instructions (47)
  • Java Virtual Machine (62)
  • machine name (50)
  • network interfaces (52)
  • Operational parameters (70)
  • Service registration (58)
  • ServiceLoader registration (65)
  • start/shutdown notifications (82)
  • tracing (86)
  • trust (76)
  • tuning (94)
  • variables (72)
  • CSTAF command (106)
  • D
  • delay service (224)
  • diag service (230)
  • E
  • echo service (248)
  • error codes
  • help service (309)
  • Java class STAFResult (200)
  • log service (339)
  • monitor service (379)
  • Resource Pool service (462)
  • STAF (583)
  • zip service (560)
  • examples
  • C API
  • STAFFree (142)
  • STAFSubmit (132)
  • STAFUnRegister (127)
  • C code (601)
  • C++ Classes
  • STAFHandle (152)
  • C++ code (606)
  • C/C++ API
  • STAFRegister (116)
  • configuration file (92)
  • GenWL (567)
  • Java Classes
  • STAFHandle (196)
  • STAFLog (211)
  • STAFMonitor (216)
  • Java code (591)
  • Rexx API
  • STAFLog (179)
  • STAFMon (174)
  • STAFPool (184)
  • STAFRegister (159)
  • STAFSubmit (169)
  • STAFUnRegister (164)
  • STAFUtil (189)
  • Rexx code (596)
  • STAFSubmit2 (133)
  • trust (80)
  • F
  • file system service (254)
  • FmtLog.cmd command (573)
  • G
  • GenWL
  • example (569)
  • query output (571)
  • syntax (565)
  • H
  • handle service (281)
  • handles
  • concepts (4)
  • help service (293)
  • I
  • installation
  • Environment Variable Settings (43)
  • Installation Problems (45)
  • Registration (24)
  • Reinstallation (27)
  • Unix (33)
  • Windows (29)
  • J
  • Java classes
  • STAFException (198)
  • STAFHandle (193)
  • STAFLog wrapper (208)
  • STAFMonitor wrapper (213)
  • STAFQueueMessage (204)
  • STAFResult (202)
  • STAFUtil (206)
  • Java code (587)
  • L
  • log service (310)
  • logging levels (337)
  • M
  • machine name (48)
  • migration
  • misc service (340)
  • monitor service (356)
  • N
  • network interfaces (53)
  • O
  • Operational parameters (68)
  • overview (1)
  • P
  • parameters
  • log service (316)
  • Resource Pool service (436)
  • ping service (380)
  • port (55)
  • process
  • Changing User Rights Assignments (395)
  • Starting a process under a different username (393)
  • process service (386)
  • process termination notifications (405)
  • Q
  • queue service (412)
  • queues
  • concepts (17)
  • R
  • Registering (22)
  • registration
  • log service (314)
  • monitor service (360)
  • notify on shutdown (505)
  • Resource Pool service (434)
  • Service registration (60)
  • ServiceLoader registration (67)
  • STAFHandle C++ class (146)
  • STAFHandle Java class (191)
  • STAFRegister C API (111)
  • STAFRegister Rexx API (154)
  • STAFRegisterUTF8 C API (118)
  • STAFUnRegister C API (122)
  • zip service (546)
  • Reinstalling (25)
  • remote log service (463)
  • requirements (2)
  • Resource Pool service (430)
  • Rexx API
  • STAFLog wrapper (176)
  • STAFMon wrapper (171)
  • STAFPool wrapper (181)
  • STAFRegister (156)
  • STAFSubmit (166)
  • STAFUnRegister (161)
  • STAFUtil library (186)
  • Rexx code (592)
  • S
  • samples (586)
  • C code (599)
  • C++ code (604)
  • Java code (589)
  • Rexx code (594)
  • security (13)
  • semaphore service (466)
  • service command reference (585)
  • service commands
  • ADD
  • Resource Pool service (448)
  • service service (485)
  • COPY
  • file system service (259)
  • COPY DIRECTORY
  • file system service (262)
  • CREATE
  • file system service (277)
  • handle service (286)
  • Resource Pool service (442)
  • DELAY
  • delay service (229)
  • DELETE
  • file system service (280)
  • handle service (289)
  • log service (330)
  • monitor service (374)
  • queue service (426)
  • Resource Pool service (445)
  • trust service (523)
  • variable service (541)
  • zip service (558)
  • DISABLE
  • Diagnostics (DIAG) service (247)
  • ECHO
  • echo service (253)
  • ENABLE
  • Diagnostics (DIAG) service (244)
  • ERROR
  • help service (301)
  • EVENT
  • semaphore service (474)
  • FREE
  • process service (404)
  • service service (492)
  • GET
  • queue service (420)
  • trust service (517)
  • variable service (532)
  • GET ENTRY
  • file system service (268)
  • GET FILE
  • file system service (265)
  • LIST
  • Diagnostics (DIAG) service (238)
  • file system service (274)
  • help service (298)
  • log service (327)
  • monitor service (371)
  • queue service (429)
  • Resource Pool service (439)
  • semaphore service (477)
  • service service (482)
  • trust service (520)
  • variable service (535)
  • zip service (555)
  • LOG
  • log service (321)
  • monitor service (365)
  • MACHINE
  • misc service (345)
  • MUTEX
  • semaphore service (471)
  • NOTIFY LIST
  • process service (411)
  • shutdown service (508)
  • NOTIFY REGISTER/UNREGISTER
  • process service (408)
  • shutdown service (503)
  • PEEK
  • queue service (423)
  • PING
  • ping service (385)
  • PURGE
  • log service (333)
  • QUERY
  • file system service (271)
  • handle service (292)
  • log service (324)
  • monitor service (368)
  • process service (401)
  • Resource Pool service (454)
  • service service (490)
  • QUEUE
  • queue service (417)
  • RECORD
  • Diagnostics (DIAG) service (235)
  • REGISTER
  • help service (304)
  • RELEASE
  • Resource Pool service (460)
  • REMOVE
  • Resource Pool service (451)
  • service service (488)
  • REQUEST
  • request service (457)
  • RESET
  • Diagnostics (DIAG) service (241)
  • RESOLVE
  • variable service (538)
  • SET
  • log service (336)
  • monitor service (377)
  • trust service (514)
  • variable service (529)
  • SHUTDOWN
  • shutdown service (498)
  • START
  • process service (391)
  • STOP
  • process service (398)
  • TRACE
  • misc service (351)
  • UNREGISTER
  • help service (307)
  • UNZIP
  • zip service (552)
  • VERSION
  • misc service (348)
  • ZIP
  • zip service (549)
  • Service registration (56)
  • ServiceLoader registration (63)
  • services
  • delay service (226)
  • Diagnostics (DIAG) service (232)
  • echo service (250)
  • file system service (256)
  • general (218)
  • concepts (7)
  • description (219)
  • option value formats (221)
  • service help (223)
  • syntax (220)
  • variable resolution (222)
  • handle service (283)
  • help service (295)
  • log service (312)
  • misc service (342)
  • monitor service (358)
  • ping service (382)
  • process service (388)
  • queue service (414)
  • remote log service (465)
  • Resource Pool service (432)
  • semaphore service (468)
  • service service (479)
  • shutdown service (495)
  • trust service (511)
  • variable service (526)
  • zip service (544)
  • shutdown service (493)
  • STAF command (100)
  • STAF.cmd command (103)
  • STAFProc command (97)
  • start/shutdown notifications
  • configuration (84)
  • shutdown service (500)
  • strings
  • concepts (21)
  • T
  • TCP/IP (54)
  • tracing
  • configuration (88)
  • hexadecimal trace points (355)
  • misc service (353)
  • trust
  • configuration (78)
  • levels (15)
  • trust service (509)
  • tuning
  • configuration (96)
  • U
  • uninstalling
  • Unix (35)
  • Windows (31)
  • unixautostart
  • AS/400 (40)
  • HP-UX IA64 64-bit (39)
  • Linux (38)
  • Unix (37)
  • z/OS (41)
  • utilities
  • format log (577)
  • utility commands
  • FORMAT
  • format log utility (580)
  • V
  • variable service (524)
  • variables
  • concepts (11)
  • configuration (74)
  • log service (318)
  • monitor service (362)
  • predefined (12)
  • W
  • workload
  • concepts (9)
  • generic workload processor (563)
  • Z
  • zip service (542)

  • End Of Document

    This is the end of the document.