Frequently Asked Questions About STAF V3, STAX, and STAF Services


This is where you should look if you have a question about STAF V3, STAX V3, or an external STAF V3 service.

For questions about STAF V2, STAX V1, or an external STAF V2 service,. see the STAF V2 FAQ

1. General Information
1.1. What is STAF?
1.2. What operating systems are supported by STAF?
1.3. Where can I get STAF?
1.4. Is STAF Open Source?
1.5. What documentation exists for STAF V3?
1.6. How do I get on/off STAF mailing lists?
1.7. How do I get help?
1.8. How do I request a feature for STAF?
1.9. Why isn't STAF written in Java?
1.10. What is the performance overhead of running STAF?
1.11. How do I interact with STAF?
2. How-to Questions
2.1. Installation/Configuration
2.1.1. How do I install STAF?
2.1.2. How do I install STAF in silent mode?
2.1.3. How do I configure STAF?
2.1.4. How can I determine which version/architecture of STAF is installed?
2.2. Starting STAF
2.2.1. How do I load STAFEnv.sh automatically for each terminal window I open on Unix?
2.3. PROCESS Service
2.3.1. How do I redirect output from a process started by STAF?
2.3.2. How do I run a complex command that I can type at a shell (command) prompt via STAF?
2.3.3. How do I quote options that contain white space (e.g. pathnames containing spaces, etc.) via STAF?
2.3.4. How do I use a static handle to have multiple programs access variables and log data?
2.3.5. How do I change the system date/time to a prior date/time via a PROCESS START request?
2.4. LOG Service
2.4.1. How do I make each application have its own STAF log file?
2.4.2. How do I view a STAF log as it appears to be in some weird format?
2.5. HTTP Service
2.5.1. Does the HTTP Service retain session information across multiple requests?
2.6. STAX Service
2.6.1. How do I access system date and time in a STAX job?
2.6.2. How do I search for multiple strings in testcase output files in STAX?
2.6.3. How do I access STAF system variable values via a STAX job?
2.6.4. How do I use the <stopusing> element in a STAX job that runs on both Windows and Unix?
2.6.5. Does a STAX process element use the workdir element as the path to the command?
2.6.6. How do I use STAF and STAX to boot and shutdown VMWare images on my test machines?
2.6.7. How can I parse an XML file from a STAX job?
2.7. Globalization
2.7.1. How do I use STAF/STAX in environments where machines running STAF have different locales?
2.7.2. How do I specify non-ASCII characters in a STAF request or STAX job?
2.7.3. How do I know what codepage STAF is using on my machine?
3. Debugging STAF
3.1. General Questions
3.1.1. What should I do if I'm having a problem with STAF or one of its services?
3.1.2. What information should I include when asking questions or reporting bugs?
3.1.3. Explain RC 16 when attempting to send a STAF request to a remote machine
3.1.4. Why can't my STAF machines communicate?
3.1.5. Why aren't my entries in /etc/hosts being used for STAF communication (particularly on Linux SLES)?
3.1.6. Why can't I use the HELP service when STAF is not running?
3.1.7. Why are there are more STAF processes on Linux?
3.1.8. Why am I having problems (such as an RC 6) submitting a request to a Java service?
3.1.9. Why is STAFProc terminating on some Unix platforms (such as Solaris) when the STAFProc terminal is exited?
3.1.10. Why don't I see any Java service output in the STAFProc console anymore?
3.1.11. When using Sun Java 1.4.2, why are the -Xmx settings for my Java STAF service not being used?
3.1.12. Explain RC 21 when submitting a STAF service request
3.1.13. Explain "Error accepting on server socket,socket RC: 24"
3.1.14. Explain error using STAF Java libraries on Linux: libJSTAF.so: undefined symbol: _ZNSt8ios_base4InitD1Ev"
3.1.15. Why is the performance slow when sending a STAF PING request to a remote machine?
3.1.16. Why does a request to the LOG, MONITOR, RESPOOL, or ZIP service fail with RC 2 (Unknown service)?
3.2. STAF Install Questions
3.2.1. If the InstallAnywhere installer fails, how do I get debug information?
3.2.2. What if AIX STAF environment variables (PATH, LIBPATH, etc.) are not set when opening a terminal?
3.2.3. When running STAFInst on Solaris, why does it fail with "test: unknown operator -ef"?
3.2.4. Explain message "JAR Archive failed security check corrupt JAR file" when trying to download a STAF jar file
3.2.5. Why does the STAF InstallAnywhere install fail on RHEL5?
3.2.6. What entries do I need for STAF in my /etc/profile file if I am using the STAF tar.gz installation?
3.3. STAF Startup Questions
3.3.1. Explain startup error: Error constructing service, JSTAF
3.3.2. Explain startup error: Error binding server socket, bind() RC=98 (or 67)
3.3.3. Explain startup error: Error binding server socket, bind() RC=10048
3.3.4. Explain startup error: 38:Illegal access to class: com.ibm.staf.service....
3.3.5. Why does STAF's user registration fail each time STAFProc is started?
3.3.6. Explain startup error: Error initializing service, RESPOOL. RC: 4008
3.3.7. What should I do if STAF fails to init with Windows Terminal Server?
3.3.8. On SLES8, why do I get an error starting STAF: STAFProc: /usr/lib/libstdc++.so.5: version `GLIBCPP_3.2.2' not found (required by STAFProc)
3.3.9. Explain startup error on z/OS: Error binding server socket, bind() RC=1115
3.3.10. Explain startup error: RC: 27, Error initializing service, JSTAF when using a GNU compiler for Java provided with Linux
3.3.11. Explain HPUX error "sh: SHLIB_PATH: Parameter not set." when running /usr/local/staf/STAFEnv.sh, or when running it via sourcing .profile)
3.3.12. When logged into the desktop on RHEL4-U4, if I run "STAFProc" or "STAF", I get "error while loading shared libraries: libSTAF.so".
3.3.13. Explain AIX error "Symbol XX__Q2_3std8ios_base is not exported from dependent module /usr/lib/libC.a"
3.3.14. Explain HPUX IA64 error /usr/lib/hpux32/dld.so: Unsatisfied code symbol '__cxa_get_exception_ptr' in load module './STAFProc'.
3.3.15. On Windows x86_64), explain error OS RC 14001: This application has failed to start because the application configuration is incorrect..
3.3.16. Explain Linux error "STAFProc: relocation error: undefined symbol: _ZNSs4_Rep20_S_empty_rep_storageE" when starting STAFProc.
3.3.17. Explain Solaris Sparc 64-bit error when starting STAFProc: "/usr/sfw/lib/libstdc++.so.6: wrong ELF class: ELFCLASS32".
3.3.18. Explain startup error: Error creating interface. Could not determine logical/physical identifier.
3.4. PROCESS Service Questions
3.4.1. Explain RC 10 when attempting to run a process
3.4.2. Explain RC 25 when starting a process on a remote machine
3.4.3. Explain why I'm having a problem interacting with process queues for processes started via the command line
3.4.4. Why are child processes not killed on Windows?
3.4.5. Why can't a STAF process log its output to an AFS directory?
3.4.6. Why do I get a SIGABRT after a STAF process has completed on HP-UX?
3.4.7. Explain error message: "STAFProcessManager::processMonitorThread: Parent could not set child's pgid: 13"
3.4.8. Explain Unix error message: STAFProcessManager::processMonitorThread: Could not start process (execve): 8
3.4.9. When running the ftp executable for Windows via a PROCESS START request, why aren't I getting the remote server responses in stdout?
3.4.10. Why do Expect scripts fail on Linux when STAFProc has been started during system reboot?
3.4.11. Why is different output returned by some commands such as "reg query" when run using a win32 version of STAF on a Windows 64-bit system?
3.5. FS Service Questions
3.5.1. Why does COPY FILE request fail when no TOMACHINE is specified?
3.5.2. Why are my text files copied via the FS service not converted correctly between Windows and Unix?
3.5.3. Why can't I copy a file that is larger then 4GB?
3.5.4. Why does FS LIST COPYREQUESTS show a copy request in progress on the destination machine that has already failed with a RC 22?
4. Debugging STAX
4.1. General Questions
4.1.1. Where can I find more information about Python?
4.1.2. Why is STAX still showing a process as running, even though it has completed?
4.1.3. Why am I getting RC=10 and STAFResult=8 when starting a Java process in a STAX job?
4.1.4. Why does my eMail Service's SEND request resulting in RC 7 when quotes or double quotes are in the message?
4.1.5. Why am I getting a java.lang.NullPointerException at org.python.core.ThreadState.entrRepr in my JVMLog.1 file?
4.1.6. Why aren't changes to imported Python modules picked up in my STAX job?
4.1.7. Explain "RC 21 submitting a STAX EXECUTE request"
4.1.8. Why is the STAX JVM crashing with a java.lang.OutOfMemoryError logged in the STAX JVM log?
4.1.9. Why is the STAX JVM's maximum heap size limited to ~2G on a 32-bit system?
4.2. STAX <import> Questions
4.2.1. Why aren't the global <script> elements in the imported XML file executed when importing a STAX function from that file?
4.2.2. Are there any conflict or efficiency concerns when doing nested file imports in a STAX job?
4.3. STAX Monitor Questions
4.3.1. What does RC 2 mean when starting the STAX Job Monitor?
4.3.2. What does RC 16 mean when starting the STAX Job Monitor?
4.3.3. What does RC 2 mean when submitting a new job via the STAX Job Monitor?
4.3.4. What does RC 16 mean when submitting a new job via the STAX Job Monitor?
4.3.5. Why I'm I getting a java.util.zip.ZipException running "java -jar STAXMon.jar"?
4.3.6. Why doesn't the STAX Job Monitor window have a close confirmation?

1. General Information

1.1. What is STAF?
1.2. What operating systems are supported by STAF?
1.3. Where can I get STAF?
1.4. Is STAF Open Source?
1.5. What documentation exists for STAF V3?
1.6. How do I get on/off STAF mailing lists?
1.7. How do I get help?
1.8. How do I request a feature for STAF?
1.9. Why isn't STAF written in Java?
1.10. What is the performance overhead of running STAF?
1.11. How do I interact with STAF?
1.1.

What is STAF?

STAF stands for "Software Testing Automation Framework. As its name indicates, STAF is an automation framework. It is intended to make it easier to create and manage automated testcases and test environments.

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:

  • Minimum machine requirements - This is both a hardware and a software statement.
  • Easily useable from a variety of languages, such as Java, C/C++, Rexx, Perl, and Tcl, or from a shell (command) prompt.
  • Easily extendable - This means that it should be easy to create other services to plug into STAF.

1.2.

What operating systems are supported by STAF?

STAF 3.4.23+ is supported on the following operating systems:

  • Windows 2000
  • Windows XP
  • Windows Server 2003 (i386, x86_64)
  • Windows Vista (i386, x86_64)
  • Windows Server 2008 (i386, x86_64)
  • Windows 7 (i386, x86_64)
  • Windows Server 2008 R2 (x86_64)
  • Windows 8 (i386, x86_64)
  • Windows Server 2012 (x86_64)
  • Windows 8.1 (i386, x86_64)
  • Windows Server 2012 R2 (x86_64)
  • Windows 10 (i386, x86_64)
  • Linux (i386, x86_64, PPC64, PPC64LE)
  • Linux on zSeries (31-bit, 64-bit)
  • AIX 6.1 or higher (32-bit, 64-bit)
  • IBM i 7.1 and higher (32-bit, 64-bit), previously known as i5/OS or OS/400
  • z/OS UNIX V1.4 and higher (32-bit, 64-bit)
  • Mac OS X 10.10 and higher (Universal binary with support for i386 and x86_64)
  • Solaris (Sparc 32-bit) 10 and higher
  • Solaris (Sparc 64-bit) 10 and higher
  • Solaris (AMD Opteron 64-bit) 10 and higher
  • Solaris (x86) 10 and higher
  • HP-UX 11.11 and higher (PA-RISC) 32-bit and 64-bit
  • HP-UX 11.31 and higher (IA64) 32-bit and 64-bit
  • FreeBSD 7.4 and higher (i386)

If you need support for another operating system, open a feature request on the STAF SourceForge web site.

If you can't wait, port STAF to your favorite operating system yourself since STAF is open source.

1.3.

Where can I get STAF?

STAF software, information, documentation, etc. can be found at the STAF SourceForge web site.

1.4.

Is STAF Open Source?

Yes! STAF is open source. STAF Version 3.2.5 and later is licensed under the EPL (Eclipse Public License) V1.0.

STAF Versions 2.6.8 through 3.2.4 were licensed under the Common Public License (CPL) V1.0.

STAF Versions prior to 2.6.8 were licensed under the GNU Lesser General Public License (LGPL) V2.1.

1.5.

What documentation exists for STAF V3?

The following documents (and more) can be found at the STAF/STAX V3 Documentation web site:

1.6.

How do I get on/off STAF mailing lists?

Go to the STAF Mailing Lists web page and click on Subscribe or Unsubscribe for the STAF mailing list that you want to be added to or removed from.

1.7.

How do I get help?

You can submit questions using the STAF Mailing Lists and the STAF Discussion Forums on SourceForge.

If you are an IBMer, you may use the following IBM Forum to submit questions for STAF, STAX, and its services:

You can also get help about a STAF service's request syntax by using the following command:

STAF local service HELP

This will return the available options for the <service>

You can find out more information about STAF error codes by using the following command:

STAF local HELP ERROR 7

This will return detailed information about error code 7.

1.8.

How do I request a feature for STAF?

To request a feature (or browse a list of requested features), click here.

1.9.

Why isn't STAF written in Java?

  1. STAF is designed to put as few dependencies on the underlying system as possible. To that end we designed STAF to consume as little memory, disk, and CPU as possible. Some of these items (particularly disk space) aren't nearly as important as they were several years ago. However, almost every new group that picks up STAF asks this very same question, "How much <room> does STAF require?". Along these same lines, we didn't want to require any additional software on the system in order to run STAF. Writing STAF in Java would obviously require a JVM. Of the three resources previously listed, this has the largest impact on memory, and then CPU. Again, this isn't as large an issue as it once was, as many/most systems today have a JVM. Nevertheless, we have many groups who are reluctant to put a JVM on their system, particularly those doing base OS testing (like the AIX and Linux Technology Center) teams, and they definitely don't like being dependent on a JVM. For example, we have a group using STAF on Linux/PPC-64. This platform still doesn't have a stable JVM. And, the Linux JVMs, in general, have struggled for stability of the years (particularly on SMP systems). For what it's worth, we've had people tell us that STAF should have been built using MQ Series, or Java, or Perl, or <insert favorite technology>. Obviously, we can't appease all these groups, as they are mutually exclusive requests. In the end, STAF only depends on a base operating system, and a working compiler (for use in porting it).

    The following items all deal with the inability to write a 100% pure-Java implementation. If you can't go 100% (or darn close to it), a lot of Java's appeal dies away.

  2. STAF is designed to be extensible from a variety of languages. In order to invoke these other languages, you need the ability to call native code. Obviously, from Java, this puts you into JNI land and out of 100% pure-Java land. At the moment, STAF supports service written in C/C++, Java, and Rexx. Perl support is being actively developed in Hursley. Other languages are feasible, given a way to communicate with the language from C/C++. For example, we have prototyped Tcl and Python service support, but have not done full-blown implementations due to lack of user demand, although both languages are picking up steam (from their user communities). For what its worth, C/C++ and Java are the most common implementation languages for STAF services. Rexx was important early in STAF's life, but has effectively died off (from a service point of view), although there are a few groups that still use it do to Rexx having a long heritage (and deep roots) at IBM.

  3. Performance. Several of STAF's services (due to their nature) require as much performance as they can squeeze out (Log and Monitor are the primary examples here). This, effectively, means writing them in C/C++. In addition, the (local) IPC performance is important for the performance of STAF. To get the best performance here, you need to use native IPC communications instead of IP Sockets (when talking locally). Some operating systems (notably AIX, at least when we tested on the 4.3 release a couple of years ago), have horrible performance for local IP Sockets when compared with their native IPC mechanisms (e.g., Unix sockets, named/anonymous pipes, shared memory). Again, from a Java perspective, these things put you in JNI land. And, then, of course, there is your basic run-of-the-mill performance problems with Java. The JIT helps, but rarely comes anywhere near natively compiled code.

  4. Access to base OS features. The most important example here is starting processes (e.g., STAF's Process service). We allow you to specify alternate shells to use when starting processes, to start processes under different user IDs, to specify additional environment variables for the process, amongst other abilities. Java makes some of these things more difficult to implement (e.g., additional environment variables) and some nigh-impossible (e.g. different user IDs) without resorting to native code. And, yes, all these items are used by multiple STAF users/teams. Other items in this category are interacting with security systems and dealing with additional file system attributes (e.g., permission bits on unix systems, attributes on Win32 systems, ACLs on any system), both of which are planned for future versions of STAF.

1.10.

What is the performance overhead of running STAF?

As a general rule, STAF takes up very little system resources. A typical STAF installation is about 10-30 MB (depending on whether you use the installer with the integrated JVM). STAF's in-memory size (without any additional external services) is about 2.5-5 MB (depending on the platform). On an idle STAF system (i.e., one in which there are no requests currently being handled by STAF) STAF consumes 0% CPU on a Windows system and a VERY limited amount on unix systems. On unix, we have a thread which wakes up once a second to see if any STAF processes have completed. STAF was designed to consume as little system resources as possible, as we know that people want their test systems as close to clean-room conditions as possible.

1.11.

How do I interact with STAF?

You can interact with STAF from many languages (Java, C, C++, Python, Perl, Tcl, Rexx) and from the command line/shell prompt. See the "API Reference" and "Commands" sections in the STAF User's Guide for more information.

If you need support for another language, open a feature request on the STAF SourceForge web site.

If you can't wait, provide support for your favorite language yourself since STAF is open sourced.

2. How-to Questions

2.1. Installation/Configuration
2.1.1. How do I install STAF?
2.1.2. How do I install STAF in silent mode?
2.1.3. How do I configure STAF?
2.1.4. How can I determine which version/architecture of STAF is installed?
2.2. Starting STAF
2.2.1. How do I load STAFEnv.sh automatically for each terminal window I open on Unix?
2.3. PROCESS Service
2.3.1. How do I redirect output from a process started by STAF?
2.3.2. How do I run a complex command that I can type at a shell (command) prompt via STAF?
2.3.3. How do I quote options that contain white space (e.g. pathnames containing spaces, etc.) via STAF?
2.3.4. How do I use a static handle to have multiple programs access variables and log data?
2.3.5. How do I change the system date/time to a prior date/time via a PROCESS START request?
2.4. LOG Service
2.4.1. How do I make each application have its own STAF log file?
2.4.2. How do I view a STAF log as it appears to be in some weird format?
2.5. HTTP Service
2.5.1. Does the HTTP Service retain session information across multiple requests?
2.6. STAX Service
2.6.1. How do I access system date and time in a STAX job?
2.6.2. How do I search for multiple strings in testcase output files in STAX?
2.6.3. How do I access STAF system variable values via a STAX job?
2.6.4. How do I use the <stopusing> element in a STAX job that runs on both Windows and Unix?
2.6.5. Does a STAX process element use the workdir element as the path to the command?
2.6.6. How do I use STAF and STAX to boot and shutdown VMWare images on my test machines?
2.6.7. How can I parse an XML file from a STAX job?
2.7. Globalization
2.7.1. How do I use STAF/STAX in environments where machines running STAF have different locales?
2.7.2. How do I specify non-ASCII characters in a STAF request or STAX job?
2.7.3. How do I know what codepage STAF is using on my machine?

2.1. Installation/Configuration

2.1.1. How do I install STAF?
2.1.2. How do I install STAF in silent mode?
2.1.3. How do I configure STAF?
2.1.4. How can I determine which version/architecture of STAF is installed?
2.1.1.

How do I install STAF?

STAF provides its own installation program which uses InstallAnywhere for supported platforms. On Unix platforms, we also provide a shell script-based installation mechanism. See the STAF Installation Guide for detailed instructions on how to install STAF.

2.1.2.

How do I install STAF in silent mode?

Here are the commands to install STAF in silent mode (these examples are for Win32):

If using the InstallAnywhere executable:

C:\temp>STAF330-setup-win32 -i silent -DACCEPT_LICENSE=1

To override the default location where STAF is installed during a silent installation, you can specify the following option:

C:\temp>STAF330-setup-win32 -i silent -DACCEPT_LICENSE=1 -DUSER_INSTALL_DIR=C:\tools\staf

2.1.3.

How do I configure STAF?

STAF is configured through a text file called the STAF Configuration File. This file may have any name you desire, but the default is STAF.cfg. The STAF configuration File is read and processed line by line. The various configuration options are described in the Configuration section in the STAF User's Guide.

2.1.4.

How can I determine which version/architecture of STAF is installed?

After the STAF install is complete, an install.properties file will be created in the root STAF install directory. The file will contain key/value pairs that provide information about the version of STAF that has been installed.

The install.properties file will contain the following information:

  • version - the version of STAF that has been installed
  • platform - the STAF platform name
  • architecture - the architecture of the STAF build (32-bit or 64-bit)
  • installer - the type of installer (InstallAnywhere, STAFInst)
  • file - the file used to install STAF
  • osname - the operating system name for the STAF build (equivalent to the "os.name" Java property)
  • osversion - the operating system version supported by the STAF build ("*" indicates the build is supported on any version of the OS; a version number followed by a "+" indicates the build supports that version or later)
  • osarch - the operating system architecture supported by the STAF build (equivalent to the "os.arch" Java property)

Here is a sample install.properties file from a Windows system (using the IA installer):

version=3.4.23
platform=win32
architecture=32-bit
installer=IA
file=STAF3423-setup-win32.exe
osname=Windows
osversion=*
osarch=x86

Here is a sample install.properties file from a Mac OS X Universal system (using the STAFInst installer):

version=3.4.23
platform=macosx-universal
architecture=32-bit/64-bit
installer=STAFInst
file=STAF3423--macosx-universal.tar
osname=Mac OS X
osversion=10.10+
osarch=universal (i386, x86_64)

2.2. Starting STAF

2.2.1. How do I load STAFEnv.sh automatically for each terminal window I open on Unix?
2.2.1.

How do I load STAFEnv.sh automatically for each terminal window I open on Unix?

Note: Be aware of all the leading dots ('.') and dot spaces (". ") in the following steps. They are crucial and are functionally distinct.

  1. Edit your .profile. If a file called /.profile (in linux it's /root/.profile) does not exist, just create it.

    prompt> vi /.profile
    

    Add the following line to your .profile:

     . /usr/local/staf/STAFEnv.sh
    

    and save the file.

  2. Run your .profile:

    prompt> .  /.profile
    

    Now when you create a terminal or log in, the STAFEnv variables will be loaded.

2.3. PROCESS Service

2.3.1. How do I redirect output from a process started by STAF?
2.3.2. How do I run a complex command that I can type at a shell (command) prompt via STAF?
2.3.3. How do I quote options that contain white space (e.g. pathnames containing spaces, etc.) via STAF?
2.3.4. How do I use a static handle to have multiple programs access variables and log data?
2.3.5. How do I change the system date/time to a prior date/time via a PROCESS START request?
2.3.1.

How do I redirect output from a process started by STAF?

You can't use the command line redirection symbols, such as '>', with STAF. They won't work. However, STAF's PROCESS service provides several redirection options, namely STDIN, STDOUT, STDOUTAPPEND, STDERR, and STDERRAPPEND, depending on what (and how) you want to redirect.

For example, to start shell script tc3.sh and redirect its standard output to /tmp/tc3.out:

STAF local PROCESS START COMMAND tc3.sh STDOUT /tmp/tc3.out

2.3.2.

How do I run a complex command that I can type at a shell (command) prompt via STAF?

The PROCESS service has a SHELL parameter which specifies that COMMAND should be executed as though you were at a shell prompt. This 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.

Unix Command Line Example:

STAF local PROCESS START SHELL COMMAND "ps | grep test | wc >testcount.txt"

Windows Command Line Example:

STAF local PROCESS START SHELL COMMAND "dir *.*"

2.3.3.

How do I quote options that contain white space (e.g. pathnames containing spaces, etc.) via STAF?

You must specify quotes around pathnames that contain white space and you need to specify double quotes around the entire option value. To have double quotes contained within double quotes, you need to escape them with a backslash, e.g. \". Here are some examples of how to quote options that contain white space in PROCESS START requests:

  1. Say you wanted to run the following command using a STAF PROCESS START request via a Windows command prompt:

    copy "C:\Program Files\file1.txt" "C:\Program Files\file2.txt"

    Using the STAF PROCESS START request, you must specify quotes around the filenames and you need to specify double quotes around the entire COMMAND option value. To have double quotes contained within double quotes, you need to escape them with a backslash (e.g. \"). And, you'll want to use the SHELL option. So, for example:

    C:\>STAF local PROCESS START SHELL COMMAND "copy \"C:\Program Files\file1.txt\" \"C:\Program Files\file2.txt\"" WAIT RETURNSTDOUT STDERRTOSTDOUT 
    Response 
    -------- 
    { 
      Return Code: 0 
      Key        : <None> 
      Files      : [ 
        { 
          Return Code: 0 
          Data       :         1 file(s) copied. 
    
        } 
      ] 
    }
    

    Note that when executing a STAF command from a program (e.g. from a Java program), you can use the STAFUtil.wrapData() function provided to wrap option value. See the STAF Java User's Guide for more information if your submitting STAF commands via a Java program instead of from the command line.

    Note that instead of copying a file this way, you should use the STAF FS (File System) service instead (which works on all operating systems and allows you to copy files to other machines, not just to the same machine, if desired). For example:

    C:\>STAF local FS COPY FILE "C:\Program Files\file1.txt" TOFILE "C:\Program Files\file2.txt" 
    Response 
    -------- 
    
    

    See the STAF User's Guide for more information on the FS service and the COPY FILE and COPY DIRECTORY requests.

  2. Say you wanted to run the following command using a STAF PROCESS START request via a Windows command prompt:

    dir "C:\Program Files"

    To run this command using a STAF PROCESS START request via a Windows command prompt:

    C:\>STAF local PROCESS START SHELL COMMAND "dir \"C:\Program Files\"" WAIT RETURNSTDOUT STDERRTOSTDOUT 
    Response 
    -------- 
    { 
      Return Code: 0 
      Key        : <None> 
      Files      : [ 
        { 
          Return Code: 0 
          Data       :  Volume in drive C has no label. 
     Volume Serial Number is B0B7-F95A 
    
     Directory of C:\Program Files 
    
    02/17/2003  09:52a      <DIR>          . 
    02/17/2003  09:52a      <DIR>          .. 
    02/17/2003  09:52a      <DIR>          Common Files 
    02/17/2003  09:58a      <DIR>          Windows NT 
    ...
                   1 File(s)        185,037 bytes 
                  51 Dir(s)  25,483,706,368 bytes free 
    
        } 
      ] 
    } 
    

    However, it makes more sense to use the STAF FS service's LIST DIRECTORY request. For example:

    C:\>STAF local FS LIST DIRECTORY "C:\Program Files" 
    Response 
    -------- 
    Common Files 
    Windows NT 
    ... 
    
    or
    C:\>STAF local FS LIST DIRECTORY "C:\Program Files" LONG 
    Response 
    -------- 
    Type Size  Modified Date-Time Name 
    ---- ----- ------------------ -------------------------------------- 
    D    0     20030217-09:52:38  Common Files 
    D    0     20030217-09:58:02  Windows NT
    ... 
    

    See the STAF User's Guide for more information on the FS service and the LIST DIRECTORY request and all of it's options.

  3. Say you wanted to run the following command:

    more "C:\Program Files\file1.txt"

    Using the STAF PROCESS START command to run this command, you must use the SAMECONSOLE option if you don't redirect all 3 streams (STDID, STDOUT, STDERR) if the command you're running accesses STDIN. There's a note about this in the STAF User's Guide in the section about the PROCESS START command.

    C:\>STAF local PROCESS START SHELL COMMAND "more \"C:\Program Files\file1.txt\"" WAIT RETURNSTDOUT STDERRTOSTDOUT SAMECONSOLE 
    Response 
    -------- 
    { 
      Return Code: 0 
      Key        : <None> 
      Files      : [ 
        { 
          Return Code: 0 
          Data       : This is line 1. 
    This is line 2. 
    
        } 
      ] 
    } 
    

    Also, note that if you have a lot of data in the file, using the command "more" specifies to prompt you whether you want to display more data. So, you would have to provide a STDIN file using the STDIN option containing the appropriate responses. In an automated environment, it doesn't make much sense to use the Windows more command. Instead, you should use the STAF FS GET FILE command to get the contents of a text file. For example:

    C:\>STAF local FS GET FILE "C:\Program Files\file1.txt" 
    Response 
    -------- 
    This is line 1. 
    This is line 2. 
    
  4. Say you wanted to run the following command:

    echo this is the string to be parsed > "C:\Program Files\echofile.txt"

    To run it via a PROCESS START command:

    C:\>STAF local PROCESS START SHELL COMMAND "echo this is the string to be parsed > \"C:\Program Filesr\echofile.txt\"" WAIT RETURNSTDOUT STDERRTOSTDOUT 
    Response 
    -------- 
    { 
      Return Code: 0 
      Key        : <None> 
      Files      : [ 
        { 
          Return Code: 0 
          Data       : 
        } 
      ] 
    } 
    

    However, instead of using > in the command, you should use the STDOUT option instead.

    C:\>STAF local PROCESS START SHELL COMMAND "echo this is the string to be parsed" STDOUT "C:\Program Files\echofile.txt" WAIT RETURNSTDOUT STDERRTOSTDOUT 
    Response 
    -------- 
    { 
      Return Code: 0 
      Key        : <None> 
      Files      : [ 
        { 
          Return Code: 0 
          Data       : this is the string to be parsed 
    
        } 
      ] 
    }
    

2.3.4.

How do I use a static handle to have multiple programs access variables and log data?

If you have a program (PROG-A) that creates a static handle, and you want to start another program (PROG-B) using the STAF start command, such that PROG-B can create variables and a log using that same handle. The problem is that each program has to know the number of the static handle in order to use it. You can do this via an environment variable. So, from PROG-A, you could do something like:

request = 'start command cmd.exe parms "/c PROG-B" env STAFHANDLE='staticHandle
call STAFSubmit 'local', 'process', request

Then, PROG-B can pull the static handle from the environment variable.

2.3.5.

How do I change the system date/time to a prior date/time via a PROCESS START request?

If you change the system date/time on a machine to a prior date/time via a STAF PROCESS START request (with the WAIT option), you may encounter a problem where the PROCESS START request hangs.

This is a timing issue where the STAF thread which periodically checks for processes that have completed is waiting for an incorrect amount of time to wake up and check for the processes. When the date is set to an earlier date/time (while this thread is already waiting), the call to pthread_cond_timedwait (which should only be waiting for a second) is now waiting for the "earlier" time which causes it to hang. If you set the date to a later date/time, the pthread_cond_timedwait will return immediately.

This problem was fixed in STAF V3.4.21 for Unix operating systems that support monotonic clocks. Upgrade to STAF V3.4.21 or later if you are encountering ths problem. Note that HP-UX, Mac OS X, and z/OS do not support monotonic clocks.

Another workaround is to run the PROCESS START request asynchronously (i.e. omit the WAIT option). Then, after starting the process asynchronously, delay for a certain number of seconds (to allow the system date to be updated), then run a synchronous PROCESS START request where the command is "date" (to verify that it has been correctly updated), and then continue on with your tests.

Here is a command line example (from a RHEL6 system) of how you can validate the process to change the date to a prior time has worked.

First check the current date:

# STAF local PROCESS START SHELL COMMAND "date" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : Wed Oct  6 09:10:20 CDT 2010

    }
  ]
}

Next, run the PROCESS to change the date to an earlier time, and specify the STDOUT <file> and STDERRTOSTDOUT options., but not the WAIT option:

# STAF local PROCESS START SHELL COMMAND "date +%T -s 09:00:01" STDOUT {STAF/DataDir}/tmp/date-output.txt STDERRTOSTDOUT
Response
--------
34

Note that the response, 34, is the handle number for this process, which we will use later to check the RC of the process.

Next, check the current date again and you see the time was updated:

# STAF local PROCESS START SHELL COMMAND "date" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : Wed Oct  6 09:00:04 CDT 2010

    }
  ]
}

Note that the process which updated the system date is still not complete (even though the actual "date" process has finished). Running the above command will cause the thread waiting for process completions to finish to wake up (it wakes up at the timeout, or whenever a new process starts).

So now we can query the PROCESS handle:

# STAF local PROCESS QUERY HANDLE 34
Response
--------
Handle         : 34
Handle Name    : <None>
Title          : <None>
Workload       : <None>
Shell          : <Default Shell>
Command        : date +%T -s 09:00:01
Parms          : <None>
Workdir        : <None>
Focus          : Background
User Name      : <None>
Key            : <None>
PID            : 7690
Start Mode     : Async
Start Date-Time: 20101006-09:13:44
End Date-Time  : 20101006-09:00:04
Return Code    : 0

So we see the process completed with a return code 0.

And we can get the content of the standard output/error file:

# STAF local FS GET FILE {STAF/DataDir}/tmp/date-output.txt
Response
--------
09:00:01

2.4. LOG Service

2.4.1. How do I make each application have its own STAF log file?
2.4.2. How do I view a STAF log as it appears to be in some weird format?
2.4.1.

How do I make each application have its own STAF log file?

Use HANDLE logs instead of GLOBAL logs. With HANDLE logs each application will get a physically separate log file. HANDLE logs keep separate logs for each process even if the processes are using the same log names. The downside to HANDLE logs is you need to remember the handles you were using, so that you can query them. For example if you log data to a handle log, like so:

STAF local log LOG HANDLE LOGNAME testit LEVEL info MESSAGE hello

then you can query it like so:

STAF local log QUERY MACHINE m1 HANDLE h1 LOGNAME testit

In this request you need to know m1 (which should be your machines name) and h1 which you won't know until your program is executed.

To facilitate HANDLE based logs, it is probably a good idea for programs using them to write their name and handle to a GLOBAL log so that you can determine which HANDLE logs you need to query.

2.4.2.

How do I view a STAF log as it appears to be in some weird format?

This is the expected format for STAF logs (they are binary files, not text files). As a general rule you should use the LOG service itself to look at the logs. For example:

STAF local log query global logname stresstst

You can redirect that to another file, which will be in text format, if you want. You can also use the FmtLog utility (shipped with STAF) which will read a log file and format and write the data to an output file in a readable format.

2.5. HTTP Service

2.5.1. Does the HTTP Service retain session information across multiple requests?
2.5.1.

Does the HTTP Service retain session information across multiple requests?

Yes. Version 2.0 (and later) of the HTTP service provides the ability to group requests to the HTTP service together in a session. Performing requests in a session provides the ability simulate a browsing experience. Since a session provides memory about the last request it is possible to manipulate cookies, login into secure web sites, and interact with form and link html elements that are returned from requests.

2.6. STAX Service

2.6.1. How do I access system date and time in a STAX job?
2.6.2. How do I search for multiple strings in testcase output files in STAX?
2.6.3. How do I access STAF system variable values via a STAX job?
2.6.4. How do I use the <stopusing> element in a STAX job that runs on both Windows and Unix?
2.6.5. Does a STAX process element use the workdir element as the path to the command?
2.6.6. How do I use STAF and STAX to boot and shutdown VMWare images on my test machines?
2.6.7. How can I parse an XML file from a STAX job?
2.6.1.

How do I access system date and time in a STAX job?

You can either use the python libraries or the java libraries. Here is a STAX job which shows both approaches:

Example 1.  Accessing system date and time via Python libraries and Java libraries

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="test"/>

  <function name="test">
    <sequence>

      <!-- get the python date -->
      <script>
        from time import localtime, strftime
        currenttime = strftime("%a, %d %b %Y %H:%M:%S", localtime())
      </script>

      <message>'Python time: %s' % currenttime</message>

      <!-- get the java date -->
      <script>
        from java.util import Calendar, Date
        from java.text import SimpleDateFormat
        formatter = SimpleDateFormat("yyyy.MM.dd G 'at' hh:mm:ss a zzz")
        currentTimestamp = Date()
        dateString = formatter.format(currentTimestamp)
      </script>

      <message>'Java time: %s' % dateString&lt</message>

    </sequence>
  </function>

</stax>
2.6.2.

How do I search for multiple strings in testcase output files in STAX?

You can use the Python re library to search for multiple strings in testcase output files. For example, if you have a testcase output file c:/temp/test.txt:

Example 2. Contents of testcase output file c:/temp/test.txt

********************************* Top of Data **********************************
---------+---------+---------+---------+---------+---------+---------+---------+
   SET CURRENT SQLID='DBTIFAHC';
---------+---------+---------+---------+---------+---------+---------+---------+
DSNE616I STATEMENT EXECUTION WAS SUCCESSFUL, SQLCODE IS 0
---------+---------+---------+---------+---------+---------+---------+---------+
   SELECT * FROM SPA_FI_REGISTRY;
---------+---------+---------+---------+---------+---------+---------+---------+
FI_ID     AVLBLTY_STATUS  UPDATE_USER_ID
UPDATE_TMSTP
---------+---------+---------+---------+---------+---------+---------+---------+
IBANKA    S
STCCICS         2003-07-11-08.38.37.638163
DSNE610I NUMBER OF ROWS DISPLAYED IS 1
DSNE616I STATEMENT EXECUTION WAS SUCCESSFUL, SQLCODE IS 100
---------+---------+---------+---------+---------+---------+---------+---------+
-- INSERT INTO IFS_SESSN_ACTIVE
--   (USR_ID, FI_ID,SERV_ID,SESSN_NBR,IP_ADDR,SESSN_STRT_TMSTP,
--    SESSN_END_TMSTP,SESSN_ST_CODE, SESSN_MQ_QUALIFIER,CHK_DUPL_TXN,
--    SERV_INST_NBR)
  F1=Help    F2=Split   F3=Exit    F5=Rfind   F7=Up      F8=Down    F9=Swap
 F10=Left   F11=Right  F12=Cancel
                            SPUFI                              SSID: DB71
 ===>

 Enter the input data set name:        (Can be sequential or partitioned)
  1  DATA SET NAME ... ===> 'MONICA1.IFSSCCAH.SPUFI.CNTL(SELECT)'
  2  VOLUME SERIAL ... ===>            (Enter if not cataloged)
  3  DATA SET PASSWORD ===>            (Enter if password protected)
                    * DSNE361I SPUFI PROCESSING COMPLETE *

Here's a sample STAX job that searches for 3 sets of strings in the test.txt file.

Notice that when you specify the string text, you need to escape, with a backslash, any non-alphanumeric characters (such as spaces, dots, comma, equals, greater/less than, parenthesis...). You can find a Howto on Regular Expressions at http://www.amk.ca/python/howto/regex/.

Example 3.  Using Python re (regular expression) module to do string matches

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="test"/>

  <function name="test">
    <sequence>

      <stafcmd>
        <location>'local'</location>
        <service>'fs'</service>
        <request>'get file c:/temp/test.txt'</request>
      </stafcmd>

      <script>
        import re
        result = STAFResult

        searchre = r"""(?mx)
                       ^.*
                       ^.*?IBANKA.*?
                       ^.*
                       ^.*?1\ \ DATA\ SET\ NAME\ \.\.\.\ \=\=\=\>\ \'MONICA1\.IFSSCCAH\.SPUFI\.CNTL\(SELECT\)\'.*?
                       ^.*
                       ^.*?DSNE361I\ SPUFI\ PROCESSING\ COMPLETE.*?
                       ^.*"""
      </script>

      <if expr='re.match(searchre, result) != None'>
        <message>'Pass'</message>
        <else>
          <message>'Fail'</message>
        </else>
      </if>

    </sequence>
  </function>

</stax>
2.6.3.

How do I access STAF system variable values via a STAX job?

The STAF variables have to be resolved using either the VAR service through a <stafcmd> or using the STAXUtilImportSTAFVars function from the STAXUtil.xml file (provided with the STAX download in the library subdirectory of the STAX installroot).

Example 4. Using <stafcmd> to call the var service

  <stafcmd>
    <location>'local'</location>
    <service>'var'</service>
    <request>'resolve string {STAF/Config/STAFRoot}'</request>
  </stafcmd>
  <script>stafRoot=STAFResult</script>

Example 5. Using the STAXUtilImportSTAFVars function

  <call function="'STAXUtilImportSTAFVars'">
    [
      {'STAF/Env/STAFDir': 'mySTAFDir', 'STAF/Version': 'mySTAFVersion'},
      'machA'
    ]
  </call>

and the resulting STAX variables could be:

  mySTAFDir = 'C:\STAF'
  mySTAFVersion = '3.2.0'

See STAXUtil.html for full details.

2.6.4.

How do I use the <stopusing> element in a STAX job that runs on both Windows and Unix?

You can first determine whether the machine is Windows or non-Windows, set a variable to the STOPUSING option that you want to use on that operating system, and then use that variable in the <stopusing> element. Here is a sample STAX job:

Example 6. Setting the <stopusing> value based on the operating system

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="test"/>

  <function name="test">
    <sequence>

      <stafcmd>
        <location>'local'</location>
        <service>'var'</service>
        <request>'resolve string {STAF/Config/OS/Name}'</request>
      </stafcmd>

      <script>
        import re
        osname = STAFResult
      </script>

      <if expr='re.search("^win", osname.lower()) != None'>
        <script>stopusing = 'WM_CLOSE'</script>
        <else>
          <script>stopusing = 'SIGKILLALL'</script>
        </else>
      </if>

      <process>
        <location>'local'</location>
        <command>'java'</command>
        <stopusing>stopusing</stopusing>
      </process>

    </sequence>
  </function>

</stax>

2.6.5.

Does a STAX process element use the workdir element as the path to the command?

No. The STAF User's Guide, section 8.10.2 (PROCESS START) says:

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.

So, if the path to the command is not specified in the <command> element, the system PATH is searched. Just specifying the <workdir> will not make it use the workdir as the path and you'll get RC 10 (Base operating system error) because it couldn't find the command executable.

The following <process> element specifies the path (assigned to variable testdir) to the test1.exe executable since it's not in the system PATH:

Example 7. Specifying the path to the executable in the <command>

  <script>
    clientname = 'machineA.austin.ibm.com'
    testdir = 'C:/test'
  </script>

  <process>
    <location>clientname</location>
    <command>'%s/test1.exe' % (testdir)</command>
    <workdir>testdir</workdir>
  </process>

2.6.6.

How do I use STAF and STAX to boot and shutdown VMWare images on my test machines?

You can use STAF/STAX to boot VMWare images and then execute tests on the VMWare images. Below is a example that demonstrates how to do this. The "startvmware" function boots a VMWare image. Note that it's <function-prolog> has important information on how to configure your VMWare image to work correctly with STAF/STAX. The "stopvmware" function shuts down and powers off a VMWare image. The "main" function shows how you call the vmware functions. In your main function, after the VMWare image has booted (you would need to wait for an appropriate amount of time and do a STAF PING to the machine to determine that it's up and running), you would begin running your tests on the VMWare image.

Example 8. Using STAF/STAX to boot VMWare images and then execute tests

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="main"/>

  <function name="main" scope="local">

    <parallel>

      <block name="'Boot up VMWare image'">
        <call function="'startvmware'">
          { 'image': 'c:/vmware/winxp/Windows-XP-Professional.vmx',
            'timeout' : '5m', 'imagehostname' : 'abcdef',
            'imagename' : 'Windows XP Professional'
          }
        </call>
      </block>

      <block name="'Release this block to shutdown the VMWare image'">
        <sequence>

          <hold/>

          <call function="'stopvmware'">
            { 'imagehostname' : 'abcdef', 'shutdown' : 'shutdown -s -f -t 0' }
          </call>

        </sequence>
      </block>

    </parallel>

  </function>

  <function name="startvmware" scope="local">

    <function-prolog>
      Starts a VMWare image, and attempts to do a STAF PING to the VMWare image.
      Your VMWare image needs to be configured so that there are no popups
      displayed when the VMWare image starts (for example, messages about Disk
      Drive warnings, etc), and that the image is set up to automatically log
      in.  Also, the machine must be configured to start STAF automatically.
      Also, you must have the following 2 lines in your VMWare image's .vmx file:

      gui.exitOnCLIHLT = "TRUE"
      gui.exitAtPowerOff = "TRUE"

      Note that you should avoid terminating any blocks that are running a VMWare
      image, as that will kill the VMWare image without it being shutdown.  Instead,
      you should manually shutdown and power off the VMWare image, or call the
      "terminatevmware" [not yet implemented] function.

      You should use Bridged network connections for VMWare images to work
      correctly with this function.

    </function-prolog>

    <function-map-args>

      <function-optional-arg name="machine" default="'local'">
        The machine on which the VMWare image is to be started.  The default is 'local'.
      </function-optional-arg>

      <function-optional-arg name="vmwarebin" default="'c:/Program Files/Vmware/VMware Workstation/vmware.exe'">
        The VMWare executable file.  If the VMWare executable is not in the
        VMWare system's PATH, then the file must be fully qualified.
        The default is 'c:/Program Files/Vmware/VMware Workstation/vmware.exe'.
      </function-optional-arg>

      <function-required-arg name="image">
        The fully qualified VMWare .vmx file for the VMWare image.  Note that
        the VMWare executable does not permit spaces in the file name of the
        vmx file.
      </function-required-arg>

      <function-required-arg name="imagehostname">
        The hostname for the VMWare image.
      </function-required-arg>

      <function-optional-arg name="timeout" default="'10m'">
        The timeout value for when the function should stop attempting to
        STAF PING the VMWare image. The default is 10 minutes.  The STAF PING
        to the VMWare image will be attempted every 30 seconds, up to the
        timeout value.
      </function-optional-arg>

      <function-optional-arg name="imagename" default='image'>
        The name of the VMWare image.  The default is the argument specified
        for image.
      </function-optional-arg>

    </function-map-args>

    <parallel>

      <process name="'VMWare Image %s ' % imagename">
        <location>machine</location>
        <command>vmwarebin</command>
        <parms>'-x -q %s' % image</parms>  <!-- -x powers on automatically, -q exits at power off -->
        <stdout>'out.txt'</stdout>
        <stderr mode="'stdout'"/>
        <returnstdout/>
      </process>

      <sequence>

        <script>contacted = 0</script>

        <timer duration='timeout'>

          <loop while="contacted == 0">

            <sequence>

              <stafcmd name="'Delaying for 30 seconds'">
                <location>'local'</location>
                <service>'delay'</service>
                <request>'delay 30000'</request>
              </stafcmd>

              <stafcmd name = "'Attempt to ping %s' % imagehostname">
                <location>imagehostname</location>
                <service>'ping'</service>
                <request>'ping'</request>
              </stafcmd>

              <if expr="RC == 0">
                <sequence>
                  <script>contacted = 1</script>
                  <message>'Machine %s is up and running with VMWare image %s' % (imagehostname, imagename)</message>
                  <log>'Machine %s is up and running with VMWare image %s' % (imagehostname, imagename)</log>
                </sequence>
              </if>

            </sequence>

          </loop>

        </timer>

        <if expr="RC != 0">
          <sequence>
            <message>'Machine %s with VMWare image %s was not successfully started RC: %s' % (imagehostname, imagename, RC)</message>
            <log>'Machine %s with VMWare image %s was not successfully started RC: %s' % (imagehostname, imagename, RC)</log>
          </sequence>
        </if>

      </sequence>

    </parallel>

  </function>

  <function name="stopvmware" scope="local">

    <function-prolog>
      Stops a VMWare image
    </function-prolog>

    <function-map-args>

      <function-required-arg name="imagehostname">
        The hostname for the VMWare image.
      </function-required-arg>

      <function-required-arg name="shutdown">
        The command used to shut down the OS.
      </function-required-arg>

    </function-map-args>

    <sequence>

      <script>
          from com.ibm.staf import STAFUtil
      </script>

      <stafcmd>
        <location>imagehostname</location>
        <service>'process'</service>
        <request>'start async shell command %s' % STAFUtil.wrapData(shutdown)</request>
      </stafcmd>

    </sequence>

  </function>

</stax>
2.6.7.

How can I parse an XML file from a STAX job?

A STAX job can parse an XML file using an XML Parser of your choice. Below is a example that demonstrates how to do this using an XML Parser provided with java. This example parses an XML file whose name you specify and also validates the xml file. In this example, it's parsing a STAX xml file so it's using the STAX DTD but you could specify another DTD). This example also provides xml parsing error information, including the line number and xml parsing error message.

Example 9. Parsing an XML File from a STAX job

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="Main"/>
    
  <function name="Main">

    <sequence>
     
      <!-- Assign the file name of a STAX xml document you want to parse -->
      <call function="'parseXML'">'c:/dev/src/stax/leTest.xml'</call>

      <script>
        document = STAXResult

        # Change code here to parse the document as you desire.
        # The code shown here is just an example for parsing a STAX xml document

        root = document.getDocumentElement()
        children = root.getChildNodes()

        msg = ''

        for i in range(children.getLength()):
          thisChild = children.item(i);

          if (thisChild.getNodeType() == Node.ELEMENT_NODE and
              thisChild.getNodeName() == 'defaultcall'):
            msg = '%s\nFound defaultcall element' % (msg)
          elif thisChild.getNodeType() == Node.COMMENT_NODE:
            # Do nothing
            continue
          elif thisChild.getNodeType() == Node.ELEMENT_NODE:
            msg = '%s\nFound %s element' % (msg, thisChild.getNodeName())
      </script>

      <message>'Some parsed data: %s' % (msg)</message>
      <log>'Some parsed data: %s' % (msg)</log>

    </sequence>
  </function>
 
  <!-- ******************************************************************* -->
  <!-- Following function is used to parse an XML file and return the DOM  -->
  <!-- document object                                                     -->
  <!-- ******************************************************************* -->
  <function name="parseXML" scope="local">

    <function-list-args>
      <function-required-arg name="xmlFileName">
        Name of file containing XML to be parsed
      </function-required-arg>
    </function-list-args>

    <sequence>

      <!-- Parse the XML -->
      <script>
        factory = DocumentBuilderFactory.newInstance();
        factory.setValidating(1)
        factory.setIgnoringElementContentWhitespace(0)

        try:
          parseError    = 0
          builder  = factory.newDocumentBuilder()
          resolver = ParserResolver()
          builder.setEntityResolver(resolver)
          builder.setErrorHandler(resolver)
          document = builder.parse(xmlFileName)
        except SAXParseException, spe:
          parseError = 1
      </script>

      <!-- Quit if there is any parsing error -->
      <if expr="parseError">
        <sequence>
          <script>
            errmsg = 'Error occurred parsing file %s\n  line: %s\n  msg: %s' % (
              xmlFileName, spe.getLineNumber(), spe.getMessage()) 
          </script>         
          <log>errmsg</log>
          <message>errmsg</message>
          <terminate/>
        </sequence>
      </if>

      <return>document</return>

    </sequence>
  </function> 

  <script>

    # These imports only need to be done once per job, no matter
    # how many xml documents are parsed 

    from java.io import File
    from java.io import StringReader
    from org.xml.sax import InputSource
    from org.xml.sax import SAXParseException
    from org.xml.sax.helpers import DefaultHandler
    from javax.xml.parsers import DocumentBuilderFactory
    from javax.xml.parsers import DocumentBuilder
    from org.w3c.dom import Document
    from org.w3c.dom import Element
    from org.w3c.dom import Node
    from org.w3c.dom import NodeList

    # Name of file containing STAX DTD (or whatever DTD you want used) to
    # when validating/parsing an xml file
    dtdFileName = 'C:/stax.dtd'  

    # ************************************************************************ #
    # Following are the private Python classes                                 #
    # ************************************************************************ #

    # This class handles XML Parsing exceptions
    class ParserException(Exception):
        pass
    
    # This class handles the exception raised by XML parser
    class ParserResolver(DefaultHandler):
        def resolveEntity (self, publicId, systemId):
            return InputSource(dtdFileName)
        def error (self, e):
            raise 'error', e
        def warning (self, e):
            raise 'warning', e
        def fatalError (self, e):
            raise 'fatal', e
  </script>

</stax>

2.7. Globalization

2.7.1. How do I use STAF/STAX in environments where machines running STAF have different locales?
2.7.2. How do I specify non-ASCII characters in a STAF request or STAX job?
2.7.3. How do I know what codepage STAF is using on my machine?
2.7.1.

How do I use STAF/STAX in environments where machines running STAF have different locales?

In general, you don't have to do anything special.

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

How do I specify non-ASCII characters in a STAF request or STAX job?

If you're specifying a STAF request from the command line, then you can just specify the appropriate characters.

Example 10.  Specifying a French character in a STAF request submitted via the command line

STAF frenchMach PROCESS START COMMAND c:/test/TestA PARMS "-server français"

If you want to specify non-ASCII characters in a STAX job, then you need to specify them in Unicode.

Example 11. Specifying a French character in Unicode in a STAX job

  <process>
    <location>'frenchMach'</location>
    <command>'c:/test/TestA'</command>
    <parms>'-server fran' + u'\u00E7' + 'ais'</parms>
  </process>

Example 12. Specifying Chinese characters in Unicode in a STAX job

  <script>dirName = '/tmp/Sun2_' + u'\u4F3A\u670D\u5668'</script>

  <stafcmd>
    <location>'chineseMach'</location>
    <service>'FS'</service>
    <request>'CREATE DIRECTORY %s' % (dirName)</request>
  </stafcmd>

If you want to specify non-ASCII characters in a STAF request submitted via a Java program, then you need to specify them in Unicode.

Example 13. Specifying Chinese characters in Unicode in a PROCESS START request via a Java program

  String machine    = "chineseMach";
  String service    = "PROCESS";
  String serverName = "\u4F3A\u670D\u5668_HP";
  String request    = "START COMMAND " + STAFUtil.wrapData("/test/startServer.sh") +
                      " PARMS " + STAFUtil.wrapData(serverName) + " WAIT";
  STAFResult submitResult = handle.submit2(machine, service, request);

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. See section "2.7.1 Windows Codepage Translation Anomalies" in the STAF User's Guide for more information on these Windows codepage translation anomalies.

2.7.3.

How do I know what codepage STAF is using on my machine?

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

STAF testmach1 VAR RESOLVE STRING {STAF/Config/CodePage}

3. Debugging STAF

3.1. General Questions
3.1.1. What should I do if I'm having a problem with STAF or one of its services?
3.1.2. What information should I include when asking questions or reporting bugs?
3.1.3. Explain RC 16 when attempting to send a STAF request to a remote machine
3.1.4. Why can't my STAF machines communicate?
3.1.5. Why aren't my entries in /etc/hosts being used for STAF communication (particularly on Linux SLES)?
3.1.6. Why can't I use the HELP service when STAF is not running?
3.1.7. Why are there are more STAF processes on Linux?
3.1.8. Why am I having problems (such as an RC 6) submitting a request to a Java service?
3.1.9. Why is STAFProc terminating on some Unix platforms (such as Solaris) when the STAFProc terminal is exited?
3.1.10. Why don't I see any Java service output in the STAFProc console anymore?
3.1.11. When using Sun Java 1.4.2, why are the -Xmx settings for my Java STAF service not being used?
3.1.12. Explain RC 21 when submitting a STAF service request
3.1.13. Explain "Error accepting on server socket,socket RC: 24"
3.1.14. Explain error using STAF Java libraries on Linux: libJSTAF.so: undefined symbol: _ZNSt8ios_base4InitD1Ev"
3.1.15. Why is the performance slow when sending a STAF PING request to a remote machine?
3.1.16. Why does a request to the LOG, MONITOR, RESPOOL, or ZIP service fail with RC 2 (Unknown service)?
3.2. STAF Install Questions
3.2.1. If the InstallAnywhere installer fails, how do I get debug information?
3.2.2. What if AIX STAF environment variables (PATH, LIBPATH, etc.) are not set when opening a terminal?
3.2.3. When running STAFInst on Solaris, why does it fail with "test: unknown operator -ef"?
3.2.4. Explain message "JAR Archive failed security check corrupt JAR file" when trying to download a STAF jar file
3.2.5. Why does the STAF InstallAnywhere install fail on RHEL5?
3.2.6. What entries do I need for STAF in my /etc/profile file if I am using the STAF tar.gz installation?
3.3. STAF Startup Questions
3.3.1. Explain startup error: Error constructing service, JSTAF
3.3.2. Explain startup error: Error binding server socket, bind() RC=98 (or 67)
3.3.3. Explain startup error: Error binding server socket, bind() RC=10048
3.3.4. Explain startup error: 38:Illegal access to class: com.ibm.staf.service....
3.3.5. Why does STAF's user registration fail each time STAFProc is started?
3.3.6. Explain startup error: Error initializing service, RESPOOL. RC: 4008
3.3.7. What should I do if STAF fails to init with Windows Terminal Server?
3.3.8. On SLES8, why do I get an error starting STAF: STAFProc: /usr/lib/libstdc++.so.5: version `GLIBCPP_3.2.2' not found (required by STAFProc)
3.3.9. Explain startup error on z/OS: Error binding server socket, bind() RC=1115
3.3.10. Explain startup error: RC: 27, Error initializing service, JSTAF when using a GNU compiler for Java provided with Linux
3.3.11. Explain HPUX error "sh: SHLIB_PATH: Parameter not set." when running /usr/local/staf/STAFEnv.sh, or when running it via sourcing .profile)
3.3.12. When logged into the desktop on RHEL4-U4, if I run "STAFProc" or "STAF", I get "error while loading shared libraries: libSTAF.so".
3.3.13. Explain AIX error "Symbol XX__Q2_3std8ios_base is not exported from dependent module /usr/lib/libC.a"
3.3.14. Explain HPUX IA64 error /usr/lib/hpux32/dld.so: Unsatisfied code symbol '__cxa_get_exception_ptr' in load module './STAFProc'.
3.3.15. On Windows x86_64), explain error OS RC 14001: This application has failed to start because the application configuration is incorrect..
3.3.16. Explain Linux error "STAFProc: relocation error: undefined symbol: _ZNSs4_Rep20_S_empty_rep_storageE" when starting STAFProc.
3.3.17. Explain Solaris Sparc 64-bit error when starting STAFProc: "/usr/sfw/lib/libstdc++.so.6: wrong ELF class: ELFCLASS32".
3.3.18. Explain startup error: Error creating interface. Could not determine logical/physical identifier.
3.4. PROCESS Service Questions
3.4.1. Explain RC 10 when attempting to run a process
3.4.2. Explain RC 25 when starting a process on a remote machine
3.4.3. Explain why I'm having a problem interacting with process queues for processes started via the command line
3.4.4. Why are child processes not killed on Windows?
3.4.5. Why can't a STAF process log its output to an AFS directory?
3.4.6. Why do I get a SIGABRT after a STAF process has completed on HP-UX?
3.4.7. Explain error message: "STAFProcessManager::processMonitorThread: Parent could not set child's pgid: 13"
3.4.8. Explain Unix error message: STAFProcessManager::processMonitorThread: Could not start process (execve): 8
3.4.9. When running the ftp executable for Windows via a PROCESS START request, why aren't I getting the remote server responses in stdout?
3.4.10. Why do Expect scripts fail on Linux when STAFProc has been started during system reboot?
3.4.11. Why is different output returned by some commands such as "reg query" when run using a win32 version of STAF on a Windows 64-bit system?
3.5. FS Service Questions
3.5.1. Why does COPY FILE request fail when no TOMACHINE is specified?
3.5.2. Why are my text files copied via the FS service not converted correctly between Windows and Unix?
3.5.3. Why can't I copy a file that is larger then 4GB?
3.5.4. Why does FS LIST COPYREQUESTS show a copy request in progress on the destination machine that has already failed with a RC 22?

3.1. General Questions

3.1.1. What should I do if I'm having a problem with STAF or one of its services?
3.1.2. What information should I include when asking questions or reporting bugs?
3.1.3. Explain RC 16 when attempting to send a STAF request to a remote machine
3.1.4. Why can't my STAF machines communicate?
3.1.5. Why aren't my entries in /etc/hosts being used for STAF communication (particularly on Linux SLES)?
3.1.6. Why can't I use the HELP service when STAF is not running?
3.1.7. Why are there are more STAF processes on Linux?
3.1.8. Why am I having problems (such as an RC 6) submitting a request to a Java service?
3.1.9. Why is STAFProc terminating on some Unix platforms (such as Solaris) when the STAFProc terminal is exited?
3.1.10. Why don't I see any Java service output in the STAFProc console anymore?
3.1.11. When using Sun Java 1.4.2, why are the -Xmx settings for my Java STAF service not being used?
3.1.12. Explain RC 21 when submitting a STAF service request
3.1.13. Explain "Error accepting on server socket,socket RC: 24"
3.1.14. Explain error using STAF Java libraries on Linux: libJSTAF.so: undefined symbol: _ZNSt8ios_base4InitD1Ev"
3.1.15. Why is the performance slow when sending a STAF PING request to a remote machine?
3.1.16. Why does a request to the LOG, MONITOR, RESPOOL, or ZIP service fail with RC 2 (Unknown service)?
3.1.1.

What should I do if I'm having a problem with STAF or one of its services?

If you are having a problem with STAF or one of its services, follow these steps to resolve the problem:

  1. View the topics listed in this FAQ to determine if any of the topics can help you to resolve the problem.

  2. View the STAF Bugs to see if the problem has already been reported.

  3. If you are not sure if the problem is a STAF bug, then post a question to the STAF Help forum.

    If you are fairly certain that this is a bug with STAF or one of its services, then Submit a new Bug.

3.1.2.

What information should I include when asking questions or reporting bugs?

When you are posting to the Help forum or submitting a new bug, the STAF development team will be better able to quickly resolve your problem if you supply the following information:

  • The OS platform and version number
  • The version of STAF that you are running. The version is displayed when you start STAFProc ("STAFProc version 3.2.0 initialized").
  • If you are having a problem with a STAF service, include the service's version number (this can be obtained by typing: staf local service version")
  • If you can't start STAFProc due to an error in the STAF configuration file, include the entire contents of the STAF.cfg file.
  • If you are having a problem with a Java STAF service, include the Java version (this can be obtained by typing: java -version) and include any errors in the JVM log for the Java STAF service (located in {STAF/DataDir}/lang/java/jvm/<JVMName>/JVMLog.1).
  • If you are having a problem installing STAF, include the type of installation where the problem occurs (InstallAnywhere executable, GNU zipped tar).

3.1.3.

Explain RC 16 when attempting to send a STAF request to a remote machine

Return code of 16 means "No Path To Endpoint". This means that STAF could not talk to the target system, with likely causes being:

  • STAF is not running on the target system.
  • An invalid or unreachable endpoint (e.g. an invalid hostname or IP address) was specified.
  • The network interface or port specified in the endpoint is not supported on the target system. The network interfaces are configured in the STAF.cfg file and can be listed by submitting a LIST INTERFACES request to the MISC service.
  • A firewall is blocking communication via the STAF TCP/IP port configured for the network interface in your STAF.cfg. Note that the default STAF TCP/IP port is 6500.
  • The DNS on one of the machines is not set up correctly. Refer to "Why can't my STAF machines communicate?".
  • You may need to increase your CONNECTTIMEOUT value for the network interface and/or increase your CONNECTATTEMPTS value in your STAF.cfg file.

3.1.4.

Why can't my STAF machines communicate?

If you are having problems getting two STAF machines to communicate, try the following steps on each machine:

  • On each machine, run ping other-machine hostname to determine if the machines can communicate.

  • On machine1, get the output from:

    staf local var resolve string {STAF/Config/Machine}
    

  • Then, on machine2, run:

    staf machine1-var ping ping
    

    where machine1-var is the output from the var resolve.

    If the ping does not work (in either direction), then you need to update the DNS settings so that the machines can communicate.

Procedure 2. Changing the DNS settings on Windows 2000

  1. From the "Start" menu, select "Network and Dialup Connections" and then select "Local Area Connection"
  2. Then click on "Properties" and select "Internet Protocol (TCP/IP)" and click on "Properties"
  3. Next, click on "Advanced" and make sure that the field for "DNS suffix for this connection:" shows the correct domain name (such as "austin.ibm.com")
  4. Another thing to verify is the Network Identification. From the "Start" menu, select "Settings" and then "Control Panel"
  5. Next, select "System" and then select the "Network Identification" tab
  6. Then click on "Properties" and make sure that the "Computer name:" is correct
  7. Then click on "More" and make sure that the "Primary DNS suffix of this computer shows the correct domain name (such as "austin.ibm.com")

Procedure 3. Changing the DNS settings on Windows XP

  1. From the "Start" menu, select "Network Connections" and then select your Local Area Connection
  2. Then click on "Properties" and select "Internet Protocol (TCP/IP)" and click on "Properties"
  3. Next, click on "Advanced" and then the "DNS" tab. Make sure that the field for "DNS suffix for this connection:" shows the correct domain name (such as "austin.ibm.com")
  4. The second place to verify is the Computer Name. From the "Start" menu, select "Control Panel"
  5. Next, select "System" and then select the "Computer Name" tab
  6. Then click on "Change" and make sure that the "Computer name:" is correct
  7. Then click on "More" and make sure that the "Primary DNS suffix of this computer" shows the correct domain name (such as "austin.ibm.com")

The following paragraph only applies to IBM users of STAF/STAX. If you are running a Windows e-business client, and other machines can't ping the e-business client, it is likely that the e-business client is running "Net Firewall", which disables the ability of other machines to ping the e-business client (which also means that STAFProc on other machines will not be able to communicate with the e-business client). To determine if the machine is running Net Firewall, open the Network Connection the machine is using, and click on "Properties". If "Net Firewall" is listed as a component, and it is checked, then the e-business client will experience this problem. If you uncheck "Net Firewall" and click on OK, other machines will be able to ping the e-business client, and STAFProc on other machines will be able to communicate with the e-business client.

Caution

DO NOT UNINSTALL NET FIREWALL! The AT&T Net Client will not run without Net Firewall, and if Net Firewall is uninstalled, you must completely reinstall the AT&T Net Client.

Procedure 4. Changing the DNS settings on Linux

  1. Edit the /etc/sysconfig/network file and change the HOSTNAME line to include the domain name (e.g. austin.ibm.com) as part of the hostname. For example::
    HOSTNAME="client1.austin.ibm.com"
    
  2. and add a line specifying the domain name (e.g. austin.ibm.com):
    DOMAINNAME="austin.ibm.com"
    
  3. Reboot the machine

Note

Certain versions of Linux set up a high level of security access for incoming requests on specific ports (including STAF requests, which, by default, come in through port 6550 for the ssl interface or 6500 for the tcp interface). From a Linux machine, if you are able to successfully send a staf ping to another machine, but the other machine cannot do a staf ping to the Linux machine (and you have verified that the DNS information is set up correctly on both machines), try the following (note that you may need to customize these commands depending on the Linux distribution):

  1. On RedHat 8.0, edit the /etc/sysconfig/iptables file and add the following lines:
    -A RH-Lokkit-0-50-INPUT -p tcp -m tcp --dport 6500 --syn -j ACCEPT
    -A RH-Lokkit-0-50-INPUT -p tcp -m tcp --dport 6550 --syn -j ACCEPT
    

    Be sure to add these ACCEPT lines to accept traffic via the tcp ports you've configured for STAF before the REJECT or DROP line in the iptables file which rejects/drops all other traffic.

  2. On RHEL4 and RHEL5, edit the /etc/sysconfig/iptables file and add the following lines:
    -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 6500 -j ACCEPT
    -A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 6550 -j ACCEPT
    

    Be sure to add these ACCEPT lines to accept traffic via the tcp ports you've configured for STAF before the REJECT or DROP line in the iptables file which rejects/drops all other traffic.

  3. Then execute:
    /etc/rc.d/init.d/iptables restart
    

Procedure 5. Changing the DNS settings on HP-UX

  1. Edit the /etc/rc.config.d/netconf file and change the HOSTNAME line to include the domain name (e.g. austin.ibm.com) as part of the hostname. For example:
    HOSTNAME="client1.austin.ibm.com"
    
  2. and add a line specifying the domain name (e.g. austin.ibm.com):
    DOMAINNAME="austin.ibm.com"
    
  3. Reboot the machine
3.1.5.

Why aren't my entries in /etc/hosts being used for STAF communication (particularly on Linux SLES)?

On Linux, if you are using /etc/hosts to specify hostnames/IPs, and a regular "ping" to the hostname works, but a STAF ping fails with RC 16, it is likely that your /etc/hosts file is not being used.

Ensure that your /etc/host.conf file looks contains

order hosts, bind

Also verify that the /etc/nsswitch.conf file contains:

hosts:          files dns

If your /etc/host.conf file contains the following line:

multi on

Verify that you are using STAF V3.1.5 or later (which contains a fix for handling 'multi on'). If you are using an earlier version of STAF, you can workaround this problem by commenting out the 'multi on' line, and then restarting STAFProc.

3.1.6.

Why can't I use the HELP service when STAF is not running?

staf local help error error-number doesn't work if STAF is not running on your workstation. Users can access help messages offline (when STAF isn't running) by viewing the STAF documentation. STAF documentation is installed on the local system (if a typical install was done). The "STAF API Return Code Reference" contains a quick reference to the STAF return codes and is available at staf/docs/STAFRC.htm or you can view it on the STAF SourceForge website at http://staf.sourceforge.net/current/STAFRC.htm.

3.1.7.

Why are there are more STAF processes on Linux?

If you issue the following command

ps -ef | grep -i staf,

you will see more STAFProc processes (typically 10 or more) on Linux than on other platforms (which there's only one).

This is because the Linux base operating system doesn't really have threads. Threads are simulated on Linux using processes, so each thread shows up as a process.

3.1.8.

Why am I having problems (such as an RC 6) submitting a request to a Java service?

If you are having a problem accessing a Java service, such as getting an RC 6 for any request you make to a Java service, the Java service's JVM may have encountered an error or may have been killed. Check the Java service's JVM log to see if any errors were logged. The JVM logs are stored in the {STAF/DataDir}/lang/java/jvm/<JVMName> directory on the system where the Java service is registered. The current JVM log is named JVMLog.1.

If the JVM log contains an OutOfMemory error, any Java services using this JVM will have to be removed and added (registered) in order to start accepting requests. You may want to look at increasing the JVM's maximum heap size as the Java service(s) using this JVM may require more memory than can be allocated. Refer to the STAF User's Guide, section "4.4.3 JSTAF service proxy library", for more information on how to do this.

Make sure you are using STAF V3.1.5 or later which contains a significant memory leak fix for STAF Java support.

If the JVM was killed, there won't be errors regarding this in the JVM log, but the following error is written to the STAFProc window when a request is made to a Java service whose java executable has died:

In JSTAF.STAFServiceAcceptRequest:
Caught STAFException
Name : STAFConnectionConnectException
Location : d:\dev\sf\src\staf\stafif\win32\STAFLocalConnection.cpp(162)
Text : OpenProcess2
Error code: 87

If the JVM was killed, any Java services using this JVM will have to be removed and added (registered) in order to start accepting requests.

3.1.9.

Why is STAFProc terminating on some Unix platforms (such as Solaris) when the STAFProc terminal is exited?

For example, if you have a script such as:

PATH=/usr/local/staf/bin:/usr/local/java/bin:$PATH
export PATH
CLASSPATH=/usr/local/staf/lib:/usr/local/staf/lib/JSTAF.jar:$CLASSPATH
export CLASSPATH
STAFCONVDIR=/usr/local/staf/codepage
export STAFCONVDIR
LD_LIBRARY_PATH=/usr/local/staf/lib:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
/usr/local/staf/bin/STAFProc &

STAF will start fine if you log in and exec this script, but when you log out, STAF terminates.

To resolve this you should change the last line in the script to:

nohup /usr/local/staf/bin/STAFProc >/tmp/STAFProc.out 2>&1 &

You should redirect STAFProc's stdout and stderr to a file, as shown above, because STAFProc's output is very important when investigating a STAF problem.

# man nohup

NAME
     nohup - run a command immune to hangups

SYNOPSIS
     /usr/bin/nohup command [ argument ...]
     /usr/xpg4/bin/nohup command [ argument ...]

DESCRIPTION
     The nohup utility invokes the named command with argu-
     ments supplied.  When the command is invoked, nohup arranges
     for the SIGHUP signal to be ignored by the process.

     The nohup utility can be used when it is known that command
     will take a long time to run and the user wants to logout of
     the terminal; when a shell exits, the system sends its chil-
     dren SIGHUP signals, which by default cause them to be
     killed.  All stopped, running, and background jobs will
     ignore SIGHUP and continue running, f their invocation is
     preceded by the nohup command or if the process programmati-
     cally has chosen to ignore SIGHUP.
3.1.10.

Why don't I see any Java service output in the STAFProc console anymore?

The console output was redirected because in STAF 2.4.4 we changed the way JVMs for STAF Java services (such as STAX) output all of their stdout/stderr data (including the output of <script>print...</script> since that is being written to the JVM's stdout). All of the output that was formerly in the console output should now be in the JVMLog file. The file is located at:

{STAF/DataDir}/lang/java/jvm/JVM Name/JVMLog.x

where x is a number and JVM Name is STAFJVM1 by default unless you used the JVMName OPTION when configuring the Java service and set it to another name.

If you look at your {STAF/DataDir}/lang/java/jvm/STAFJVM1/JVMLog.1 file, you should see something like:

 ******************************************************************************
 *** 20030418-14:40:33 - Start of Log for JVMName: STAFJVM1
 *** JVM Executable: java
 *** JVM Options : none
 ******************************************************************************

3.1.11.

When using Sun Java 1.4.2, why are the -Xmx settings for my Java STAF service not being used?

This appears to be a bug in Sun Java 1.4.2 where it is not using the -Xmx heap settings. This means that if you are running Java STAF services with Sun 1.4.2, and specifying the OPTION J2=-Xmx option, the option will not be used and your service JVM will run out of memory at a much lower heap size (the actual limit seems to vary by OS).

IBM Java 1.4.2 works correctly (http://www-106.ibm.com/developerworks/java/jdk/index.html)

3.1.12.

Explain RC 21 when submitting a STAF service request

You can use the STAF HELP service's ERROR request to get more information about STAF return codes such as RC 21. For example:

C:\>STAF local HELP ERROR 21
Response
--------
Description: STAF not running
Details    : This indicates that STAFProc is not running on the local machine
with the same STAF_INSTANCE_NAME (and/or the same STAF_TEMP_DIR if on a Unix
machine).

Notes:
1. If the STAF_INSTANCE_NAME environment variable is not set, it defaults
   to "STAF".
2. On Unix, if the STAF_TEMP_DIR environment variable is not set, it defaults
   to "/tmp".  This environment variable is not used on Windows.
3. This error can also occur when submitting a request using the local IPC
   interface on a Unix machine if the socket file that the local interface
   uses has been inadvertently deleted.
4. On Windows, with User Account Controls (UAC) enabled, if STAFProc.exe is
   being run as an Administrator, this error will occur if a STAF service
   request is not also run as an Administrator (e.g. from an "Administrator:
   Command Prompt") or if programs that submit STAF service requests using
   STAF APIs for Java, C/C++, Perl, Python, or Tcl are not run an an
   Administrator. See section "5.1.2 Running STAFProc on Windows with User
   Account Controls (UAC) Enabled" in the STAF User's Guide for more
   information.
5. More information on this error may be displayed if you set special
   environment variable STAF_DEBUG_21=1 and resubmit your STAF service
   request.

Also, note that on Unix systems, when executing STAFEnv.sh during system startup, it is possible to inadvertently pass "start" as the parameter to STAFEnv.sh (and so STAFProc is using that as the instance name when it starts). In this scenario, if you run STAF <unix-machine> VAR LIST from another machine and examine the value of STAF/Config/InstanceName, the value will be set to "start". So, even though "echo $STAF_INSTANCE_NAME" is set to "STAF" as expected when you run "STAF local PING PING", the value that STAFProc is using does not match, and so you get an RC 21.

If this is the case, you can resolve the problem by adding a "shift" command to the start section of the STAF startup script just before STAFEnv.sh is called. That way, the parameters are decremented from 1 to 0. So you would have something like:

'start')
        if [ -f /etc/rc.config.d/staf ]; then
                . /etc/rc.config.d/staf
        fi
        if [ $STAF -eq 1 ]; then
                shift
                . /usr/local/staf/STAFEnv.sh
                /bin/nohup STAFProc 2>error &
        fi
        ;;

3.1.13.

Explain "Error accepting on server socket,socket RC: 24"

This error can occur when your system has run out of file descriptors because too many files have been opened and you've exceeded the maximum number of open files allowed by your system. Anytime a file is opened, a file descriptor must be used to allow the program to access the data. When the STAF connection provider calls accept() to accept a connection on a socket and it's failing to open the socket and setting errno to 24 (this is the error code on Unix systems). In /usr/include/asm/errno.h on Linux systems, errno 24 is defined as:

#define EMFILE          24      /* Too many open files */
EMFILE The per-process limit of open file descriptors has been reached.

To see what files are open on Unix machines, use the lsof command. It lists the names of the open files and the pids of the processes that opened them. You can list the open files for a process by getting it's pid and then run lsof -p <pid>command>.

If you you are using the STAX service on this machine, it's possible that a STAX job could be responsible for opening files and not closing them. Refer to Explain "RC 21 submitting a STAX EXECUTE request" for more information on this.

3.1.14.

Explain error using STAF Java libraries on Linux: libJSTAF.so: undefined symbol: _ZNSt8ios_base4InitD1Ev"

This error can occur when using the STAF Java libraries on Linux systems using IBM Java 5.0 SR 11 (or later) or IBM Java 6.0 SR7 (or later).

This problem is fixed in STAF V3.4.1 and later.

3.1.15.

Why is the performance slow when sending a STAF PING request to a remote machine?

If submitting a STAF PING request to the PING service on a remote machine is slow (e.g. > 5 seconds), and it is not because the network is slow, a hostname resolution issue may be causing the performance issue. To debug this, enable the STAF warning and error tracepoints on both machines and redirect the STAFProc trace output to a file by running the following commands on each machine (specifying a file name of your choice):

STAF local TRACE ENABLE TRACEPOINTS "warning error"
STAF local TRACE SET DESTINATION TO FILE "/tmp/STAFProc.trc"

Then, submit the STAF PING request to the PING service on the remote machine again and check if there are any errors or warnings logged in the STAF trace files on each machine.

If you see a trace warning message like the following:

Error getting hostname (for IP address 99.99.999.99, STAFSocketGetNameByInAddr(), RC: 0,
Info: Error getting hostent structure: gethostbyaddr_r() host_error=2 after retrying 20 times 

there is a problem resolving the host name. You may be able to resolve the issue by adding a hostname entry to the hosts network hostname file (e.g. /etc/hosts) which keeps track of the mapping between host names and IP addresses.

Or, if you see a trace warning message like the following:

STAFConnectionManager::makeConnection - Attempt #1 of 2 (Delay 91 milliseconds), RC: 16, Result: <Error Message>

you may want to increase the CONNECTTIMEOUT specified for the ssl and tcp interfaces in the STAF.cfg file on the machine submitting the STAF service request. The default connect timeout value is 5 seconds (5000 milliseconds). To increase it the connect timeout to 10 seconds, edit the STAF.cfg file and add option CONNECTTIMEOUT 10000 to the ssl and tcp interfaces. For example:

# Enable TCP/IP connections
interface ssl library STAFTCP option Secure=Yes option Port=6550 option CONNECTTIMEOUT=10000
interface tcp library STAFTCP option Secure=No  option Port=6500 option CONNECTTIMEOUT=10000

Note: You must shutdown and restart STAFProc for any changes in the STAF.cfg file to take effect.

3.1.16.

Why does a request to the LOG, MONITOR, RESPOOL, or ZIP service fail with RC 2 (Unknown service)?

If you get RC 2 (Unknown service) submitting a STAF request to the LOG, MONITOR, RESPOOL, or ZIP service (which are all external, not internal, STAF services), it may be because you don't have the STAF default service loader service reqistered in the STAF configuration file. The default service loader service is implemented by library STAFDSLS and it dynamically loads the Log, Zip, Monitor, and ResPool C++ services if they haven't already been registered. This service loader is configured automatically in the default STAF.cfg file as follows:

# Add default service loader
serviceloader library STAFDSLS

Note that if you list all the STAF services via a "LIST SERVICES" request submitted to the SERVICE service, you won't see the LOG, MONITOR, RESPOOL, or ZIP services registered (if not explicitly registered) until a request has been submitted to these services because then the STAFDSLS service will dynamically load the service if it isn't already registered.

3.2. STAF Install Questions

3.2.1. If the InstallAnywhere installer fails, how do I get debug information?
3.2.2. What if AIX STAF environment variables (PATH, LIBPATH, etc.) are not set when opening a terminal?
3.2.3. When running STAFInst on Solaris, why does it fail with "test: unknown operator -ef"?
3.2.4. Explain message "JAR Archive failed security check corrupt JAR file" when trying to download a STAF jar file
3.2.5. Why does the STAF InstallAnywhere install fail on RHEL5?
3.2.6. What entries do I need for STAF in my /etc/profile file if I am using the STAF tar.gz installation?
3.2.1.

If the InstallAnywhere installer fails, how do I get debug information?

The STAF IA installers will create a log file called STAFInstall.log in the root install directory.

The install log will contain a "Summary" section with status information for the install. If there were any errors during the install, the "Install Log Detail" section will contain information about the errors.

3.2.2.

What if AIX STAF environment variables (PATH, LIBPATH, etc.) are not set when opening a terminal?

Edit the file ~/.Xdefaults (create it in your home directory if it does not exist) and add the following line:

*loginShell:true

Save the changes and logout/login. Any terminals that you open will have /etc/profile executed automatically (so that STAF's InstallAnywhere environment variable updates will be read).

3.2.3.

When running STAFInst on Solaris, why does it fail with "test: unknown operator -ef"?

If you receive this error message when running the command ./STAFInst" on Solaris, this indicates that the current Solaris shell does not support certain "test" commands. The solution for this problem is to enter bash at your shell prompt prior to entering ./STAFInst.

3.2.4.

Explain message "JAR Archive failed security check corrupt JAR file" when trying to download a STAF jar file

Certain browsers may report this problem when downloading jar files. To resolve the problem, "shift-click" on the link to download the jar file.

3.2.5.

Why does the STAF InstallAnywhere install fail on RHEL5?

When installing using IA on RHEL5, when attempting to launch the STAF installer, the following error may be seen: "The installer is unable to run in graphical mode.". On RHEL5, the libraries required to run a Swing based Java application (such as our STAF installers) may not be installed by default. See this Macrovision (InstallShield, InstallAnywhere) article for more information.

To resolve the problem, install the required X libraries on the RHEL5 system. For example, download libXp-1.0.0-8.1.el5.i386.rpm and install it via RPM.

3.2.6.

What entries do I need for STAF in my /etc/profile file if I am using the STAF tar.gz installation?

Below is an example of the lines needed in /etc/profile when using the STAF tar.gz installation. You can cut and paste this directly into your /etc/profile if you have installed STAF to the default location (/usr/local/staf):

if [ -z "`echo $PATH`" ]
then
PATH=/usr/local/staf/bin
else
PATH=`echo $PATH`:/usr/local/staf/bin
fi
export PATH

if [ -z "`echo $LD_LIBRARY_PATH`" ]
then
LD_LIBRARY_PATH=/usr/local/staf/lib
else
LD_LIBRARY_PATH=`echo $LD_LIBRARY_PATH`:/usr/local/staf/lib
fi
export LD_LIBRARY_PATH

if [ -z "`echo $CLASSPATH`" ]
then
CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar
else
CLASSPATH=/usr/local/staf/lib/JSTAF.jar:/usr/local/staf/samples/demo/STAFDemo.jar:`echo $CLASSPATH`
fi
export CLASSPATH

STAFCONVDIR=/usr/local/staf/codepage
export STAFCONVDIR

Note that this example is for Linux. On other Unix platforms, use the appropriate library environment variable (instead of LD_LIBRARY_PATH).

3.3. STAF Startup Questions

3.3.1. Explain startup error: Error constructing service, JSTAF
3.3.2. Explain startup error: Error binding server socket, bind() RC=98 (or 67)
3.3.3. Explain startup error: Error binding server socket, bind() RC=10048
3.3.4. Explain startup error: 38:Illegal access to class: com.ibm.staf.service....
3.3.5. Why does STAF's user registration fail each time STAFProc is started?
3.3.6. Explain startup error: Error initializing service, RESPOOL. RC: 4008
3.3.7. What should I do if STAF fails to init with Windows Terminal Server?
3.3.8. On SLES8, why do I get an error starting STAF: STAFProc: /usr/lib/libstdc++.so.5: version `GLIBCPP_3.2.2' not found (required by STAFProc)
3.3.9. Explain startup error on z/OS: Error binding server socket, bind() RC=1115
3.3.10. Explain startup error: RC: 27, Error initializing service, JSTAF when using a GNU compiler for Java provided with Linux
3.3.11. Explain HPUX error "sh: SHLIB_PATH: Parameter not set." when running /usr/local/staf/STAFEnv.sh, or when running it via sourcing .profile)
3.3.12. When logged into the desktop on RHEL4-U4, if I run "STAFProc" or "STAF", I get "error while loading shared libraries: libSTAF.so".
3.3.13. Explain AIX error "Symbol XX__Q2_3std8ios_base is not exported from dependent module /usr/lib/libC.a"
3.3.14. Explain HPUX IA64 error /usr/lib/hpux32/dld.so: Unsatisfied code symbol '__cxa_get_exception_ptr' in load module './STAFProc'.
3.3.15. On Windows x86_64), explain error OS RC 14001: This application has failed to start because the application configuration is incorrect..
3.3.16. Explain Linux error "STAFProc: relocation error: undefined symbol: _ZNSs4_Rep20_S_empty_rep_storageE" when starting STAFProc.
3.3.17. Explain Solaris Sparc 64-bit error when starting STAFProc: "/usr/sfw/lib/libstdc++.so.6: wrong ELF class: ELFCLASS32".
3.3.18. Explain startup error: Error creating interface. Could not determine logical/physical identifier.
3.3.1.

Explain startup error: Error constructing service, JSTAF

You can get an error like the following when STAF attempts to register a Java service (such as Event, STAX, EventManager, Cron, Email, etc) that is configured in the STAF.cfg file:

Error code: 27
Reason    : Error constructing service, JSTAF, Result: Unable to connect to JVM

When you get this error, look at the contents of the JVM log for this Java STAF service (located in {STAF/DataDir}/lang/java/jvm/<JVMName>/JVMLog.1) to get more information about the cause of the error. For example, the following is an example of an error logged in the C:\STAF\data\lang\java\jvm\STAFJVM1\JVMLog.1 file when STAFProc cannot find the "java" binary executable on Windows:

******************************************************************************
*** 20140102-12:40:48 - Start of Log for JVMName: STAFJVM1
*** JVM Executable: java
*** JVM Options   : none
*** JVM Version   : '"java"' is not recognized as an internal or external command,
operable program or batch file.

This error could occur if Java has not been installed on the system, or if Java has been installed but the "java" binary executable is not in the PATH environment variable in the environment in which you are running STAFProc (or if you specified the JVM option when registering a Java STAF service and specified an incorrect path to the location of the "java" binary executable). To fix this problem, make sure that Java is installed on this system and then do one of the following:

  1. Make sure the "java" binary executable is available in the PATH environment variable by verifying that running java -version from a shell prompt works and returns the version of Java found in the PATH,

    - OR -

  2. Use the JVM option to specify the location of the java executable when registering the Java STAF service in the STAF.cfg file. For example, if the fully qualified location of the java executable is "C:\jdk7\jre\bin\java.exe", use the JVM option as follows to specify this when registering a Java service such as STAX:

    SERVICE STAX LIBRARY JSTAF EXECUTE C:/STAF/services/stax/STAX.jar \
            OPTION JVMName=STAX OPTION JVM="C:/jdk7/jre/bin/java"
    
3.3.2.

Explain startup error: Error binding server socket, bind() RC=98 (or 67)

This error can occur on Unix if STAFProc has not been shutdown correctly. The error will be displayed when you attempt to restart STAFProc. You should always shutdown STAF by submitting a SHUTDOWN request to the STAF SHUTDOWN service. For example:

STAF local SHUTDOWN SHUTDOWN

If you don't submit a SHUTDOWN request and instead kill the STAFProc process, then STAFProc is not given the opportunity to kill other processes that it started and to perform clean-up activities such as deleting it's temporary files.

For example, say you started STAFProc when logged in as the root user, and then you killed STAFProc instead of submitting a SHUTDOWN request. Then, you logged in as a non-root user and attempted to start STAFProc. STAFProc may fail to start with a "Error binding server socket" message because the non-root user does not have permission to delete the temporary STAF files that were previously created by the root user (and were not deleted since STAFProc was not shutdown correctly).

To resolve the problem:

  1. Go to the /tmp directory, and delete the temporary files that STAF created for the instance of STAFProc that you're trying to start. You'll need to be logged on as a user that has permission to remove these files. The temporary STAF files are named:

    • XXXX.tmp
    • DataDir_*XXXX.tmp
    • STAFIPC_XXXX
    • All files beginning with STAFIPC_XXXXJSTAF. Note that there could be one of these files for each STAF JVM that was created when registering STAF Java services.

    Note that you need to replace XXXX with the STAF Instance Name. The default STAF Instance Name is STAF if you didn't override it by setting the STAF_INSTANCE_NAME environment variable.

    So, if you are trying to start STAFProc using the default STAF instance name STAF, then to delete these temporary STAF files, you could run the following commands when logged on as a user that has permission to remove these files:

       rm /tmp/STAF.tmp
       rm /tmp/DataDir_*STAF.tmp
       rm /tmp/STAFIPC_STAF
       rm /tmp/STAFIPC_STAFJSTAF*
    
  2. Also, type ps or ps -ea and determine if there are any processes that STAF started which are still running or any java executables that STAF started for it's Java services. If there are any, you'll need to stop these processes in order to restart STAFProc. You can do this by typing kill xxx where xxx is the PID for the process.

  3. Restart STAFProc

As a last resort if the above steps did not resolve the problem, reboot the machine.

3.3.3.

Explain startup error: Error binding server socket, bind() RC=10048

This indicates that the socket address is already in use. This error occurs if STAF attempts to bind a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing.

You can also try typing ps or ps -ea and determine if there are any processes that STAF started which are still running or any java executables that STAF started for it's Java services. If there are any, you'll need to stop these processes in order to restart STAFProc. You can do this by typing kill xxx where xxx is the PID for the process.

Note

Some Solaris systems require a system reboot to fix this condition.

3.3.4.

Explain startup error: 38:Illegal access to class: com.ibm.staf.service....

This error occurs if you attempt to register a Java service that has not been declared public in its class definition. Every STAF Java service's class definition should look like:

public class CronService implements STAFServiceInterfaceLevel3

3.3.5.

Why does STAF's user registration fail each time STAFProc is started?

During the STAF installation, if you selected to register STAF, everytime STAF starts it will attempt to register the user information with a machine that is internal to IBM. Once this registration is successful, STAF will no longer try to register. However, the registration will fail for all non-IBM users, and will attempt to register (and fail) each time STAF is started. You can either choose to let it fail forever, or delete the STAFReg.inf file (in the root STAF directory) and STAF will stop trying to register.

3.3.6.

Explain startup error: Error initializing service, RESPOOL. RC: 4008

The ResPool RC 4008 means "The directory specified by the DIRECTORY parameter when registering the service or the default directory could not be created."

It is likely that STAF was installed as another userid, and you are now trying to use the ResPool as a different userid that doesn't have write access to the STAF directory.

3.3.7.

What should I do if STAF fails to init with Windows Terminal Server?

When using Windows 2000 Terminal Server and Windows XP remote desktop feature with multiple users on a machine, only the user starting the STAF process (STAFproc) can execute STAF commands from the command line. Others users on the machine receive 'Error registering with STAF, RC: 21' when issuing STAF commands.

To resolve this, install STAF as a Windows Service. See the STAF Installation Guide for more information.

3.3.8.

On SLES8, why do I get an error starting STAF: STAFProc: /usr/lib/libstdc++.so.5: version `GLIBCPP_3.2.2' not found (required by STAFProc)

This indicates that you do not have the latest libraries on the SLES8 system. You need to install Service Pack 3 (SP3) to upgrade the system libraries.

3.3.9.

Explain startup error on z/OS: Error binding server socket, bind() RC=1115

This indicates that the socket address is already in use. This error occurs if STAF attempts to bind a socket to an IP address/port that has already been used for an existing socket, or a socket that wasn't closed properly, or one that is still in the process of closing.

You should wait approximately 2-3 minutes for TCP/IP to complete the socket close and retry starting STAF. You can also try typing ps or ps -ea and determine if there are any processes that STAF started which are still running. If there are any, type kill -9 xxx where xxx is the PID for the process.

3.3.10.

Explain startup error: RC: 27, Error initializing service, JSTAF when using a GNU compiler for Java provided with Linux

This error can occur when starting STAFProc if Java STAF services (such as STAX, Event, EventManager, Cron, Email, etc.) are configured in the STAF.cfg file and the version of Java installed on the Linux machine is the GNU compiler for Java. For example, the following version of Java cannot be used when registering STAF Java services:

# java -version
java version "1.4.2"
gij (GNU libgcj) version 4.1.1 20060525 (Red Hat 4.1.1-1)

Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying
conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.

When this version of Java is used to register a STAF Java service, you may get an error like the following:

Error initializing service, STAX, RC: 27, Result: Error
initializing service, JSTAF, Result: Error:
/usr/local/staf/data/STAF/lang/java/shared_jython/2.1-staf-v2/Lib/rfc822.py
(No such file or directory)

Instead, use IBM or Oracle Java when registering a STAF Java service..

3.3.11.

Explain HPUX error "sh: SHLIB_PATH: Parameter not set." when running /usr/local/staf/STAFEnv.sh, or when running it via sourcing .profile)

This is most likely because the .profile has a "set -u" statement in it. This statement turns on the safety restriction against working with undefined variables. On your system, if SHLIB_PATH was not defined, you would get this error when running STAFEnv.sh or when running it via sourcing .profile. If you comment out the "set -u", the error should go away.

3.3.12.

When logged into the desktop on RHEL4-U4, if I run "STAFProc" or "STAF", I get "error while loading shared libraries: libSTAF.so".

This error "error while loading shared libraries: libSTAF.so: cannot open shared object file: No such file or directory" means that the STAF libraries (including libSTAF.so) could not be found. These libraries are usually located in /usr/local/staf/lib, and the environment variable LD_LIBRARY_PATH should include this directory so that the libraries are found. Normally you would either use the STAF InstallAnywhere installer to install STAF, which will automatically update /etc/profile with the required environment variables (including LD_LIBRARY_PATH) or you would manually edit /etc/profile and set the environment variables.

However, as of RHEL4-U4, when logging into the desktop, any references to LD_LIBRARY_PATH in /etc/profile will be ignored. This means that after logging into the RedHat deskop, all of the required STAF environment variables (PATH, CLASSPATH, etc) will be set except for LD_LIBRARY_PATH, which will cause this error. To correct this, after logging in to the desktop, you can source the profile . ./etc/profile or run the STAFEnv script . ./usr/local/staf/STAFEnv.sh.

Note that this problem will only occur when logging in directly to the RHEL4-U4 desktop. If you telnet or ssh to a RHEL4-U4 machine, all the environment variables in /etc/profile (including LD_LIBRARY_PATH) will be correctly set.

3.3.13.

Explain AIX error "Symbol XX__Q2_3std8ios_base is not exported from dependent module /usr/lib/libC.a"

On the AIX 6.1 machine that we use to build STAF, we have the following AIX XL C/C++ Runtime ("lslpp -l xlC.aix*.rte"):

xlC.aix61.rte 11.1.0.0  COMMITTED  XL C/C++ Runtime for AIX 6.1

If you try to run the STAF libraries on an AIX machine with a previous version of the AIX XL C/C++ Runtime, such as:

xlC.aix50.rte 5.0.2.2  COMMITTED  XL C/C++ Runtime for AIX 5.0

You will get errors like:

Could not load program ./STAFProc:
Symbol resolution failed for /usr/local/staf/lib/libSTAF.so because:
         Symbol in__Q2_3std8ios_base (number 126) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol out__Q2_3std8ios_base (number 127) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol adjustfield__Q2_3std8ios_base (number 129) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol left__Q2_3std8ios_base (number 130) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol fixed__Q2_3std8ios_base (number 131) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol showpos__Q2_3std8ios_base (number 132) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol showpoint__Q2_3std8ios_base (number 133) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol floatfield__Q2_3std8ios_base (number 134) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol scientific__Q2_3std8ios_base (number 135) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol internal__Q2_3std8ios_base (number 136) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol uppercase__Q2_3std8ios_base (number 137) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol showbase__Q2_3std8ios_base (number 138) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol basefield__Q2_3std8ios_base (number 139) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol oct__Q2_3std8ios_base (number 140) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol hex__Q2_3std8ios_base (number 141) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol boolalpha__Q2_3std8ios_base (number 142) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol eofbit__Q2_3std8ios_base (number 143) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
           Symbol failbit__Q2_3std8ios_base (number 144) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol skipws__Q2_3std8ios_base (number 145) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol dec__Q2_3std8ios_base (number 146) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol goodbit__Q2_3std8ios_base (number 147) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol badbit__Q2_3std8ios_base (number 148) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol unitbuf__Q2_3std8ios_base (number 149) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol space__Q2_3std10ctype_base (number 150) is not exported  
 from dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol ate__Q2_3std8ios_base (number 151) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol trunc__Q2_3std8ios_base (number 152) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
         Symbol binary__Q2_3std8ios_base (number 153) is not exported from  
dependent
           module /usr/lib/libC.a(ansi_32.o).
Examine .loader section symbols with the 'dump -Tv' command.

To correct the problem, you need to upgrade the machine's xlC.aix61.rte to at least 11.1.0.0.

See this related discussion on Google.

3.3.14.

Explain HPUX IA64 error /usr/lib/hpux32/dld.so: Unsatisfied code symbol '__cxa_get_exception_ptr' in load module './STAFProc'.

This error message indicates that this version of STAF was compiled on a newer OS version that is not compatible with the machine's OS version.

In STAF V3.2.2, the machine used to build STAF for HPUX IA64 was upgraded to OS version 11.31, and so STAF V3.2.2 through V3.3.0 will only run on HPUX IA64 11.31 or later, and if you attempt to run STAF V3.2.2 - V3.3.0 on a machine with an OS version earlier than 11.31, such as HPUX IA64 11.23, you will get this error. In STAF V3.3.1, we changed the HPUX IA64 build machine back to 11.23.

To resolve this problem you need to do one of the following:

  • Use STAF V3.3.1 or later or V3.2.1 or earlier.

  • Upgrade the machine OS version to HPUX IA64 11.31 or later

  • Build a custom version of STAF on your HPUX IA64 11.23 machine (this will require the HP aCC compiler to be installed)

3.3.15.

On Windows x86_64), explain error OS RC 14001: This application has failed to start because the application configuration is incorrect..

On Windows x86_64 (aka AMD64) using STAF V3.3.0 or later, if you get an error like the following when starting STAFProc:

C:\STAF\bin>STAFProc
Error on INTERFACE definition, interface tcp library STAFTCP option Secure=No option Port=6500
Error creating interface, RC: 10, Reason: STAFDynamicLibrary: STAFTCP:
Cannot open library file (aka module/DLL), OS RC 14001: This application has failed
to start because the application configuration is incorrect. Reinstalling the
application may fix this problem.

this indicates that the Microsoft Visual C++ 2005 runtime libraries are not installed on your machine.

In STAF V3.3.0, the STAF TCP interface was updated to provide support for secure connections using OpenSSL and this change requires that the Microsoft Visual C++ 2005 runtime libraries be installed. In STAF V3.3.1, we updated the STAF install to install these libraries for you so you don't have to.

To resolve this problem, if you are using STAF V3.3.0, upgrading to STAF V3.3.1 or later should resolve this problem for you. Or, you can download file vcredist_x64.exe from Microsoft Visual C++ 2005 Redistributable Package (x64) and run it to install the Microsoft Visual C++ 2005 runtime libraries which should resolve the problem.

3.3.16.

Explain Linux error "STAFProc: relocation error: undefined symbol: _ZNSs4_Rep20_S_empty_rep_storageE" when starting STAFProc.

When starting STAFProc on Linux, if you get an error like the following:

STAFProc: relocation error: /usr/local/staf/lib/libSTAF.so: undefined symbol: _ZNSs4_Rep20_S_empty_rep_storageE

The problem is resolved by:

  1. Download the libstdc++.so.6 and libgcc_s.so.1 files used for our STAF Linux IA-32 builds:

    http://staf.sourceforge.net/oslibs/linux-ia32/libstdc++.so.6

    http://staf.sourceforge.net/oslibs/linux-ia32/libgcc_s.so.1

  2. Copy these to /usr/local/staf/lib and start STAFProc.

See the Section 10. Operating System Library Compatability (Linux) section of the STAF Installation Guide for more details.

3.3.17.

Explain Solaris Sparc 64-bit error when starting STAFProc: "/usr/sfw/lib/libstdc++.so.6: wrong ELF class: ELFCLASS32".

When starting STAFProc on Solaris Sparc 64-bit platforms, if you get an error like the following:

/usr/sfw/lib/libstdc++.so.6: wrong ELF class: ELFCLASS32

The solution is to include "/usr/sfw/lib/sparcv9" in LD_LIBRARY_PATH:

LD_LIBRARY_PATH=/usr/sfw/lib/sparcv9:$LD_LIBRARY_PATH
export LD_LIBRARY_PATH
STAFProc &

/usr/sfw/lib/sparcv9 contains the 64-bit Solaris Sparc libraries.

3.3.18.

Explain startup error: Error creating interface. Could not determine logical/physical identifier.

When starting STAFProc, if you get an error like the following:

Error on Interface definition line:

interface ssl library STAFTCP option Secure=Yes option Port=6550

Error code: 47
Reason    : Error creating interface.  STAFConnectionProviderConstruct: Could not determine logical/
physical identifier. Errorcode: 22  Reason: Error getting hostent structure: gethostbyaddr() RC=1

Error in configuration file: /usr/local/staf/bin/STAF.cfg

TCP/IP or DNS is probably not configured correctly which is why the gethostbyaddr API called by STAFProc is not able to determine the host name for the system. To fix this issue, you should make sure that TCP/IP and DNS are configured properly on this system. On Linux, one way that you may be able to resolve this issue is by editing the /etc/hosts file and adding a line to specify the host name for this system's IP address. For example, if your system's IP address is 9.99.100.99 and its host name is linux1.company.com, you could edit the /etc/hosts file and add the following line:

9.99.100.99             linux1.company.com  linux1

3.4. PROCESS Service Questions

3.4.1. Explain RC 10 when attempting to run a process
3.4.2. Explain RC 25 when starting a process on a remote machine
3.4.3. Explain why I'm having a problem interacting with process queues for processes started via the command line
3.4.4. Why are child processes not killed on Windows?
3.4.5. Why can't a STAF process log its output to an AFS directory?
3.4.6. Why do I get a SIGABRT after a STAF process has completed on HP-UX?
3.4.7. Explain error message: "STAFProcessManager::processMonitorThread: Parent could not set child's pgid: 13"
3.4.8. Explain Unix error message: STAFProcessManager::processMonitorThread: Could not start process (execve): 8
3.4.9. When running the ftp executable for Windows via a PROCESS START request, why aren't I getting the remote server responses in stdout?
3.4.10. Why do Expect scripts fail on Linux when STAFProc has been started during system reboot?
3.4.11. Why is different output returned by some commands such as "reg query" when run using a win32 version of STAF on a Windows 64-bit system?
3.4.1.

Explain RC 10 when attempting to run a process

Return code 10 means "Base OS Error", and the additional info provided in STAFResult is the actual error returned by the operating system. One of the most common reasons for getting a Base OS Error is "File Not Found". On Windows systems, OS error code 2 means "The system cannot find the file specified". On Unix systems, OS error code 2 means "No such file or directory".

If you receive an OS error code 2, make sure the executable or script file is in the PATH of the machine where it will be executed., or fully qualify the COMMAND option on the process request (i.e. /opt/tests/mytest).

For Windows systems, you can find more information for OS error codes by typing "net helpmsg <error code>". So, to find more information for OS error code 2 on a Windows 2000 system, type:

net helpmsg 2

For Unix systems, you can find more information for OS error codes from include files named errno.h found in directory /usr/include and its subdirectories.

3.4.2.

Explain RC 25 when starting a process on a remote machine

This error indicates that you have submitted a request from a machine which is not authorized to perform the request. To start a process on a remote machine, a TRUST level of 5 is required.

To resolve the problem:

  • On the remote machine, add a TRUST statement to its STAF.cfg file, give the requesting machine a trust level of 5.
  • Shutdown and restart STAF on the remote machine.

3.4.3.

Explain why I'm having a problem interacting with process queues for processes started via the command line

When you submit a request to STAF from the command line, a unique handle is generated for that request. After the request completes, that handle is no longer active in STAFProc. If you were to submit a subsequent STAF request from the command line which referenced that handle or was dependent upon the continued existence of that handle, your request would fail.

Messages are sent to queues associated with specific handles. So, if you register with STAF, and then someone queues you a message, you can retrieve it off your handle's queue. The STAF command line utility works just like any other STAF application. It registers with STAF, performs a request (which is the service request you specify), and then unregisters. That last step causes the handle to be deleted. Every time you run the STAF command line utility it gets a different handle. When the process you started finishes, it tried to send the message to the queue of a handle that no longer existed. If you were to do a queue list, you would be listing the queue of a completely different handle than the one that submitted the "process start" request.

If you were doing all of this inside a program, then it would have worked like you anticipated. From the command line, you can simulate it by:

  1. Open another window and have it use the delay command to wait for a while. For example:

    STAF local delay delay 300000
    

  2. See what handle the other window is using. For example:

    STAF local handle query all
    

    It should be the lowest numbered handle called "STAF/Client".

  3. Start the process and specify the specific handle to queue the message to. For example:

    STAF local process start command clock notify onend handle handle_from_step_2
    

  4. Stop the process, as you did previously.

  5. Check the other window's queue, For example:

    STAF local queue list handle handle_from_step_2
    

    Note, when the delay request finishes (after 5 minutes in this case), the handle and it's queue will disappear.

3.4.4.

Why are child processes not killed on Windows?

If you terminate a STAX job (or send a Process Stop request to a running STAF process) on Windows, any child processes that the process has created will not be terminated. This is a limitation on Windows platforms. To resolve this problem you can specify the option: STOPUSING WM_CLOSE on the PROCESS START request, or specify the <stopusing>'WM_CLOSE'</stopusing> element for a STAX <process> element.

3.4.5.

Why can't a STAF process log its output to an AFS directory?

When attempting to start a Process on a remote machine so that the output can be logged to an AFS directory, STAFProc needs to be started in an authenticated "session" in order to be able to store the log files in AFS-space.

3.4.6.

Why do I get a SIGABRT after a STAF process has completed on HP-UX?

If you see the following error on an HP-UX machine after a STAF process has completed:

Received signal 6 (SIGABRT)
/usr/lib/dld.sl: Call to __sigenable() failed
/usr/lib/dld.sl: Not owner
Received signal 6 (SIGABRT)
/usr/lib/dld.sl: Unresolved symbol: __h_errno__Fv (code)  from
/usr/local/staf/l
ib/libSTAF.sl
Received signal 6 (SIGABRT)
/usr/lib/dld.sl: Call to __sigenable() failed
/usr/lib/dld.sl: Not owner
Received signal 6 (SIGABRT)
/usr/lib/dld.sl: Unresolved symbol: __h_errno__Fv (code)  from
/usr/local/staf/l

This is likely due to an incorrect hostname. Verify that the DNS is setup correctly an all machines (Refer to "Why can't my STAF machines communicate?").

3.4.7.

Explain error message: "STAFProcessManager::processMonitorThread: Parent could not set child's pgid: 13"

Periodically on Unix systems, you may see this error message. You can ignore these messages (you should not encounter any problems because of the messages).

3.4.8.

Explain Unix error message: STAFProcessManager::processMonitorThread: Could not start process (execve): 8

If you get this error message when trying to start a process on a Unix system, the 8 in the error message is the errno that is being set by the operating system. For example, an errno of 8 on a Solaris 5.7 system, according to the /usr/include/sys/errno.h file, means "Exec format error". This indicates that there is a problem with the executable you specified in the process start command. If you specified a shell script, check to see if it is missing #! on the first line. Check if you can execute the same command (and parameters, if specified) without involving STAF.

3.4.9.

When running the ftp executable for Windows via a PROCESS START request, why aren't I getting the remote server responses in stdout?

When using the PROCESS service to run command "ftp -s:C:/temp/stdin.txt" on a Windows machine, where C:/temp/stdin.txt is a text file that contains the FTP commands to run after FTP starts, if you don't specify the SAMECONSOLE option (e.g. if you use the NEWCONSOLE option which is the default),, the remote server responses are not written to stdout. However, if you can specify the -v option for the ftp executable when using new console, then the remote server response are written to stdout. For example: "ftp -v -s:C:/temp/stdin.txt". When you specify the SAMECONSOLE option, the remote server responses are written to stdout when you don't use the -v option for the ftp executable.

For example, say file C:\temp\stdin.txt contains the following content to log on to remote ftp server machine staf1e and and put a file on the remote ftp server:

open staf1e
root
mypassword
binary
cd sharon
put copyme.txt
bye

Here are the results when using the PROCESS service to run the ftp executable when using various options:

1) When using new console (the default) and not using the -v option for the ftp executable, you see that the remote server responses are not written to stdout:

C:\>STAF local PROCESS START COMMAND "ftp -s:C:/temp/stdin.txt" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : User (staf1e.austin.ibm.com:(none)): open staf1e



binary
cd sharon
put copyme.txt
bye

    }
  ]
}

2) When using new console (the default) and the -v option for the ftp executable, you see that the remote server responses are written to stdout:

C:\>STAF local PROCESS START COMMAND "ftp -v -s:C:/temp/stdin.txt" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : Connected to staf1e.austin.ibm.com.
open staf1e
220 (vsFTPd 2.0.1)
User (staf1e.austin.ibm.com:(none)):
331 Please specify the password.

230 Login successful.

binary
200 Switching to Binary mode.
cd sharon
250 Directory successfully changed.
put copyme.txt
200 PORT command successful. Consider using PASV.
150 Ok to send data.
226 File receive OK.
ftp: 24 bytes sent in 0.00Seconds 24000.00Kbytes/sec.
bye
221 Goodbye.

    }
  ]
}

3) When using the SAMECONSOLE option and not using the -v option for the ftp executable, you see that the remote server responses are written to stdout:

C:\>STAF local PROCESS START COMMAND "ftp -s:C:/temp/stdin.txt" RETURNSTDOUT STDERRTOSTDOUT WAIT SAMECONSOLE
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : ftp> Connected to staf1e.austin.ibm.com.
open staf1e
220 (vsFTPd 2.0.1)
User (staf1e.austin.ibm.com:(none)):
331 Please specify the password.

230 Login successful.
ftp> ftp>
binary
200 Switching to Binary mode.
ftp> cd sharon
250 Directory successfully changed.
ftp> put copyme.txt
200 PORT command successful. Consider using PASV.
150 Ok to send data.
226 File receive OK.
ftp: 24 bytes sent in 0.00Seconds 24000.00Kbytes/sec.
ftp> bye
221 Goodbye.

    }
  ]
}

3.4.10.

Why do Expect scripts fail on Linux when STAFProc has been started during system reboot?

When executing Expect scripts on a Linux system where STAFProc has been started during the system reboot, the scripts may fail to perform the expected interactive steps. Here is an example Expect script:

package require Expect
spawn scp root@abc.company.com:/root/test/xyz.err /tmp/myxyz.err
expect "root@abc.company.com's password:"
send "**********\n"
interact

This script will copy a remote file to the system where the script is executing. Here is an example of running the script via STAF (where STAFProc has been started after the system boots):

# STAF <machine> PROCESS START SHELL COMMAND "/opt/ActiveTcl-8.5/bin/tclsh8.5 /home/expect.tcl" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : spawn scp root@abc.company.com:/root/test/xyz.err /tmp/
myxyz.err
root@abc.company.com's password:
myxyz.err                                       100% 5085     5.0KB/s   00:00

    }
  ]
}

Notice that the standard output includes the information about the copied file (myxyz.err 100% 5085 5.0KB/s 00:00) and the /tmp/myxyz.err file exists.

However, if you configure the system to start STAFProc automatically during reboot, using something like:

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

After the system reboots, here is an example of running the script via STAF:

# STAF <machine> PROCESS START SHELL COMMAND "/opt/ActiveTcl-8.5/bin/tclsh8.5 /home/expect.tcl" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : <None>
  Files      : [
    {
      Return Code: 0
      Data       : spawn scp root@abc.company.com:/root/test/xyz.err /tmp/
myxyz.err
root@abc.company.com's password:

    }
  ]
}

Notice that the standard output does not include the information about the copied file, and the /tmp/myxyz.err file does not exist.

The root cause of the problem is that STAFProc is being started in the background (using &) when the system is rebooted; in this scenario the Expect scripts will fail. Note that if you start STAFProc in the background (using &) after the system has booted, the Expect scripts will run successfully.

There are two workarounds for the problem:

  • Start STAFProc after the system has rebooted.
  • Start STAFProc in the foreground during the system boot (i.e. remove the & when starting STAFProc). WARNING -- use caution when using this workaound, as it may cause your operating system to hang during the boot.
    • On SLES10, this workaround has been successful when the /etc/sysconfig/boot has RUN_PARALLEL=yes (so that services, including STAF, will start in parallel). So, even though the script that starts STAFProc will hang, this will not cause the system boot to hang.

3.4.11.

Why is different output returned by some commands such as "reg query" when run using a win32 version of STAF on a Windows 64-bit system?

When running a win32 version of STAF on a Windows 64-bit system, the output returned from some commands such as "reg query" when run via a STAF PROCESS START request may be different than when running the command via a command prompt. For example, when running a "reg query HKLM\Software" command via an "Administrator: C:\Windows\System\cmd.exe" command prompt, the result could be:

C:\>reg query HKLM\Software

HKEY_LOCAL_MACHINE\Software\Classes
HKEY_LOCAL_MACHINE\Software\Clients
HKEY_LOCAL_MACHINE\Software\JavaSoft
HKEY_LOCAL_MACHINE\Software\Lotus
HKEY_LOCAL_MACHINE\Software\Microsoft
HKEY_LOCAL_MACHINE\Software\MozillaPlugins
HKEY_LOCAL_MACHINE\Software\ODBC
HKEY_LOCAL_MACHINE\Software\Policies
HKEY_LOCAL_MACHINE\Software\RegisteredApplications
HKEY_LOCAL_MACHINE\Software\Symantec
HKEY_LOCAL_MACHINE\Software\Wow6432Node

C:\>

But, when the same "reg query HKLM\Software" command is run via a STAF PROCESS START request, the result could be different:

C:\>STAF local PROCESS START SHELL COMMAND "reg query HKLM\Software" RETURNSTDOUT STDERRTOSTDOUT WAIT
Response
--------
{
  Return Code: 0
  Key        : &lt;None>
  Files      : [
    {
      Return Code: 0
      Data       :
HKEY_LOCAL_MACHINE\Software\Microsoft
HKEY_LOCAL_MACHINE\Software\Mozilla
HKEY_LOCAL_MACHINE\Software\MozillaPlugins
HKEY_LOCAL_MACHINE\Software\ODBC
HKEY_LOCAL_MACHINE\Software\SNIA
HKEY_LOCAL_MACHINE\Software\Symantec
HKEY_LOCAL_MACHINE\Software\Classes
HKEY_LOCAL_MACHINE\Software\Clients
HKEY_LOCAL_MACHINE\Software\Policies
HKEY_LOCAL_MACHINE\Software\RegisteredApplications

    }
  ]
}

This is because a 32-bit version of STAF (or any 32-bit application) can only run processes in 32-bit mode (SysWOW64). Additionally, a 32-bit application cannot retrieve file information about any files in the System32 folder or in the subfolders of the System32 folder. So running the command via STAF PROCESS START request, you get the same result as if you ran the command via an "Administrator: C:\Windows\SysWOW64\cmd.exe" command prompt.

If you want to get the same output as when running the command via an "Administrator: C:\Windows\System32\cmd.exe" command prompt, you could do one of the following:

  • Use C:\Windows\Sysnative in the PATH to run the command instead of using C:\Windows\System32. You can do this by using the ENV option on your PROCESS START request to include C:\Windows\Sysnative at the beginning of the PATH environment variable. Note that you can specify STAF variable {STAF/Env/SystemRoot} instead of hardcoding C:\Windows in case you may have Windows installed on a drive other than C:. For example:
    C:\>STAF local PROCESS START SHELL COMMAND "reg query HKLM\Software" ENV "PATH={STAF/Env/SystemRoot}\Sysnative;{STAF/Env/PATH}" RETURNSTDOUT STDERRTOSTDOUT WAIT
    Response
    --------
    {
      Return Code: 0
      Key        : &lt;None>
      Files      : [
        {
          Return Code: 0
          Data       :
    HKEY_LOCAL_MACHINE\Software\Classes
    HKEY_LOCAL_MACHINE\Software\Clients
    HKEY_LOCAL_MACHINE\Software\JavaSoft
    HKEY_LOCAL_MACHINE\Software\Lotus
    HKEY_LOCAL_MACHINE\Software\Microsoft
    HKEY_LOCAL_MACHINE\Software\MozillaPlugins
    HKEY_LOCAL_MACHINE\Software\ODBC
    HKEY_LOCAL_MACHINE\Software\Policies
    HKEY_LOCAL_MACHINE\Software\RegisteredApplications
    HKEY_LOCAL_MACHINE\Software\Symantec
    HKEY_LOCAL_MACHINE\Software\Wow6432Node
    
        }
      ]
    }
    
    
    Or you could change the PATH environment variable in the environment in which STAFProc is run to include C:\Windows\Sysnative before C:\Windows\System32. Note that this would then effect all commands run via a PROCESS START request which may or may not be what you want.

    For more information on using C:\Windows\Sysnative, see "Batch Script Question - REG QUERY results" at Batch Script Question - REG QUERY results.

  • Install a 64-bit version of STAF for Windows (e.g. winamd64) instead of using a win32 version of STAF on your 64-bit Windows operating system. Note that there could be other factors that influence whether or not you decide to install a 64-bit version of STAF (e.g. if you need to use a 32-bit version of Java instead of a 64-bit version of Java to run STAF Java services).

3.5. FS Service Questions

3.5.1. Why does COPY FILE request fail when no TOMACHINE is specified?
3.5.2. Why are my text files copied via the FS service not converted correctly between Windows and Unix?
3.5.3. Why can't I copy a file that is larger then 4GB?
3.5.4. Why does FS LIST COPYREQUESTS show a copy request in progress on the destination machine that has already failed with a RC 22?
3.5.1.

Why does COPY FILE request fail when no TOMACHINE is specified?

From machine m1 this command fails:

C:\>STAF m2 FS COPY FILE c:/staf/data/log/global/temp.log TOFILE c:/staf/data/log/global/archivetemp.log
Error submitting request, RC: 17
Additional info: c:/staf/data/log/global/archivetemp.log

From machine m1 this command works:

C:\>STAF m2 FS COPY FILE c:/staf/data/log/global/temp.log TOFILE c:/staf/data/log/global/archivetemp.log TOMACHINE m2

This is working as expected/designed. The default for the TOMACHINE option is the system that originated the request. So, if m1 does not actually have a c:/staf/data/log/global directory, then STAF will not be able to create the archivetemp.log directory. Once you add TOMACHINE m2, it is obvious you were trying to copy a file "locally" on the remote system, which does require the use of the TOMACHINE option.

3.5.2.

Why are my text files copied via the FS service not converted correctly between Windows and Unix?

Beginning with STAF 2.5.0 and later, you can use a TEXT option on a FS COPY FILE or GET FILE request (or TEXTEXT options on a FS COPY DIRECTORY request) to convert line-endings between Windows and Unix and to convert between codepages if necessary. See the "File System (FS) Service" section of the STAF User's Guide for more information.

3.5.3.

Why can't I copy a file that is larger then 4GB?

The STAF FS Service does not currently support copying files that are >= 4GB (4,294,967,296 bytes), even on 64-bit machines. Feature Request #438 has been opened to add support to the FS service for copying files that are >= 4GB. There is no planned implementation date at this time. .

3.5.4.

Why does FS LIST COPYREQUESTS show a copy request in progress on the destination machine that has already failed with a RC 22?

If a FS COPY request fails due to a network problem such as with RC: 22 and Result: "STAFConnectionWrite: Error writing to socket: send() RC=10054: 22", it's possible that half of the connection on the destination ("TO") machine side didn't get closed. So, it still shows up in the FS LIST COPYREQUESTS LONG request on the destination machine (even though the copy request is no longer running) and it causes RC 19 if you resubmit this FS COPY request.

This occurs because the network connection on the FS COPY destination machine may not be notified if the other side of the network connection ended unless keepalive is enabled and the KeepAliveTime has expired. Note that on Windows, keepalive is not enabled on a Windows socket by default. Keep Alive refers to the time before TCP will begin sending keepalive messages, but only if keepalive is enabled for a network connection. The default is usually around 2 hours. KeepAliveInterval is the time between retransmissions of keepalives once a KeepAliveTime has expired.

To improve this problem:

  1. Install STAF V3.2.0 or later as a bug fix was made in it that helps with this problem by enabling the TCP keepalive option for client sockets in the STAF TCP connection provider.

  2. Also, you may want to decrease the TCP KeepAliveTime parameter from 2 hours to around 30 minutes. The following webpages contain information for tuning Windows TCP/IP:

4. Debugging STAX

4.1. General Questions
4.1.1. Where can I find more information about Python?
4.1.2. Why is STAX still showing a process as running, even though it has completed?
4.1.3. Why am I getting RC=10 and STAFResult=8 when starting a Java process in a STAX job?
4.1.4. Why does my eMail Service's SEND request resulting in RC 7 when quotes or double quotes are in the message?
4.1.5. Why am I getting a java.lang.NullPointerException at org.python.core.ThreadState.entrRepr in my JVMLog.1 file?
4.1.6. Why aren't changes to imported Python modules picked up in my STAX job?
4.1.7. Explain "RC 21 submitting a STAX EXECUTE request"
4.1.8. Why is the STAX JVM crashing with a java.lang.OutOfMemoryError logged in the STAX JVM log?
4.1.9. Why is the STAX JVM's maximum heap size limited to ~2G on a 32-bit system?
4.2. STAX <import> Questions
4.2.1. Why aren't the global <script> elements in the imported XML file executed when importing a STAX function from that file?
4.2.2. Are there any conflict or efficiency concerns when doing nested file imports in a STAX job?
4.3. STAX Monitor Questions
4.3.1. What does RC 2 mean when starting the STAX Job Monitor?
4.3.2. What does RC 16 mean when starting the STAX Job Monitor?
4.3.3. What does RC 2 mean when submitting a new job via the STAX Job Monitor?
4.3.4. What does RC 16 mean when submitting a new job via the STAX Job Monitor?
4.3.5. Why I'm I getting a java.util.zip.ZipException running "java -jar STAXMon.jar"?
4.3.6. Why doesn't the STAX Job Monitor window have a close confirmation?

4.1. General Questions

4.1.1. Where can I find more information about Python?
4.1.2. Why is STAX still showing a process as running, even though it has completed?
4.1.3. Why am I getting RC=10 and STAFResult=8 when starting a Java process in a STAX job?
4.1.4. Why does my eMail Service's SEND request resulting in RC 7 when quotes or double quotes are in the message?
4.1.5. Why am I getting a java.lang.NullPointerException at org.python.core.ThreadState.entrRepr in my JVMLog.1 file?
4.1.6. Why aren't changes to imported Python modules picked up in my STAX job?
4.1.7. Explain "RC 21 submitting a STAX EXECUTE request"
4.1.8. Why is the STAX JVM crashing with a java.lang.OutOfMemoryError logged in the STAX JVM log?
4.1.9. Why is the STAX JVM's maximum heap size limited to ~2G on a 32-bit system?
4.1.1.

Where can I find more information about Python?

4.1.2.

Why is STAX still showing a process as running, even though it has completed?

If you are running a STAX Job, and it shows that a process is still running, even though the process has actually completed, this is likely a DNS problem with either the STAX service machine or the machine where the process was executed (where the machine that executed the process is unable to find the STAX service machine in order to deliver the process completion message).

Refer to "Why can't my STAF machines communicate?" to resolve this problem.

4.1.3.

Why am I getting RC=10 and STAFResult=8 when starting a Java process in a STAX job?

Certain Unix Java versions will contain a /bin/java file that is actually a soft link to a wrapper shell script file, rather than a binary executable file. If you try to start a Java process in a STAX job:

<process>
  <location>machName</location>
  <command>'java'</command>
  <parms>'TestA'</parms>
</process>

the result will be RC=10 and STAFResult=8. The Operating System return code 8 indicates "Exec format error". To resolve this problem, specify the 'shell' attribute:

<process>
  <location>machName</location>
  <command mode="'shell'">'java'</command>
  <parms>'TestA'</parms>
</process>

4.1.4.

Why does my eMail Service's SEND request resulting in RC 7 when quotes or double quotes are in the message?

If the message request has embedded quotes or double quotes, it may cause the STAF command parsing to fail (resulting in the RC 7). Here is a portion of a STAX job that shows how to get this working:

<script>
  from com.ibm.staf import STAFUtil
  emailmessage = STAFUtil.wrapData(emailmessage)
</script>

<stafcmd>
  <location>'local'</location>
  <service>'email'</service>
  <request>'send to user@us.ibm.com message %s' %(emailmessage)</request>
</stafcmd>

<if expr="RC !=0">
  <message>'RC: %s result: %s' % (RC, STAFResult)</message>
</if>

4.1.5.

Why am I getting a java.lang.NullPointerException at org.python.core.ThreadState.entrRepr in my JVMLog.1 file?

The following NullPointerException at org.python.core.ThreadState.enterRepr(ThreadState.java) is a known problem in IBM Java's JIT:

******************************************************************************
*** 20030911-12:50:41 - Start of Log for JVMName: STAFJVM1
*** JVM Executable: java
*** JVM Options   : -Xms128m -Xmx512m
******************************************************************************
java.lang.NullPointerException
    at org.python.core.ThreadState.enterRepr(ThreadState.java(Compiled Code))
    at org.python.core.PyList.toString(PyList.java(Compiled Code))
    at org.python.core.PyObject.__repr__(PyObject.java(Compiled Code))
    at org.python.core.PyObject.__str__(PyObject.java(Compiled Code))
    at com.ibm.staf.service.stax.STAXThread.pyStringEval(STAXThread.java(Compiled Code))
    at com.ibm.staf.service.stax.STAXMessageAction.execute(STAXMessageAction.java(Compiled Code))
    at com.ibm.staf.service.stax.STAXThread.execute(STAXThread.java(Compiled Code))
    at com.ibm.staf.service.stax.STAXThreadQueue$QueueThread.run(STAXThreadQueue.java:66)

If you see this NullPointerException in your JVMLog.1 file when debugging a problem running a STAX job, verify that the JVM that STAX is using is IBM's java by doing:

  java -version

This problem is in the JIT in IBM Java versions 1.3.x, 1.4.0, and 1.4.1 and has been seen on both Windows and Unix systems. This problem has been reported to IBM Java support and is under investigation. When this NullPointerException occurs in the JVM, any services using this JVM can no longer function until the services using this JVM are removed and re-added via the SERVICE service or STAFProc is shutdown and restarted.

There are two workarounds:

  1. Disable the JIT (which will degrade performance):

    To turn the JIT off for the JVM that the STAX service is using, configure the STAX service using a J2 OPTION to set the java.compiler property to NONE. For example:

    SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\services\stax\STAX.jar \
                 OPTION JVMName=STAX OPTION J2=-Xmx256m \
                 OPTION J2=-Djava.compiler=NONE

  2. Use another version of Java (e.g. Oracle Java) instead of IBM Java:

    To specify another version of Java for the STAX service to use, configure the STAX service using the JVM OPTION to set the Java executable. For example, if you install Oracle Java 7.0 in C:\jdk7.0, then configure STAX as follows to specify to use the java executable in the C:\jdk7.0\bin directory:

    SERVICE STAX LIBRARY JSTAF EXECUTE C:\STAF\services\services\stax\STAX.jar \
                 OPTION JVM=C:\jdk7.0\bin\java \
                 OPTION JVMName=STAX OPTION J2=-Xmx512m

4.1.6.

Why aren't changes to imported Python modules picked up in my STAX job?

Use the built-in Python "reload" function if you want to pick up changes made to imported Python modules without having to unregister and register the STAX service (either by stopping STAF and restarting it or by using the SERVICE service to dynamically delete and add the STAX service). Note that there is a "gotcha" in that reload may not impact "from" imports. Reloading allows you to test Python module changes immediately after reloads, without having to unregister the STAX service. Here's more detailed information about using the built-in Python "reload" function.

One of the most common questions Python beginners seem to ask when using modules is: why won't my imports keep working? The first import works fine, but later imports in STAX jobs seem to have no effect. They're not supposed to, and here's why:

  • Modules are loaded and run on the first import or from
  • Running a module's code creates its top-level names.
  • Later import and from operations fetch an already loaded module.

Python loads, compiles, and runs code in a module file only on the first import, on purpose; since this is an expensive operation. So, even across STAX jobs, a Python module's code is run only once per STAX service by default. But, sometimes you really want a module's code to be rerun.

To force a module's code to be reloaded and rerun, you need to ask Python explicitly to do so, by calling the reload built-in function. Using reload can make your STAX jobs more dynamic. In a nutshell:

  • Imports load and run a module's code only the first time.
  • Later imports use the already loaded module object without rerunning code.
  • The reload function forces an already loaded module's code to be reloaded and rerun.

Unlike import and from:

  • reload is a built-in function in Python, not a statement.
  • reload is passed an existing module object, not a name.

Because reload expects an object, a module must have been previously imported successfully before you can reload it. Reloading looks like this:

  import module     # initial import
  #  Use module.attributes
  ...               # now, go change the module file
  ...
  reload(module)    # get updated exports
  # Use module.attributes

You typically import a module, then change its source code in a text editor and reload. When you call reload, Python rereads the module file's source code and reruns its top-level statements and changes a module object in-place, so every reference to a module object is automatically effected by a reload.

Note that there is an important "gotcha" in that reload may not impact fromimports. In fact, the from statement is the source of all sorts of gotchas in Python. Because from copies (assigns) names when run, there's no link back to the module where the names came from. Names imported with from simply become references to objects, which happen to have been referenced by the same names in the importee when the from ran. Because of this behavior, reloading the importee has no effect on clients that use from; the client's names still reference the objects fetched with from, even though names in the original module have been reset. For example:

  from module import X     # X may not reflect any module reloads!
  ...
  reload(module)           # changes module, not my names
  X                        # still references old object

The solution to this is: Don't do it that way. To make reloads more effective, use import and name qualification, instead of from. Because qualifications always go back to the module, they will find the new bindings of module names after calling reload:

  import module            # get module, not names
  ...
  reload(module)           # changes module in-place
  module.X                 # get current X; reflects module reloads

So, let's say you have a Python file, changer.py, in directory /usr/mypyfuns that contains a function called getValue. For example, say changer.py looks like:

  value = 'First value'

  def getValue():
      return value

Here's an example of a STAX job that tests reloading function getValue from module changer in /usr/mypyfuns. If you run this job, even after editing changer.py so that value is assigned some other value, you'll get the updated value.

Example 14.  Reloading imported function getValue from module changer in /usr/mypyfuns

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<!--  Test reloading Python modules  -->

<stax>

  <defaultcall function="TestReload"/>;

  <script>
    myPythonDir = '/usr/mypyfuns'

    import sys
    pythonpath = sys.path

    # Append myPythonDir to sys.path if not already present
    if myPythonDir not in pythonpath:
      sys.path.append(myPythonDir)

    # Import
    import changer

    # Force new code to load/run
    reload(changer)
  </script>

  <function name="TestReload">
    <message>'changer.getValue()=%s' % changer.getValue()</message>
  </function>

</stax>

See Python documentation for more information about module reloads.

4.1.7.

Explain "RC 21 submitting a STAX EXECUTE request"

You can get this error if your system has exceeded the maximum number of files that can be open. Check your JVM log and see if you have lots of the following error logged:

Error accepting on server socket, socket RC: 24

Check your STAX jobs and see if they use Jython's open() function to open a file in a <script> element but aren't using Jython's close() function to close the file. If the file is opened within a loop construct (or if the function this code is in is called many times or the STAX job is run many times), many files could be left open, even after the STAX job(s) complete. Unlike Python, Jython requires that you explicitly close files (otherwise they could be left open for a long, long time until they are garbage collected).

You can run command lsof -p <STAX JVM PID> to see the names of the files that were opened by the STAX service and STAX jobs (which can help you determine which STAX job(s) are leaving files open).

Refer to Explain "Error accepting on server socket, socket RC: 24" for more information on how to debug this problem by finding out what files are open.

4.1.8.

Why is the STAX JVM crashing with a java.lang.OutOfMemoryError logged in the STAX JVM log?

If the STAX JVM crashes and the STAX JVM log contains error java.lang.OutOfMemoryError: Java heap space, try tuning the JVM by increasing the maximum heap size used by the JVM be specifying JVM option -Xmx<Size> when registering the STAX service. For example, to increase the maximum heap size to 1024m, register the STAX service as follows in the STAF.cfg file:

SERVICE STAX LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/stax/STAX.jar \
             OPTION JVMName=STAX OPTION J2=-Xmx1024m

If the STAX JVM crashes and the STAX JVM log contains an error like java.lang.OutOfMemoryError: PermGen space or java.lang.OutOfMemoryError: requested <size> bytes for <reason>. Out of swap space? in the STAX JVM log, try tuning the JVM by increasing the maximum size (and possibly the initial size) of the permanent generation space used by the JVM. The permanent generation is the area of the heap where class and method objects are stored. If an application loads a very large number of classes, then the maximum size of the permanent generation space might need to be increased using the -XX:MaxPermSize JVM option when registering the STAX service. You may also want to increase the initial size of the permanent generation space by using the -XX:PermSize JVM option. For example, to increase the maximum and initial sizes of the permanent generation space to 256m (and to increase the maximum heap size to 1024m), register the STAX service as follows in the STAF.cfg file:

SERVICE STAX LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/stax/STAX.jar \
             OPTION JVMName=STAX \
             OPTION "J2=-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=256m"

Also, if the STAX JVM log contains following memory allocation error, try increasing the maximum heap space and/or the permanent generation size for the JVM as described above to resolve the problem.

terminate called after throwing an instance of 'std::bad_alloc'
  what():  std::bad_alloc

For more information on tuning memory when using Oracle Java 1.6 see Chapter 3: Troubleshooting Memory Leaks in the Troubleshooting Guide for Java SE 6 with HotSpot VM.

4.1.9.

Why is the STAX JVM's maximum heap size limited to ~2G on a 32-bit system?

On a 32-bit system with lots of memory (e.g. 8G), if registering a STAF Java service like STAX fails when specifying a maximum heap size of ~2G of more (e.g. OPTION J2=-Xmx2560m) with an error like the following:

JVMJ9VM015W Initialization error for library j9gc24(2): Failed to instantiate heap; 2560M requested
Could not create the Java virtual machine.

you've probably run into a limitation using a 32-bit JVM because on most operating systems running on a 32-bit architecture, processes (including the Java heap) are limited to less than 2GB total memory.

For more information on Java heap size limitations when using a 32-bit JVM, see question Why can't I get a larger heap with the 32-bit JVM? in the Oracle Java FAQ. which says, "If your application requires a very large heap you should use a 64-bit VM on a version of the operating system that supports 64-bit applications". Some reasons behind the ~2GB limitation on Linux 32-bit systems are talked about in discussion thread How to avoid 2GB memory limit of JVM in Linux. Also see forum thread Java Heap Size at the JavaRanch Java Forum which says:

"In most Operating Systems running on a 32-bit architecture, processes are limited to less than 2GB total memory. This includes the Java heap, the process' heap and stack, the memory used by JNI (if any), the thread stacks and other internal structures.

On a Sun Fire V440 w/ Solaris 9 and HotSpot JRE 5.0 the 32-bit heap limit is 4.3 GB.

In Linux (e.g. RHEL 4.0 and later) you can run a hugepage kernel and JRockIt which gives a max 32-bit heap size of 2.7GB.

On MS Windows you can try something like /3GB or /PAE with JRockIt, but due to the fact that the heap needs to be in consecutive memory, you'll end up with a heap size of less than 2GB."

4.2. STAX <import> Questions

4.2.1. Why aren't the global <script> elements in the imported XML file executed when importing a STAX function from that file?
4.2.2. Are there any conflict or efficiency concerns when doing nested file imports in a STAX job?
4.2.1.

Why aren't the global <script> elements in the imported XML file executed when importing a STAX function from that file?

Global <script> elements defined in an XML file containing only functions intended to be imported by the <import> element, are not recognized in the body of the functions. In the imported xml file, only the <script> elements contained within the imported <function> will be executed.

Just to give a little history, in the early stages of STAX's life, <function>s were not allowed to take arguments (and the <import> element didn't exist either). Any data that you wanted to "pass into" a function had to be previously set in existing variables. To that end, it was necessary to allow <script> elements at the root of the document so that default values could be fed into the functions. However, once we added argument passing to <function>s, we began encouraging that over global <script>s. Nevertheless, we couldn't remove support for global <script>s, as many groups were already using them.

When we implemented the <import> element, we felt it would be cleaner to just import the <function>s in the job, as there was less interaction with the pieces of the importing job. For example, what you already had a variable that was overwritten by a <script> in another file, just because you imported a single utility <function> from it. Even if you were expecting a certain variable to be set from the job, you would have to be very careful to import the functions in the job first, and then set the variables, otherwise your values would overwritten. This same line of argument also applies to importing <signalhandler>s.

4.2.2.

Are there any conflict or efficiency concerns when doing nested file imports in a STAX job?

Question: If I have a situation where file A imports files B and C, and files B and C both import file D is that going to cause any sort of conflict when a call is made to a function in file D?

Answer: No.

Question: If file A imports file B and file B imports file C, does file C get re-imported every time the function in file B is called? If so is there any potential conflict there, and how much will this impact overall efficiency?

Answer: No, functions in file C do not get re-imported every time the function in file B is called. However, we should point out that file C will, in fact, be re-imported every time. Now, none of the functions in it will get imported, but the file will be retrieved and parsed each time you try to import something from it. Depending on how big this file is, and how often you are calling the function which imports it, you might either set a STAF variable (with the job number somewhere in it) that you can retrieve across function calls, or have the importing function use "global" scope and set a STAX variable that indicates the import has already been done.

You can see this for yourself if you'd like by looking at STAXResult after each <import> element. In the STAX User's Guide, in the section that describes the <import> element, it says:

After executing an import element, STAXResult will be set to a list containing:

STAXResult[0]
Either None or a list containing a STAXImportError object and a text string with details about the error.
STAXResult[1]
A list of the successfully imported functions that were requested to be imported.
STAXResult[2]
A list of the successfully imported functions that were required by other functions.
STAXResult[3]
A list of the functions that were requested to be imported but already existed (so they were not imported).
STAXResult[4]
A list of the functions that were required by other functions but already existed (so they were not imported).
STAXResult[5]
A list of the functions that were not requested to be imported and were not required by other functions.
STAXResult[6]
A list of functions requested to be imported that were not found.

Here are some STAX jobs that demonstrate this:

Example 15. D:/dev/src/stax/A.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <defaultcall function="FunctionA"/>

  <script>
    machName = 'lucas'
  </script>

  <function name="FunctionA">
    <sequence>

      <message>'Running FunctionA'</message>

      <import machine="machName" file="'D:/dev/src/stax/B.xml'" mode="'error'"/>

      <message>
        'After import B.xml:\n%s\n%s\n%s\n%s\n%s\n%s\n%s' % \
        (STAXResult[0], STAXResult[1], STAXResult[2], STAXResult[3],
         STAXResult[4], STAXResult[5], STAXResult[6])
      </message>

      <call function="'FunctionB'"/>
      <call function="'FunctionB'"/>
      <call function="'FunctionB'"/>

    </sequence>
  </function>

</stax>

Example 16. D:/dev/src/stax/B.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">

<stax>

  <function name="FunctionB">
    <sequence>

      <message>'Running FunctionB'&lt;/message>

      <import machine="machName" file="'D:/dev/src/stax/C.xml'" mode="'error'"/>

      <message>
        'After import C.xml:\n%s\n%s\n%s\n%s\n%s\n%s\n%s' % \
        (STAXResult[0], STAXResult[1], STAXResult[2], STAXResult[3],
         STAXResult[4], STAXResult[5], STAXResult[6])
      </message>

    </sequence>
  </function>

</stax>

Example 17. D:/dev/src/stax/C.xml

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE stax SYSTEM "stax.dtd">
<stax>

  <function name="FunctionC">
    <sequence>

      <message>'Running FunctionC'</message>

    </sequence>
  </function>

</stax>

Here are the results that were logged. As you can see, the second and third time that FunctionB was called, the STAXResult after importing C.xml in FunctionB shows 'FunctionC' showing up in STAXResult[3] instead of STAXResult[1].

STAXResult[1] is a list of the successfully imported functions that were requested to be imported.
STAXResult[3]: A list of the functions that were requested to be imported but already existed (so they were not imported).
C:\>staf local log query machine lucas logname STAX_Job_11_User
Response
--------
20030319-18:52:10|lucas|189|STAX/Job/11|Info|Running FunctionA
20030319-18:52:11|lucas|189|STAX/Job/11|Info|After import B.xml:
None
['FunctionB']
[]
[]
[]
[]
[]
20030319-18:52:11|lucas|189|STAX/Job/11|Info|Running FunctionB
20030319-18:52:11|lucas|189|STAX/Job/11|Info|After import C.xml:
None
['FunctionC']
[]
[]
[]
[]
[]
20030319-18:52:11|lucas|189|STAX/Job/11|Info|Running FunctionB
20030319-18:52:11|lucas|189|STAX/Job/11|Info|After import C.xml:
None
[]
[]
['FunctionC']
[]
[]
[]
20030319-18:52:11|lucas|189|STAX/Job/11|Info|Running FunctionB
20030319-18:52:11|lucas|189|STAX/Job/11|Info|After import C.xml:
None
[]
[]
['FunctionC']
[]
[]
[]

4.3. STAX Monitor Questions

4.3.1. What does RC 2 mean when starting the STAX Job Monitor?
4.3.2. What does RC 16 mean when starting the STAX Job Monitor?
4.3.3. What does RC 2 mean when submitting a new job via the STAX Job Monitor?
4.3.4. What does RC 16 mean when submitting a new job via the STAX Job Monitor?
4.3.5. Why I'm I getting a java.util.zip.ZipException running "java -jar STAXMon.jar"?
4.3.6. Why doesn't the STAX Job Monitor window have a close confirmation?
4.3.1.

What does RC 2 mean when starting the STAX Job Monitor?

When starting the STAX Job Monitor, if you get an error message "Error registering Job Monitor. Could not register for Job Events RC = 2", this means that Event service name specified in the STAX Job Monitor Properties was not found on the specified Event machine. In the main STAX Job Monitor window, click on File in the Menu bar, and then select Properties. Make sure that the Event Service Name is the correct Event service name for the specified Event machine. Also make sure that the Event service has been installed and configured on the Event service machine.

4.3.2.

What does RC 16 mean when starting the STAX Job Monitor?

When starting the STAX Job Monitor, if you get an error message "Error registering Job Monitor. Could not register for Job Events RC = 16", this means that Event service machine specified in the STAX Job Monitor Properties was not found. In the main STAX Job Monitor window, click on File in the Menu bar, and then select Properties. Make sure that the Event Service Machine shown is the correct Event service machine.

4.3.3.

What does RC 2 mean when submitting a new job via the STAX Job Monitor?

When starting a new job through the STAX Job Monitor, if you get an error message "STAX Error. RC:2 Error starting Job Monitor <STAX service name>", this means that STAX service name specified in the STAX Job Monitor Properties was not found on the specified STAX service machine. The "<STAX service name>" in the error message is the STAX service name which would not be found. In the main STAX Job Monitor window, click on File in the Menu bar, and then select Properties. Make sure that the STAX Service Name is the correct STAX service name for the specified STAX service machine. Also make sure that the STAX service has been installed and configured on the STAX service machine.

4.3.4.

What does RC 16 mean when submitting a new job via the STAX Job Monitor?

When starting a new job through the STAX Job Monitor, if you get an error message "STAX Error. RC:16 Error starting Job Monitor", this means that STAX service machine specified in the STAX Job Monitor Properties was not found. In the main STAX Job Monitor window, click on File in the Menu bar, and then select Properties. Make sure that the STAX Service Machine is the correct STAX service machine.

4.3.5.

Why I'm I getting a java.util.zip.ZipException running "java -jar STAXMon.jar"?

To run the command java -jar STAXMon.jar, the STAXMon.jar file must be in the current directory (otherwise you will get the ZipException). If it is not in the current directory, then you need to fully qualify the jar file name: java -jar c:/staf/services/stax/STAXMon.jar

4.3.6.

Why doesn't the STAX Job Monitor window have a close confirmation?

Closing the STAX Job Monitor window should never terminate your job. Doing that just closes that view of the job; the STAX job should still be running. In the main STAX Monitor window (which shows the table of currently running STAX jobs), your job still should be there, and you should be able to right click on it and select "Start Monitoring", and you should see a new STAX Job Monitor window for your STAX job.