STAF V3 Migration Guide

Software Testing Automation Framework (STAF) V3 Migration Guide

April 23, 2005

Contents

1.0 Introduction

The intended reader for this document is anyone who is currently using STAF V2 and who will be migrating to STAF V3.

2.0 Why Migrate?

STAF has remained basically backward compatible for 7 years and over 25 releases (since STAF V1.0 was first made available in April 1998). To further advance STAF and to accomplish some features requested by our customers, STAF V3 will not be fully backward compatible with STAF V2 / V1. Our intention is to make all the backward incompatible changes in STAF V3.0 so that future versions of STAF will be backwards compatible with STAF V3.0 and later.

End of service for all STAF V2 releases is planned for April 21, 2006. As of April 21, 2006, we will no longer fix bugs in STAF V2 and will not release any new versions of STAF V2 (though we will continue to try to answer STAF V2 questions). Note that since STAF is open source, you can fix a problem in STAF V2 yourself. But, to have complete support from the STAF Development team, move to STAF V3.

New STAF clients should start with the latest STAF V3 release. Existing STAF V2 clients should wait for a break in their test cycles to migrate to STAF V3, but we encourage our clients to migrate as soon as realistically possible to take advantage of the many new features and capabilities in STAF V3.

Upgrading from STAF V2 to STAF V3 is supported (instead of having to uninstall STAF V2 before installing STAF V3). It is recommended, if possible, that when upgrading to STAF V3, you upgrade all of your STAF machines to V3 at the same time.

If you register any external STAF services with STAF V3, you will have to install a version of the external STAF service that supports STAF V3. Note that STAF services that support V2 don't work with STAF V3 and vice versa because of different service interface levels. For example, to run the STAX service on a STAF V3 machine, you must have STAX V3 installed as an earlier version of STAX such as V1.5.5 will not work with STAF V3.

3.0 Migration Preparation

To help current STAF V2 customers prepare for migrating from STAF V2 to V3, we provided a new DIAG (Diagnostics) internal service in STAF V2.6 and instrumented all requests whose syntax and/or results will be changing in STAF V3 so that clients can identify which test cases, STAX jobs, applications, and services that they have written will need to be updated to work with STAF V3.

Use the migration data provided by enabling the DIAG service on your STAF V2 machines to gauge how much migration work will be required. You will need to enable diagnostics on all machines involved in running a test, STAX job, etc., and then collect the diagnostics information from all machines after running the test. See "Appendix A: STAF V3 Migration Diagnostic Triggers in STAF V2.6.x" for more information.

You will probably need to make updates to existing STAF-enabled testcases, STAX jobs, custom services, etc., due to changes in the syntax and results for some STAF requests, service interface changes, etc.

For example, if you wanted to gather STAF V3 migration diagnostics data for a particular STAX job, you would enable diagnostics on the STAX service machine (and possibly on other STAF machines as well if you are running STAF-enabled testcases on other machines in the STAX job) and then run the job. When the job is complete, you can then disable diagnostics.

For example, you can list the sources for the diagnostics information. If you run a STAX job, you could see information like the following. 

STAF stax1 DIAG LIST SOURCES
Response
--------
From Date/Time    : 20041108-13:15:27
To Date/Time      : 20041108-13:20:39
Elapsed Time      : 00:05:12
Number of Sources : 4

2807;STAX/JobMonitor/lucas/2;lucas.austin.ibm.com;28
658;STAX/Job/2;lucas.austin.ibm.com;27
460;STAX/JobMonitor/Extension/STAFCmdTable;lucas.austin.ibm.com;30
44;STAX/JobMonitor/Extension/ProcessTable;lucas.austin.ibm.com;29
You can ignore STAF V3 migration diagnostics from sources like STAX/JobMonitor/... because STAF Development is responsible for updating the STAX Monitor to work with STAF V3. You'll want to look at the triggers generated by the source of your STAX job, which in this case, is STAX/Job/2;lucas.austin.ibm.com;27 which represents the handle name, the machine, and the handle number. For example, you can list all diagnostics for this source and sort by trigger (or count). 
STAF stax1 DIAG LIST SOURCE STAX/Job/2;lucas.austin.ibm.com;27 SORTBYTRIGGER
Response
--------
From Date/Time    : 20041108-13:15:27
To Date/Time      : 20041108-13:21:19
Elapsed Time      : 00:05:52
Source            : STAX/Job/2;lucas.austin.ibm.com;27
Number of Triggers: 37

19;STAF/V3.0-Mig/FS DELETE (No IGNOREERRORS)
4;STAF/V3.0-Mig/FS LIST
8;STAF/V3.0-Mig/HANDLE QUERY
1;STAF/V3.0-Mig/MISC MACHINE
4;STAF/V3.0-Mig/MISC TRACE LIST
15;STAF/V3.0-Mig/MISC TRACE
4;STAF/V3.0-Mig/MONITOR LIST
3;STAF/V3.0-Mig/MONITOR QUERY
10;STAF/V3.0-Mig/MONITOR SET
2;STAF/V3.0-Mig/PROCESS FREE ALL|WORKLOAD
1;STAF/V3.0-Mig/PROCESS NOTIFY LIST
4;STAF/V3.0-Mig/PROCESS QUERY
15;STAF/V3.0-Mig/PROCESS START WAIT
1;STAF/V3.0-Mig/PROCESS STOP ALL|WORKLOAD
545;STAF/V3.0-Mig/QUEUE GET|PEEK
1;STAF/V3.0-Mig/RESPOOL LIST
1;STAF/V3.0-Mig/RESPOOL QUERY
1;STAF/V3.0-Mig/SEM EVENT DELETE
2;STAF/V3.0-Mig/SEM EVENT POST|PULSE
1;STAF/V3.0-Mig/SEM EVENT QUERY
1;STAF/V3.0-Mig/SEM EVENT RESET
1;STAF/V3.0-Mig/SEM EVENT WAIT
2;STAF/V3.0-Mig/SEM LIST
25;STAF/V3.0-Mig/SEM MUTEX DELETE
2;STAF/V3.0-Mig/SEM MUTEX QUERY
14;STAF/V3.0-Mig/SEM MUTEX RELEASE
13;STAF/V3.0-Mig/SEM MUTEX REQUEST
2;STAF/V3.0-Mig/SHUTDOWN NOTIFY LIST
1;STAF/V3.0-Mig/STAX LIST
1;STAF/V3.0-Mig/STAX QUERY
26;STAF/V3.0-Mig/VAR DELETE
6;STAF/V3.0-Mig/VAR GET
5;STAF/V3.0-Mig/VAR LIST
4;STAF/V3.0-Mig/VAR RESOLVE (Multiple)
25;STAF/V3.0-Mig/VAR RESOLVE
34;STAF/V3.0-Mig/VAR SET
10;STAF/V3.0-Mig/ZIP LIST

You'll probably want to redirect the diagnostics information from each machine to a file: 

STAF stax1 DIAG LIST SOURCE STAX/Job/2;lucas.austin.ibm.com;27 SORTBYTRIGGER > C:\client1DiagForSTAXJob1.txt

4.0 Migration Checklist

  1. Run your STAF-enabled testcases/applications, STAX jobs, custom STAF services, etc. on STAF V2.6.x machines with diagnostics enabled and colllect the diagnostics. Note that you need to enable and collect diagnostics on all of the machines involved.

  2. Analyze the migration diagnostics data.

  3. Update your testcases, STAX jobs, and custom services to work with STAF V3 based on the analysis of the migration diagnostics data.

  4. Test that the changes work with STAF V3.

  5. Determine which STAF-enabled testcases/applications, STAX jobs, custom STAF services, etc. should be changed to leverage new features in STAF V3 such as marshalling multi-valued results from LIST/QUERY requests, etc. or marshalling multi-valued information in a queued message. For example,

  6. Complete the changes.

  7. Test that the changes work with STAF V3.

5.0 New Features in STAF V3

Here is a list of some of the major enhancements in STAF V3:

The following sections provide a more in-depth description for each enhancement.

5.1 Communication Interface Enhancements

Many communication interface enhancements have been included in STAF V3. Some of the major enhancements include:

5.2 IPv6 Support

5.3 Enhanced Security

For example, here's an example of configuring an authenticator in the STAF configuration file and using it in trust specifications: 

AUTHENTICATOR AuthSample LIBRARY JSTAF \
              EXECUTE C:\STAF\services\AuthSample.jar
              PARMS "USERPROPERTIESFILE C:\STAF\services/auth.prp"

TRUST LEVEL 5 USER AuthSample://JohnDoe@us.ibm.com
TRUST LEVEL 4 USER AuthSample://*@us.ibm.com

5.5 New Format for Multi-Valued Results

How the STAF Command Handles a Multi-Valued Result

The STAF command automatically unmarshalls the result and prints it in the most appropriate format: simple (or default), table, or verbose.

Handling Multi-Valued Results

See section 6.5 Marshalling Structured Data for more information on how to handle multi-value results (marshalled structured data) and examples on how to do this via different programming languages or via a STAX job.

5.6 Inform on Garbage Collected Handles

C:\>STAF local SEM REQUEST MUTEX myMutex
Response
--------

C:\>STAF local SEM QUERY MUTEX myMutex
Response
--------
{
  State           : Unowned
  Owner           : 
  Pending Requests: []
}
Note that you are not the mutex owner because the STAF command executable deleted the handle and it was garbage collected. 
C:\>STAF local HANDLE CREATE HANDLE NAME MyHandle
Response
--------
33

C:\>set STAF_STATIC_HANDLE=33

C:\>STAF local SEM REQUEST MUTEX myMutex
Response
--------

C:\>STAF local SEM QUERY MUTEX myMutex
Response
--------
{
  State           : Owned
  Owner           : {
    Machine            : client1.ibm.com
    Handle Name        : MyHandle
    Handle             : 33
    User               : none://anonymous
    Endpoint           : tcp://client1.ibm.com@6500
    Date-Time Requested: 20041012-10:16:20
    Date-Time Acquired : 20041012-10:16:20
  }
  Pending Requests: []
}
Note that you are the mutex owner since the handle is a static one and, thus, still exists.

5.7 Send Variables Across the Network

In STAF V2, a STAF handle's variable pool is only used in variable resolution if the request is processed locally. If a request is made to a remote machine, the STAF handle's variable pool is not delivered to the remote machine so it is not used in variable resolution. On remote machines, only the remote system's global variable pool is used. This leads to issues where variables such as a handle's log mask are not propagated to remote machines. However, of possibly larger consequence is that this flaw limits the ability of services to provide configurability on a per-handle basis. For example, the Log service could potentially allow for a default logging level to be specified in a STAF variable. But, in STAF V2, this would only work for systems doing local logging. With the addition of the following enhancements in STAF V3, STAF services will be able to start leveraging STAF variables for defining configurable behavior.

A new SHARED option has been added to the VAR service SET, GET, DELETE, LIST, and RESOLVE requests. On SET, GET, and DELETE requests, this option will direct the request to the system's shared variable pool. On a RESOLVE request, the SHARED option will resolve variables in the context of the system's shared variable pool. On a LIST request, this option will list the contents of the system's shared variable pool. For more information on the changes made in STAF V3 for this enhancement, please see sections "2.4, Variables" and "8.19, Variable (VAR) Service" in the STAF V3 User's Guide.

Here's a summary of the new variable enhancements:

Here is the updated syntax for the VAR service: 

C:\>STAF local VAR HELP
Response
--------
VAR Service Help

SET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name=Value> [VAR <Name=Value>]...

GET [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name>

DELETE [SYSTEM | SHARED | HANDLE <Handle>] VAR <Name> [VAR <Name>]...

LIST [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> |
      REQUEST [<Request Number>] ]

RESOLVE [SYSTEM | SHARED | HANDLE <Handle> | ASHANDLE <Handle> |
         REQUEST [<Request Number>] ]
        STRING <String> [STRING <String>]...

HELP

5.8 Standardize Request Strings for Services

5.9 Provide/Use Data Directory for STAF and its Services

Java Service's init() Example Using info.writeLocation

We have standardized where data within the "STAF data directory" should be stored. For example, a service should write its data to a directory named <STAF Write Location>/service/<Service Name (lower-case)>. 

    // Assign the location that the service can write data to, 
    // <STAF Write Location>/service/<service name (lower-case)>
    // and create the directory if it doesn't exist.

    fDataDir = info.writeLocation + fileSep + "service" + fileSep +
        fServiceName.toLowerCase();

    File dir = new File(fDataDir);

    if (!dir.exists())
    {
        dir.mkdirs();
    }

Here's a table showing the location that STAF V3 services write data compared to the location that STAF V2 services write data. If you want to use existing data for a STAF V2 service, then you will have to copy the directory or files from the old STAF V2 location to the new STAF V3 location.

Comparison of Write Locations for STAF V3 and STAF V2
Service Directory or Files to Copy STAF V3 Location STAF V2 Location
Log Service Directory {STAF/DataDir}/service/<Service name (lower-case)> {STAF/Config/STAFRoot}/data/log
ResPool Service Directory {STAF/DataDir}/service/<Service name (lower-case)> {STAF/Config/STAFRoot}/data/<Service name (lower-case)>
EventManager Service Directory {STAF/DataDir}/service/<Service name (lower-case)> {STAF/Config/STAFRoot}/data/eventmanagerdata
Cron Service Directory {STAF/DataDir}/service/<Service name (lower-case)> <System.getProperty(user.home)>/crondata
Event Service Files {STAF/DataDir}/service/<Service name (lower-case)>/GenManager.out and RegManager.out <Directory where STAFProc was started>/GenManager.out and RegManager.out
NamedCounter Service File {STAF/DataDir}/service/<Service name (lower-case)>/namedCounter.ser <Directory where STAFProc was started>/.ser
Timer Service Files {STAF/DataDir}/service/<Service name (lower-case)>/tlist.ser and wlist.ser {STAF/Config/STAFRoot}/bin/tlist.ser and wlist.ser

5.10 Installation Enhancements

6.0 STAF V3 Changes

Many enhancements have been added in STAF V3. Some of these enhancements resulted in changes that are not backward compatible with STAF V2. Some of the changes that you may encounter are described in this section.

6.1 Installation Changes

Some of the installation improvements in STAF V3 are:

  1. STAF V3 supports installation upgrades. When you want to upgrade from a previous version of STAF (e.g. STAF V2 or STAF V3.0.0 Beta 5) to STAF V3, you no longer have to first uninstall STAF before installing STAF V3.

    If you migrated from STAF V2 to STAF V3, there are a couple of things you'll need to consider:

  2. STAF V3 allows installation of multiple different versions of STAF on a single machine. For example, if you already have STAF V2 installed, and you want to try out STAF V3, the installation allows you to install STAF V3 in a different directory without overriding the STAF V2 installation. To run multiple versions of STAF at the same time, you will need to set environment variable STAF_INSTANCE_NAME to differentiate between multiple instances of STAF and you must specify different ports for the tcp interface in the STAF configuration file.

    In addition, now that you can have more than one version of STAF installed on a machine, we are providing script files in STAF V3 that you can run to set up your STAF environment. These are located in the root STAF directory (STAFEnv.bat on Windows, STAFEnv.sh on Unix). In STAF V3 (GA release and later) we will also be creating a similar file for any STAF 2.x version installed on the machine. Here's a sample one for Windows you can use for STAF V2 if you are running STAF V2 and STAF V3 on the same system. 

    @echo off 
REM STAF environment variables 
set PATH=C:\STAF\bin;%PATH% 
set CLASSPATH=C:\STAF\bin\JSTAF.jar;C:\STAF\samples\demo\STAFDemo.jar;%CLASSPATH% 
set STAFCONVDIR=C:\STAF\codepage
    Of course, if you have STAF V2 installed in a location other than C:\STAF, you would need to change this sample script. The sample scripts that are created automatically by STAF V3 will use the actual install directories in the files.

    Note: When you install STAF V3 on a Windows system that already has STAF 2.6.5 or earlier installed (at a different location), only the STAF V3 uninstall is available in Add/Remove Programs. To uninstall STAF V2, you will need to open a command prompt, go to the _uninst directory in the root STAF V2 installation directory, and run "uninstaller.exe". To uninstall STAF 2.6.6 or later, instead of running the uninstaller.exe from a command prompt, there is a "Uninstall STAF" icon in the "STAF - Software Testing Automation Framework" folder that can be used to uninstall STAF 2.6.6 or later.

  3. STAF V3 tar and zip files, as well as all of the service V3 tar and zip files, have been changed so that they unpack into a single directory. So, for example, when you unzip the STAXV3xx.zip file, it will now create a directory named stax.

  4. STAF V3 now uses InstallShieldX instead of InstallShield Multi-Platform.

6.2 STAF Configuration File Changes

The STAF configuration file that you used from STAF V2 will not work with STAF V3. Here is a list of the changes that you may need to make:

  1. Changed Syntax of Trace Statements

    You may enable or disable STAF trace points and STAF services for tracing using the TRACEM configuration statement. In addition, you can set the trace output destination and set the default tracing state for newly registered services. By default, all STAF services are enabled for tracing. Also, if you are using the default STAF configuration file provided, only the ERROR and DEPRECATED trace points are enabled by default.

    Note: The TRACE ENABLE/DISABLE SERVICE(S) statements affect the current list of services. So, if you add line TRACE DISABLE ALL SERVICES to the configuration file and then register any external services later in the configuration file, those services will not necessarily be disabled. To ensure that all registered services are disabled, either set the default service state to disabled, or add the TRACE statements after the SERVICE configuration statements in the configuration file. Here's the new syntax for TRACE statements in the STAF configuration file: 

    TRACE ENABLE ALL  [ TRACEPOINTS | SERVICES ]
TRACE ENABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
TRACE ENABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
TRACE ENABLE SERVICE <Service> [SERVICE <Service>]...
 
TRACE DISABLE ALL  [ TRACEPOINTS | SERVICES ]
TRACE DISABLE TRACEPOINTS <Trace point list> | SERVICES <Service list>
TRACE DISABLE TRACEPOINT <Trace point> [TRACEPOINT <Trace point>]...
TRACE DISABLE SERVICE <Service> [SERVICE <Service>]...
 
TRACE SET DESTINATION TO < STDOUT | STDERR | FILE <File name> >
TRACE SET DEFAULTSERVICESTATE <Enabled | Disabled>

  2. Removed/Added Operational Parameters

  3. Removed the MACHINE Configuration Statement

    It is no longer needed.

  4. Added the MACHINENICKNAME Configuration Statement

    The MACHINENICKNAME configuration statement is used to specify a nickname for your machine. This overrides the value of the STAF/Config/MachineNickname system variable which defaults to the value of the STAF/Config/Machine system variable (e.g. the long host name). This primarily effects the data stored by services such as the Log and Monitor services, which store data based on the machine from which it came by using the STAF/Config/MachineNickname system variable as part of the directory path when creating logs and monitor data. By allowing the STAF/Config/MachineNickname system variable to be overridden, it allows you to better manage your data.

    Note: The machine nickname is not used to communicate with other systems and does not have any effect on trust.

  5. Network Interfaces

    You indicate that you wish to send and accept requests on a network interface using the INTERFACE configuration statement. The INTERFACE configuration statement registers connection providers (also called network interfaces, or interfaces for short). In STAF V3, you can register multiple, pluggable interfaces.

    The syntax for the default tcp interface changed in STAF V3:

    Notes:

    1. The only network interface which comes with STAF is TCP/IP (uses implementation library STAFTCP). However, STAF allows you to plug in network interfaces (aka connection providers) so that you can create your own connection provider which can communicate via any mechanism you choose (e.g. SSL, a Serial Line, NetBIOS, or SNA).
    2. An interface named local is also provided with STAF. Requests coming from the local system will appear as though they came from an interface named "local" and a system identifier of "local".

    Here's an example of configuring two TCP interfaces, one using the default port, 6500, and a second one using port 6600 for IPv6 traffic with a longer connect timeout. 

    INTERFACE tcp LIBRARY STAFTCP
INTERFACE tcp2 LIBRARY STAFTCP OPTION Port=6600 OPTION PROTOCOL=IPv6 \
                               OPTION ConnectTimeout=15000

  6. Authenticators

    Added the ability to specify multiple, pluggable Authenticator services via the new AUTHENTICATOR configuration statement. The first Authenticator registered is the default, unless overridden by using the new DEFAULTAUTHENTICATOR operational parameter.

    Here's an example of registering the sample authenticator: 

    AUTHENTICATOR AuthSample LIBRARY JSTAF \
  EXECUTE {STAF/Config/STAFRoot}\services\auth\AuthSample.jar \
  PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/auth/authsample.prp"

  7. Changed Syntax for Setting STAF Variables

    You may set STAF variables in the system or shared variable pool at startup by using the SET VAR configuration statement. SET VAR will set a variable to a certain value. The variable is created if it does not exist. Note that you may SET multiple variables with a single request.

    The new syntax is: SET [SYSTEM | SHARED] VAR <Name=Value> [VAR <Name=Value>] ...

    SYSTEM means the variable is to be set in system variable pool. This is the default.
    SHARED means the variable is to be set in shared variable pool.
    VAR means the variable to be set. Name is the name of the variable and Value is the value of the variable.

    Here are some examples of setting some STAF variables in the system and shared variable pools: 

    SET SYSTEM VAR STAFDemo/JavaAppClassPath={STAF/Env/CLASSPATH};C:\STAF\samples\demo\STAFDemo.jar;
SET VAR STAFDemo/JavaAppCommand=java.exe VAR STAFDemo/Dummy=dummy
SET SHARED VAR STAFDemo/JavaAppParms=STAFProcess

  8. Changed Trust Statements:

    You may grant access to machines or users by using the TRUST configuration statement. Trust configuration statements for machines are based on the network identification of the system. In particular, different trust levels can be given to the same system coming in through different networking interfaces. Both logical (e.g. hostnames) and physical identifiers (e.g. IP addresses) may be used in trust configuration statements for machines. Trust configuration statements for users require that you have an authenticator registered.

    The syntax for a trust statement is: 

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

    Notes:

    To determine effective trust for a User:

    If multiple trust specifications would match the same user, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:

    1. Exact match of authenticator and user identifier
    2. Exact match of authenticator, wildcard match of user identifier
    3. Wildcard authenticator match, exact match of user identifier
    4. Wildcard authenticator match, wildcard match of user identifier
    5. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.

    To determine effective Trust for a Machine:

    If multiple trust specifications would match the same system, STAF will rank the matching specifications as follows and use the match with the highest (i.e. lowest numbered) rank:

    1. Exact match of interface and physical network identifier
    2. Exact match of interface and logical network identifier
    3. Exact match of interface, wildcard match of physical network identifier
    4. Exact match of interface, wildcard match of logical network identifier
    5. Wildcard interface match, exact match of physical network identifier
    6. Wildcard interface match, exact match of logical network identifier
    7. Wildcard interface match, wildcard match of physical network identifier
    8. Wildcard interface match, wildcard match of logical network identifier
    9. If multiple trust specifications match within the same rank, the lowest matching trust level will be used.

    Note: The user authentication overrides the machine authentication. For example, if the machine trust level is 3 and the authenticated user has a trust level of 4, then the handle will have a trust level of 4. If the user has been authenticated, but there are no user authentication trust matches, the machine trust level is used. If there is no machine trust level specified, then the default trust level is used.

Default STAF V3 Configuration File

Here's the default STAF configuration file of STAF V3: 

# Turn on tracing of internal errors and deprecated options
trace enable tracepoints "error deprecated"

# Enable TCP/IP connections
interface tcp library STAFTCP

# Set default local trust
trust machine local://local level 5

# Add default service loader
serviceloader library STAFDSLS

Example of a Customized STAF V3 Configuration File

Here's an example of a customized STAF configuration file for STAF V3: 

# Enable TCP/IP connections
interface tcp LIBRARY STAFTCP
interface tcp2 LIBRARY STAFTCP OPTION Port=6600 OPTION ConnectTimeout=15000

# Turn on tracing of internal errors
trace enable tracepoints "deprecated error"

# Add default service loader
SERVICELOADER LIBRARY STAFDSLS

# Authenticator registration
AUTHENTICATOR AuthSample LIBRARY JSTAF \
  EXECUTE {STAF/Config/STAFRoot}\services\auth\AuthSample.jar \
  PARMS "USERPROPERTIESFILE {STAF/Config/STAFRoot}/services/auth/authsample.prp"

# Set default local trust
TRUST LEVEL 5 MACHINE local://local

# Set trusts
TRUST LEVEL 2 DEFAULT
TRUST LEVEL 3 MACHINE *.austin.ibm.com
TRUST LEVEL 4 MACHINE 9.41.53.*
TRUST LEVEL 5 MACHINE tcp://9.41.53.147
TRUST LEVEL 5 MACHINE tcp://client1.austin.ibm.com
TRUST LEVEL 5 USER AuthSample://*
TRUST LEVEL 0 USER AuthSample://User5

# Register services
SERVICE STAX  LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}\services\stax\STAX.jar \
              OPTION JVMName=STAX OPTION JVM=C:\j2sdk1.4.2_03\bin\java \
              OPTION J2=-Xmx384m \
              PARMS "EXTENSIONXMLFILE C:/staf/services/extensions.xml"

SERVICE Event LIBRARY JSTAF \
              EXECUTE {STAF/Config/STAFRoot}\services\stax\STAFEvent.jar \
              OPTION JVMName=STAX

SERVICE Cron  LIBRARY JSTAF \
              EXECUTE {STAF/Config/STAFRoot}\services\cron\STAFCron.jar

# Set up some STAF variables
SET SYSTEM VAR STAFDemo/JavaAppClassPath=C:\STAF\lib\JSTAF.jar;C:\STAF\samples\demo\STAFDemo.jar;
SET VAR STAFDemo/JavaAppCommand=java.exe VAR STAFDemo/Dummy=dummy
SET SHARED VAR STAFDemo/JavaAppParms=STAFProcess

6.3 Pre-defined STAF Variable Changes

STAF maintains a "system" variable pool that is common to all the processes on a given STAF Client. STAF predefines a set of system variables. Some of these system variables (formerly known as "global" variables in STAF V2) have been removed in STAF V3 and some variables have been added in STAF V3.

The following variable was removed from the set of system variables that STAF pre-defines:

The following variables were added to the set of system variables that STAF pre-defines:

6.4 Removed Deprecated Functions

6.5 Marshalling Structured Data

If you're the owner of a custom STAF service and you want to leverage the multi-value result change in your service or if your testcase or application is providing a multi-value queued message, read this section to learn more about providing the result or message in a marshalled data structure.

The multi-value result change is applicable to any command that can logically return multiple values. Essentially any command where the user would take the result buffer and parse it into multiple values instead of just using the whole thing as a string. The most common examples of these are LIST and QUERY commands which almost always return multiple values. But, that doesn't mean there might not be other commands that return multiple values. For example doing a PROCESS FREE ALL will return two values (the total number of processes and the total that were freed). In some cases, the multiple values are only returned as part of an error (for example an FS DELETE, generally of a directory, without IGNOREERRORS will return a list of the files/directories that couldn't be deleted).

For example, in STAF V2, a LIST MUTEX request to the SEM service could result in the following output: 

DataSource1: Unowned
Printers/Printer1: Owned - 2 pending request(s)
You had to parse this information in order to get the name of each mutex, to determine if a mutex is owned or unowned and if there are any pending requests.

In STAF V3, multi-valued results are now returned as marshalled data structures. In STAF V3, a LIST MUTEX request to the SEM service results in a marshalled <List> of <Map:STAF/Service/Sem/MutexInfo> representing the mutex semaphores. This map class is defined with keys: name, state, pendingRequests. In STAF V3, a LIST MUTEX request to the SEM service issued from the command line, could look like the following in table format: 

Name              State   Pending Requests
----------------- ------- ----------------
DataSource1       Unowned 0
Printers/Printer1 Owned   2
But, more importantly, when accessed via a testcase (e.g. a Java program) or a STAX job, you do not have to parse the result to obtain the name of each mutex, or its state, or the number of pending requests. So, after the result is unmarshalled, you can iterate through the list accessing the name, state, and pending requests via the map keys for each entry in the list.

Read section "6.1 Marshalling Structured Data" in the STAF V3 User's Guide for more information about how STAF supports the automatic marshalling and unmarshalling of structured data. The act of marshalling takes a data structure and converts it into a string-based representation. The act of unmarshalling reverses this and converts the string-based representation back into a data structure.

Also, see the STAF V3 Service Developer's Guide for more information on how to convert a multi-valued result into a marshalled data structure.

Once the data structure is generated, the data structure needs to be set as the root of a marshalling context. Then you can marshall the marshalling context itself to create a string which can then be returned in the result buffer.

When structured data is returned in the result string, the STAF command will automatically unmarshall the data and print it in the most appropriate format. See section "5.2 STAF" in the STAF V3 User's Guide for more information on this.

If a request returns a multi-valued result, such as a LIST or QUERY request, you should create a marshalled data structure to be returned in the result buffer.

Here are some examples of marshalling structured data in Java and C++. These are examples from the sample Device service described in the STAF V3 Service Developer's Guide that shows how to generate marshalled structured data for a LIST request. See the STAF V3 Service Developer's Guide for the complete code.

6.6 Handling Marshalled Structured Data (Unmarshalling)

This section shows you examples of handling marshalled data structures, in this case, the result from a LIST request, via a Java program, a C++ program, and a STAX job.

When you submit a LIST POOLS request to the RESPOOL service in STAF V3, the result is a data structure consisting of a list of maps, one for each pool. 

C:\>STAF local RESPOOL LIST POOLS
Response
--------
Pool Name Description
--------- -----------------------
pool1     Pool 1
STAFDemo  STAF Demo Resource Pool
Here are some examples of how you can access values in the multi-valued result:

6.7 STAF Custom Service Changes

If you have written any custom STAF services, you will need to make changes to them in order for them to work with STAF V3. This section talks about changes that are specific to custom services. Other changes described elsewhere in this migration guide may also apply to your service. For example, if your service submits any requests to STAF services, you'll want to gather the STAF V3 migration diagnostics to see if the syntax and/or results for the request have changed. Also, if your services resolves any STAF variables, you'll want to make sure that those variables still exist. If your service submits requests to STAF services on remote machines, you'll need to consider whether your service should support remote machines that are running STAF V2 or just STAF V3.

6.7.1 STAF Java Service Changes

If you wrote a custom STAF service in Java, you must make the following changes to enable your service to work with STAF V3:

  1. Change the service interface level as follows:

    1. Change the STAFServiceInterfaceLevel class that the service implements to be STAFServiceInterfaceLevel30 
      public class MyService implements STAFServiceInterfaceLevel30
    2. Change the service's init method to pass in STAFServiceInterfaceLevel30.InitInfo 
      public STAFResult init(STAFServiceInterfaceLevel30.InitInfo info)
    3. Change the service's acceptResult method (and any handleXXX methods) to pass in STAFServiceInterfaceLevel30.RequestInfo 
          public STAFResult acceptRequest(STAFServiceInterfaceLevel30.RequestInfo info)
    private STAFResult handleXXX(STAFServiceInterfaceLevel30.RequestInfo info)
  2. You may want to change your service to take advantage of two new fields that were added to the STAFServiceInterfaceLevel30.InitInfo class. shown in bold: 
        public InitInfo(String name, String parms, JarFile serviceJar,
                    int serviceType, String writeLocation)
    {
        this.name = name;
        this.parms = parms;
        this.serviceJar = serviceJar;
        this.serviceType = serviceType;
        this.writeLocation = writeLocation;
    }
    In STAF V3, we have standardized where data within the directory specified by the writeLocation field should be stored. A service should write its data to a directory named info.writeLocation + "/service/" + info.name.toLowerCase().

    Here's a snippet of code that could be used in the init() method, to assign the location that the service should write its data. 

        // Assign the location that the service can write data to and create the
    // directory if it doesn't exist.

    fDataDir = info.writeLocation + fileSep + "service" + fileSep +
        info.name.toLowerCase();

    File dir = new File(fDataDir);

    if (!dir.exists())
    {
        dir.mkdirs();
    }

  3. Change the init and term methods for Java services to return a STAFResult instead of an int return code. 
        STAFResult init(InitInfo initInfo)
    STAFResult term()
    The STAFResult class consists of an int rc (return code) and a String result so that your service can now return not only a return code, but also more information about the error.

    Both the RC and Result will be provided in the STAFProc window if an error occurs registering or unregistering a service when starting STAF, or if dynamically registering/unregistering a service via a SERVICE ADD/REMOVE request, the result buffer will contain the additional information about the error.

    For example, if in the init() method, your Java service submitted a request to resolve a STAF variable, you should change the service to return the STAFResult object from the resolve request, instead of just a return code. 

        // Get the file separator

    String fileSep;
            
    STAFResult res = fHandle.submit2(
        "local", "VAR", "RESOLVE STRING {STAF/Config/Sep/File}");

    if (res.rc != 0)
        return res;
    else
        fileSep = res.result;
  4. Change your service if it uses any fields that were removed or whose name changed in the STAFServiceInterfaceLevel30.RequestInfo class. Here's the new definition for STAF V3.0.0 with the new and changed fields shown in bold: 
        static public class RequestInfo
    {
        public String  stafInstanceUUID;
        public String  machine;
        public String  machineNickname;
        public String  handleName;
        public int     handle;
        public int     trustLevel;
        public boolean isLocalRequest;
        public int     diagEnabled;
        public String  request;
        public int     requestNumber;
        public String  user;
        public String  endpoint;
        public String  physicalInterfaceID;
    ...
    }

    Change your service to not use the following fields which were removed from the STAFServiceInterfaceLevel30.RequestInfo class:

    The following fields were added to the STAFServiceInterfaceLevel30.RequestInfo class:

6.7.2 STAF C++ Service Changes

If you wrote a STAF service in C++, you must make the following changes:

  1. Change the service interface level to be 30 for all service interface methods. For example, change the STAFServiceConstruct, STAFServiceInit, and STAFServiceAcceptRequest methods to check if the level is 30 and if not, return kSTAFInvalidAPILevel. Also, change to cast the pServiceInfo, pInitInfo, and pRequestInfo to level 30 of STAFServiceInfoLevel30, STAFServiceInitLvel30 and STAFServiceRequestLevel30 respectively. Also, change any handleXXX methods to specify STAFServiceRequestLevel30. 
    STAFRC_t STAFServiceConstruct(STAFServiceHandle_t *pServiceHandle,
                              void *pServiceInfo, unsigned int infoLevel,
                              STAFString_t *pErrorBuffer)
{
    if (infoLevel != 30) return kSTAFInvalidAPILevel;

    try
    {
        STAFServiceInfoLevel30 *pInfo =
            reinterpret_cast<STAFServiceInfoLevel30 *>(pServiceInfo);
        ...

STAFRC_t STAFServiceInit(STAFServiceHandle_t serviceHandle,
                         void *pInitInfo, unsigned int initLevel,
                         STAFString_t *pErrorBuffer)
{
    if (initLevel != 30) return kSTAFInvalidAPILevel;

    try
    {
        STAFServiceInitLevel30 *pInfo =
            reinterpret_cast<STAFServiceInitLevel30 *>(pInitInfo);
        ...

STAFRC_t STAFServiceAcceptRequest(STAFServiceHandle_t serviceHandle,
                                  void *pRequestInfo, unsigned int reqLevel,
                                  STAFString_t *pResultBuffer)
{
    if (reqLevel != 30) return kSTAFInvalidAPILevel;

    try
    {
        STAFServiceRequestLevel30 *pInfo =
            reinterpret_cast<STAFServiceRequestLevel30 *>(pRequestInfo);
        ...

  2. Change the min/max interface levels for ServiceInfo, ServiceInit, and ServiceAcceptRequest to be 30. 
    STAFRC_t STAFServiceGetLevelBounds(unsigned int levelID,
                                   unsigned int *minimum,
                                   unsigned int *maximum)
{
    switch (levelID)
    {
        case kServiceInfo:
        {
            *minimum = 30;
            *maximum = 30;
            break;
        }
        case kServiceInit:
        {
            *minimum = 30;
            *maximum = 30;
            break;
        }
        case kServiceAcceptRequest:
        {
            *minimum = 30;
            *maximum = 30;
            break;
        }
        case kServiceTerm:
        case kServiceDestruct:
        {
            *minimum = 0;
            *maximum = 0;
            break;
        }
        default:
        {
            return kSTAFInvalidAPILevel;
        }
    }

    return kSTAFOk;
}
  3. A new field was added to the STAFServiceInfoLevel30 structure shown in bold: 
        struct STAFServiceInfoLevel30
    {
        STAFString_t name;
        STAFString_t exec;
        STAFString_t writeLocation;
        STAFServiceType_t serviceType;
        unsigned int numOptions;
        STAFString_t *pOptionName;
        STAFString_t *pOptionValue;
    };

    The serviceType field specifies the type of service (e.g. regular service, service loader service, or authenticator service).

    No changes are required to be made to your service for this change.

  4. Change your service if it uses any fields that were removed or whose name changed in the STAFServiceRequestLevel30 structure. Here's the new definition for STAF V3.0.0 with the new and changed fields shown in bold: 
        struct STAFServiceRequestLevel30
    {
        STAFString_t        stafInstanceUUID;
        STAFString_t        machine;
        STAFString_t        machineNickname;
        STAFString_t        handleName;
        STAFHandle_t        handle;
        unsigned int        trustLevel;
        unsigned int        isLocalRequest;
        unsigned int        diagEnabled;
        STAFString_t        request;
        STAFRequestNumber_t requestNumber;
        STAFString_t        user;
        STAFString_t        endpoint;
        STAFString_t        physicalInterfaceID;
    };

    Change your service to not use the following fields which were removed from the STAFServiceInterfaceLevel30.RequestInfo class:

    The following fields were added to the STAFServiceInterfaceLevel30.RequestInfo class:

Appendix A: STAF V3 Migration Diagnostic Triggers in STAF V2.6.x

This section contains a list of the triggers for all STAF commands owned by the STAF Development team that will be changing in STAF V3 due to one or both of the following reasons:

  1. The result can "logically" return more than one value so the format of the result will be changing to allow for easier parsing of the result.

    Note that many results vary depending on the request options specified, with results for some requests sometimes containing multiple values and at other times only containing one value.

  2. The syntax of the STAF command is changing in STAF V3. For example, we're going to create a new TRACE service in STAF V3 and move the TRACE commands from the MISC service to a new TRACE service so the syntax for all :xph.TRACE:exph. commands will be changing. As another example, we're standardizing the syntax for requests in STAF V3. As a result of this, the syntax for all requests to the VAR service are changing.

Trigger Syntax

The format of the trigger recorded by STAF services for STAF V2 to aid in migrating to STAF V3 is: 

STAF/V3.0-Mig/<Service> <Request>
where:

Source Syntax

The format of the source recorded by STAF services to aid in migrating to STAF V3 is: 

<Handle Name>;<Machine Name>;<Handle#>
where:

STAF V3 Migration Diagnostics Triggers
Trigger Meaning
STAF/V3.0-Mig/CRON LIST This indicates a LIST request to the CRON service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/EVENT LIST This indicates a LIST request to the EVENT service. The result and syntax for the request will change in STAF V3.

The syntax changes include:

  • LIST REGCLIENTS -> LIST REGISTRATIONS
  • LIST EVENTIDS -> LIST EVENTIDS LONG
  • LIST TYPES -> LIST TYPES LONG
  • LIST TYPE -> LIST TYPES
  • LIST TYPE -> LIST SUBTYPES TYPE
  • LIST EVENTID -> QUERY EVENTID LONG
  • LIST EVENTIDS -> LIST EVENTIDS LONG
STAF/V3.0-Mig/EVENT QUERY This indicates a QUERY request to the EVENT service. The result and syntax for the request will change in STAF V3.

The syntax changes include:

  • QUERY TYPE <Type> -> LIST REGISTRATIONS LONG TYPE <Type>
  • QUERY LONG TYPE <Type> [SUBTYPE <Subtype>] -> LIST REGISTRATIONS LONG TYPE <Type> [SUBTYPE <SubType>]
STAF/V3.0-Mig/EVENTMANAGER LIST This indicates a LIST request to the EVENTMANAGER service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FS COPY DIRECTORY (no IGNOREERRORS) This indicates a COPY DIRECTORY request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FS DELETE (no IGNOREERRORS) This indicates a DELETE request to the FS service, without the IGNOREERRORS option. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FS GET ENTRY SIZE This indicates a GET ENTRY request to the FS service, with the SIZE option specified. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FS LIST This indicates a LIST request to the FS service. The result for the request will change in STAF V3. Also, changed the request syntax: the FORMAT option will change to the DETAILS option in STAF V3. Also, note that the default format when using the LONG option is different in STAF V3.
STAF/V3.0-Mig/FS QUERY This indicates a QUERY request to the FS service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FSEXT QUERY This indicates a QUERY request to the FSEXT service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FSEXT COMPAREDIR (No EXISTS) This indicates a COMPARDIR request to the FSEXT service that does not specify the EXISTS option. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FSEXT FILECONTAINS NOT This indicates a FILECONTAINS request to the FSEXT service with the NOT option specified. The result for the request will change in STAF V3.
STAF/V3.0-Mig/FSEXT LINECONTAINS This indicates a LINECONTAINS request to the FSEXT service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HANDLE QUERY This indicates a QUERY request to the HANDLE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HELP ERROR This indicates a ERROR request to the HELP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HELP LIST This indicates a LIST request to the HELP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HTTP FOLLOW LINK This indicates a FOLLOW LINK request to the HTTP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HTTP LIST This indicates a LIST request to the HTTP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HTTP REQUEST|POST|DOGET This indicates a REQUEST, POST, or DOGET request to the HTTP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HTTP QUERY This indicates a QUERY request to the HTTP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/HTTP SUBMIT FORM This indicates a SUBMIT FORM request to the HTTP service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/LOG LIST This indicates a LIST request to the LOG service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/LOG PURGE This indicates a PURGE request to the LOG service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/LOG QUERY This indicates a QUERY request to the LOG service. The result for the request will change in STAF V3. :p. In addition, there are some changes to the request syntax in STAF V3: :ul. :li.The FIELDSEP option has been removed since it is no longer needed with the way multi-valued results are handled in STAF V3. :li.There is now a DefaultMaximumQueryRecords parameter/setting in STAF V3 that is set by default to 100. You may need to add the ALL option to your QUERY request in STAF V3 if you really want all of the records even if the number of records matching the query criteria exceeds the default maximum query records. :eul.
STAF/V3.0-Mig/LOG SET This indicates a SET request to the LOG service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/MISC MACHINE This indicates a MACHINE request to the MISC service. This request does not exist in STAF V3 as it is no longer needed since there a USELONGNAMES operational setting no longer exists (e.g. the effective machine name and machine name are now the same).
STAF/V3.0-Mig/MISC TRACE This indicates any TRACE request to the MISC service, other than a TRACE LIST request. The syntax for the request will change in STAF V3 due to moving the TRACE requests from the MISC service to a new TRACE service.
STAF/V3.0-Mig/MISC TRACE LIST This indicates a LIST request to the MISC service. The result for the request will change in STAF V3, as well as the syntax.
STAF/V3.0-Mig/MONITOR LIST This indicates a LIST request to the MONITOR service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/MONITOR QUERY This indicates a QUERY request to the MONITOR service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/MONITOR SET This indicates a SET request to the MONITOR service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/NAMEDCOUNTER LIST This indicates a LIST request to the NAMEDCOUNTER service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/PROCESS FREE ALL|WORKLOAD This indicates a FREE ALL or FREE WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/PROCESS NOTIFY LIST This indicates a NOTIFY LIST request to the PROCESS service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/PROCESS QUERY This indicates a QUERY request to the PROCESS service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/PROCESS START WAIT This indicates a START request to the PROCESS service with the option WAIT specified. The result for the request will change in STAF V3.
STAF/V3.0-Mig/PROCESS STOP ALL|WORKLOAD This indicates a STOP ALL or STOP WORKLOAD request to the PROCESS service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/QUEUE GET|PEEK This indicates a GET or PEEK request to the QUEUE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/QUEUE LIST This indicates a LIST request to the QUEUE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/RESPOOL LIST This indicates a LIST request to the RESPOOL service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/RESPOOL QUERY This indicates a QUERY request to the RESPOOL service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SEM EVENT DELETE This indicates an EVENT DELETE request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM EVENT POST|PULSE This indicates an EVENT POST or PULSE request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM EVENT QUERY This indicates an EVENT QUERY request to the SEM service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SEM EVENT RESET This indicates an EVENT RESET request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM EVENT WAIT This indicates an EVENT WAIT request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM LIST This indicates a LIST request to the SEM service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SEM MUTEX DELETE This indicates a MUTEX DELETE request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM MUTEX QUERY This indicates a MUTEX QUERY request to the SEM service. The syntax and the result for the request will change in STAF V3.
STAF/V3.0-Mig/SEM MUTEX RELEASE This indicates a MUTEX RELEASE request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SEM MUTEX REQUEST This indicates a MUTEX REQUEST request to the SEM service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/SERVICE FREE This indicates a FREE request to the SERVICE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SERVICE LIST This indicates a LIST request to the SERVICE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SERVICE QUERY This indicates a QUERY request to the SERVICE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SHUTDOWN NOTIFY LIST This indicates a NOTIFY LIST request to the SHUTDOWN service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/STAX EXECUTE TEST RETURNDETAILS This indicates a TEST request to the STAX service specifying option RETURNDETAILS. The result for the request will change in STAF V3. Note that RETURNDETAILS is an undocumented option and is for use by STAF developers only.
STAF/V3.0-Mig/STAX EXECUTE WAIT RETURNRESULT This indicates an EXECUTE request to the STAX service specifying options WAIT and RETURNRESULT. The result for the request will change in STAF V3.
STAF/V3.0-Mig/STAX LIST This indicates a LIST request to the STAX service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/STAX QUERY This indicates a QUERY request to the STAX service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/STAX SET This indicates a SET request to the STAX service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/SXE EXECUTE This indicates an EXECUTE request to the SXE service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/TIMER LIST This indicates a LIST request to the TIMER service. The result for the request and the syntax for the request will change in STAF V3.
STAF/V3.0-Mig/TRUST LIST This indicates a LIST request to the TRUST service. The result for the request will change in STAF V3.
STAF/V3.0-Mig/VAR DELETE This indicates a DELETE request to the VAR service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/VAR GET This indicates a GET request to the VAR service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/VAR LIST This indicates a LIST request to the TRUST service. The syntax and result for the request will change in STAF V3.
STAF/V3.0-Mig/VAR RESOLVE This indicates a RESOLVE request to the VAR service, specifying one RESOLVE option. The syntax for the request will change in STAF V3. Not only has the syntax been restructured, but the DELIMIT option for resolving multiple variables will be removed in STAF V3 as it is no longer needed due to the new format for multi-valued results.
STAF/V3.0-Mig/VAR RESOLVE (Multiple) This indicates a RESOLVE request to the VAR service, specifying more than one RESOLVE option such that the result returns the resolved value for more than one STAF variable. The syntax and result for the request will change in STAF V3.
STAF/V3.0-Mig/VAR SET This indicates a SET request to the VAR service. The syntax for the request will change in STAF V3.
STAF/V3.0-Mig/ZIP LIST This indicates a LIST request to the ZIP service. The result for the request will change in STAF V3.

Viewing STAF V3.0 Migration Diagnostics

To view the diagnostics data that has been recorded, use the LIST request for the DIAG service. See :hdref refid=diagList. for more information.

Notes

  1. STAF-enabled applications provided by the STAF Development team may also record STAF V3 migration diagnostics data. For example, the STAX Monitor will record STAF V3 migration diagnostics data because it submits QUERY requests to the STAX service and GET/PEEK requests to the QUEUE service. Diagnostics data recorded by the STAX Monitor have a source that starts with STAX/JobMonitor/ or STAX/Job/. The STAF development team will be updating the STAX Monitor for STAF V3.

  2. If a STAF request that is changing in STAF V3 originates from the STAF executable, its source recorded in the diagnostics map will start with STAF/Client since that's the handle name for any STAF command submitted at the command line.

Appendix B: Queued Message Format Changes in STAF V3

Messages queued by STAF V3 and it's services have a different format than in STAF V2. A new TYPE option was added in STAF V3 to identify the type of message being queued. STAF V3 and it's services specify a type for all the message that they generate because queued messages can contain various marshalled data structures, such as a map, so the type let's you know the structure of the message.

Here's a table showing the new format of the messages queued by STAF V3 and it's services, as well as showing the format of these messages queued by STAF V2 clients to a STAF V3 machine.

STAF V3 Queued Messages
Queued Messages from STAF V3 Queued Messages from STAF V2
TYPE: STAF/RequestComplete
MESSAGE: A map containing the request completion information as follows: 
{
  requestNumber: <Request #>
  rc           : <Request return code>
  result       : <Request result buffer>
}
TYPE: <None>
MESSAGE: A string containing request completion information as follows:

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

TYPE: STAF/Process/End
MESSAGE: A map containing the process completion information as follows: 
{
  handle      : <Handle #>
  endTimestamp: <YYYMMDD-HH&colon.MM&colon.SS>
  rc          : <Process Return Code>
  key         : <Key> | <None>
  fileList    : [
    {
      rc  : <Returned File #1 RC>
      data: <Returned File #1 Data>
    }
  ]
}
TYPE: <None>
MESSAGE: A string containing process completion information as follows:

STAF/PROCESS/END ;<Timestamp>;<Return Code>[;<Returned file data>]

TYPE: STAF/Start
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAF/START.
TYPE: STAF/Shutdown
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAF/SHUTDOWN.
TYPE: STAF/Service/Event
MESSAGE: A map containing the event information as follows: 
{
  eventID         : <Event ID>
  eventServiceName: <Event Service Name>
  handle          : <Handle #>
  handleName      : <Handle Name>
  machine         : <Machine>
  propertyMap     : {
    <Name>: <Value>
    ...
  }
  subtype         : <Subtype>
  timestamp       : <YYYYDDMM-HH:MM:SS>
  type            : <Type>
}
TYPE: <None>
MESSAGE: A string containing the event information as follows:

STAF/SERVICE/<Event Service Name>/;<Event ID>;<Generating Machine>;<Generating Process>;<Generating Handle>;<TimeStamp>;<Type>;<Subtype>; [<Name>=<Value>;]...

TYPE: STAF/Service/EventManager/End
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing EventManager/End.
TYPE: STAF/Service/Cron/End
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing Cron/End.
TYPE: STAF/Service/STAX/End
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAX/End.
TYPE: STAF/Service/STAX/JobWaitComplete/
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAX/Job/Wait/Complete/.
TYPE: STAF/STAXMonitor/End
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAXMonitorJob/End or STAXJobMonitor/End.
TYPE: STAF/Service/Timer
MESSAGE: A map containing the timer information as follows: 
{
  timerServiceName: <Timer Service Name>
  type            : <Timer Type>
  timestamp       : <YYYYDDMM-HH&colon.MM&colon.SS>
  key             : <Key (blank if no KEY specified)>
}
TYPE: <None>
MESSAGE: A string containing the timer information as follows:

STAF/SERVICE/<Timer Service Name>;<Type>;<Timestamp>;

TYPE: STAF/Service/Timer/End
MESSAGE: A string containing QUIT. 		TYPE: <None>
MESSAGE: A string containing QUIT.
TYPE: STAF/STAFDemo/Stop
MESSAGE: Blank 		TYPE: <None>
MESSAGE: A string containing STAFDemo/End.