Hands-On Automation with STAF/STAX 3 - Part 1

Exercise 1.1 - Installing STAF

Objective - Install STAF on your machine

On the STAF/STAX CD, go to directory /Part1/install and run STAF344-setup-win32.exe.

On the Introduction panel, click on Next.

On the License Agreement panel, select "I accept the terms of the license agreement". Click on Next.

On the Choose Install Folder panel, accept the default directory of C:\STAF and click on Next.

On the Choose Install Set panel, accept the default type of Full and click on Next.

On the Registration Information panel, accept all of the defaults and click on Next.

On the Advanced Options panel, accept all of the defaults and click on Next.

On the Pre-Installation Summary panel, click on Next to start the installation.

On the Install Complete panel, click on Done.

Exercise 1.2 - Starting and Stopping STAF

Objective - Learn how to start and stop STAF

Click on "Start" on the Windows task bar. Then click on "Start STAF 3.4.4". You should see a new window open titled "Start STAF" with the text "STAFProc version 3.4.4 initialized". Alternatively, you can open a command prompt and type "stafproc" to start STAF.

Click on "Start" on the Windows task bar. Then click on "Shutdown STAF 3.4.4". You should see the "Start STAF" window close.

Did STAF Stop? Yes/No ____________________

Click on "Start" on the Windows task bar. Then click on "Start STAF 3.4.4".

Go to the C:\STAF\bin directory and edit the STAF.cfg file. This is the default STAF.cfg file; note that the STAF installation program automatically configured the default Service Loader.

Exercise 1.3 - Basic STAF Commands

Objective - Learn some basic STAF commands

From a command prompt, type each of the following commands (note that they are not case sensitive):

STAF LOCAL PING PING

This command verifies that you can communicate with STAF.

STAF PING PING PING

What result do you get? ___________________________________________________________
Why? ___________________________________________________________

STAF LOCAL VAR LIST

This command shows you all of the STAF variables on your machine.
What command would you execute to list the configured STAF services (hint: the Service Service)? ___________________________________________________________

STAF LOCAL SERVICE LIST REQUESTS

This commands lists all of the executing requests (you should only see the "list requests" request).

STAF LOCAL HANDLE LIST HANDLES

This command lists all of the current STAF handles.

STAF LOCAL HANDLE LIST HANDLES

Compare this with the output from the previous command. What are the differences?

STAF LOCAL PROCESS LIST

This command lists all of the current STAF Processes.

STAF LOCAL PROCESS START COMMAND NOTEPAD

This command starts the Notepad Process.

STAF LOCAL PROCESS LIST

This command lists all of the current STAF Processes. Note that you should see the Notepad process. Now, close the Notepad window.

STAF LOCAL PROCESS LIST

This command lists all of the current STAF Processes. What is the RC of the Notepad process?

STAF LOCAL LOG HELP

This command displays the Help for the Log Service.

STAF LOCAL HELP ERROR [Error Number]

This command displays the Help for the specified error number.

STAF LOCAL SHUTDOWN SHUTDOWN

This command will shutdown staf.

STAF LOCAL PING PING

What do you get as the result? ___________________________________________________________
Why did you get this? ___________________________________________________________
Now restart STAFProc

STAF LOCAL PING PING

STAF LOCAL HELP ERROR 21

STAF LOCAL VAR RESOLVE STRING {STAF/Config/MachineNickname}

This command displays the value of variable STAF/Config/MachineNickname

STAF LOCAL LOG LOG MACHINE LOGNAME log1 LEVEL info message test-message

This command creates machine log (associate with the MachineNickname) called log1 and writes an informational message to the log.

STAF LOCAL LOG LIST MACHINES

This command list the machines for which machine log exist. Notice that it shows the MachineNickname.

STAF LOCAL LOG QUERY MACHINE xxx.austin.ibm.com LOGNAME log1

Note: change "xxx" to your hostname. This command queries the machine log named log1. Note that you need to specify the hostname for the "MACHINE" option. Now, add the following to your STAF.cfg file:
```
MACHINENICKNAME testmachine1
```
and restart STAF.

STAF LOCAL VAR RESOLVE STRING {STAF/Config/MachineNickname}

This command displays the value of variable STAF/Config/MachineNickname (which should be "testmachine1").

STAF LOCAL LOG LOG MACHINE LOGNAME log2 LEVEL info message second-message

This command creates machine log (associate with the MachineNickname) called log2 and writes an informational message to the log.

STAF LOCAL LOG LIST MACHINES

This command list the machines for which machine log exist. Notice that it shows the MachineNickname testmachine1.

STAF LOCAL LOG QUERY MACHINE testmachine1 LOGNAME log2

Notice that now you can use the machine nickname for the MACHINE option.

STAF LOCAL MISC LIST INTERFACES

This command will list the network interfaces that are currently configured.
Which TCP/IP ports are being used? ___________________________________________________________
Which one is encrypted? ___________________________________________________________

Now try some of the commands, substituting a neighbor's machine hostname instead of "local" in the commands.

Exercise 1.4 - Adding a STAF variable

Objective - Learn how to use STAF variables via the command line and the STAF configuration file

From a command prompt type

staf local var set system var HandsOn/Variables/MyVar=xyz

Now type

staf local var resolve string {HandsOn/Variables/MyVar}

Verify that you get "xyz" as the result.

Now shutdown STAFProc and restart it.

Now type
```
staf local var resolve string {HandsOn/Variables/MyVar}
```
What is the result? ___________________________________________________________
Why do you get this result? ___________________________________________________________

Edit the C:\STAF\bin\STAF.cfg file and add the line "SET SYSTEM VAR HandsOn/Variables/MyVar=xyz". Save the changes to the STAF.cfg file.

Click on "Start" on the Windows task bar. Then click on "Shutdown STAF 3.4.4".

Click on "Start" on the Windows task bar. Then click on "Start STAF 3.4.4".

Type the command
```
staf local var list
```
and verify that HandsOn/Variables/MyVar=xyz is listed.

Type the command
```
staf local var help
```
to see the help for the Variable service.

Type the command

staf local var resolve string {HandsOn/Variables/MyVar}

and verify that the response is "xyz".

Click on "Start" on the Windows task bar. Then click on "Shutdown STAF 3.4.4".

Click on "Start" on the Windows task bar. Then click on "Start STAF 3.4.4".

Type the command
```
staf local var resolve string {HandsOn/Variables/MyVar}
```
and verify that the response is "xyz". Why is this variable still set to "xyz"?

Exercise 1.5 - Configuring a Java STAF Service

Objective - Install and Configure the EmailService

In the C:\STAF directory, create a services\email directory.

From the STAF/STAX CD, unzip /Part1/install/EmailV335.zip to C:\STAF\services

Click on "Start" on the Windows task bar. Then click on "Shutdown STAF 3.4.4".

Edit the C:\STAF\bin\STAF.cfg file and add the lines

service email library JSTAF execute C:/STAF/services/email/STAFEmail.jar \
    parms "mailserver na.relay.ibm.com"

Save the changes to the STAF.cfg file.

Click on "Start" on the Windows task bar. Then click on "Start STAF 3.4.4".

Type the command
```
staf local service list
```
and verify that the Email service is listed.

Type the command
```
staf local email version
```
and verify that the Email service version is 3.3.5.

Type the command
```
staf local email help
```
and verify that you get the Help for the email Service.

Use your favorite editor to examine the following file:

C:/STAF/data/STAF/lang/java/jvm/STAFJVM1/JVMLog.l

This file will contain any Java errors/exceptions that the Email service (and any other Java STAF services) encounters. The end of the file should be similar to:

******************************************************************************
*** 20110120-10:41:37 - Start of Log for JVMName: STAFJVM1
*** JVM Executable: java
*** JVM Options   : -Xmx1024m 
*** JVM Version   : java version "1.5.0_16"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_16-b02)
Java HotSpot(TM) Client VM (build 1.5.0_16-b02, mixed mode, sharing)
*** JVM PID       : 3764
******************************************************************************

Exercise 1.6 - Executing a simple Testcase

Objective - Execute a simple, non-STAF-enabled testcase via STAF

In the C:\STAF directory, create a testcases directory.

From the STAF/STAX CD, copy /Part1/testcases/SimpleTestcase.java to C:\STAF\testcases.

In the C:\STAF\testcases directory, type "javac SimpleTestcase.java".

From a command prompt, type

staf local process start command java parms "SimpleTestcase 10"
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases

You should notice that a new command prompt window has opened and it executing SimpleTestcase (it loops for 10 seconds and displays a message every second). Note that after the testcase completes, the command prompt window closes.

From a command prompt, type
```
staf local process list handles
```
What is the output? __________________________________________________________

From a command prompt, type
```
staf local process free handle XX
```
where XX is the handle that was listed in the process query all request

From a command prompt, type
```
staf local process list handles
```
What is the output now, and why has it changed? __________________________________________________________

Execute the process start command again, changing 10 to 30, and then, while the testcase is executing, type "staf local process list running". Notice that the process shows as "Running". After the process completes, run the process query command again, and note that the process shows as "Completed".

Exercise 1.7 - Executing a STAF-enabled Testcase

Objective - Executing a STAF-enabled testcase via STAF

From the STAF/STAX CD, copy /Part1/testcases/STAFTestcase.java to C:\STAF\testcases.

In the C:\STAF\testcases directory, type "javac STAFTestcase.java"

From a command prompt, type
```
staf local process start command java parms "STAFTestcase 60" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases
```
Note that after you execute the command, the response contains a number, which is the handle number for the STAFTestcase.

When you run the command, if a separate command window opens and then immediately closes, that indicates that was an error when running the command. Re-run the command again, but add
```
RETURNSTDOUT STDERRTOSTDOUT WAIT
```
at the end of the command. This will give you detailed information about the error.

Now type
```
staf local monitor help
```
to familiarize yourself with the Monitor service.

Type
```
staf local monitor query machine testmachine1 handle YY
```
substituting the handle number for STAFTestcase for YY. Notice that the response you get back is the current information (loop #) which the testcase is publishing. Execute this command several times to get the latest status of the testcase.

Exercise 1.8 - Enabling a Testcase with STAF (OPTIONAL: Requires Java programming skills)

Objective - Leverage STAF within the testcase by adding additional call to STAF services

1.8.1 - Adding Logging to a STAF-enabled Testcase

From a command prompt, type
```
staf local log help
```
to familiarize yourself with the Log Service commands.

In the C:\STAF\testcases directory, copy STAFTestcase.java to STAFTestcase1.java.

Edit STAFTestcase1.java. On line 2, change the class name to STAFTestcase1. In the for loop, after the submit call to the Monitor service, add another submit call to the Log service to log the same information that is published to the Monitor service. If you were submit this request via the command line, it would look like: staf local log log machine logname STAFTestcase1.log level info message "Loop #n".

In the C:\STAF\testcases directory, type "javac STAFTestcase1.java"

Type the command

staf local log list machine testmachine1

From a command prompt, type

staf local process start command java parms "STAFTestcase1 15" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases

After STAFTestcase1 executes, type the log list command again. You should now see the STAFTestcase1.log listed.

Now type

staf local log query machine testmachine1 logname STAFTestcase1.log

You should see 15 Loop # lines.

Now type

staf local log query machine testmachine1 logname STAFTestcase1.log last 5

You should see the last 5 lines in the log file.

1.8.2 - Using the Delay service in a STAF-enabled Testcase

In the C:\STAF\testcases directory, copy STAFTestcase1.java to STAFTestcase2.java.

Edit STAFTestcase2.java. On line 2, change the class name to STAFTestcase2. In the for loop, after the submit call to the Log service, add another submit call to the Delay service to have it delay for 1 second, and then remove the entire try/catch block for the Thread.sleep(1000) statement. Rather than using Thread.sleep, we are now using the STAF Delay service instead. Note that if you were executing the Delay command via the STAF executable, the syntax would be "staf local delay delay 1000".

In the C:\STAF\testcases directory, type "javac STAFTestcase2.java"

From a command prompt, type
```
staf local process start command java parms "STAFTestcase2 15" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases
```
You should see the testcase behaving as before, but it is now using the STAF Delay service to delay 1 second between each loop.

1.8.3 - Using the Var service in a STAF-enabled Testcase

From a command prompt, type
```
staf local var help
```
to familiarize yourself with the Var Service commands.

In the C:\STAF\testcases directory, copy STAFTestcase2.java to STAFTestcase3.java.

Edit STAFTestcase3.java. On line 2, change the class name to STAFTestcase3. Previously, this testcase would loop for the specified number of loops. Now let's have it check a STAF variable to see if it should continue execution. In the for loop, after the submit call to the Delay service, add a submit call to the Var service to check the value of the variable {HandsOn/Variables/MyVar} (this is the variable that we set to "xyz" in an earlier exercise). From the command line, this command would be "staf local var resolve string {HandsOn/Variables/MyVar}".

In STAFTestcase3.java, after the submit to the Var service, call add the following lines to determine if the testcase should terminate:
```
if ((varResult.rc == 0) && 
    (varResult.result.equals("STAFTestcase3/Terminate")))
{
    System.exit(0);
}
```
In the C:\STAF\testcases directory, type "javac STAFTestcase3.java"

From a command prompt, type

staf local process start command java parms "STAFTestcase3 100" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases

Note the handle number given to the testcase.

As the testcase is running, type the command
```
staf local var handle YY set var HandsOn/Variables/MyVar=STAFTestcase3/Terminate
```
where YY is the handle number for STAFTestcase3.

When you execute this command, the testcase should terminate as expected.

1.8.4 - Using the Queue service in a STAF-enabled Testcase

From a command prompt, type
```
staf local queue help
```
to familiarize yourself with the Queue Service commands.

In the C:\STAF\testcases directory, copy STAFTestcase1.java to STAFTestcase4.java.

Edit STAFTestcase4.java. On line 2, change the class name to STAFTestcase4. Now, once again remove the entire try/catch block for the Thread.sleep(1000) statement. In this exercise, instead of using the Delay service and the Var service for notification when the testcase should terminate, we will use the Queue service.

In STAFTestcase4.java, after the submit call to the Log service, add a call to the Queue service to run the "get" command. Specify the "wait 1000" option. This will cause the testcase to check its queue for any messages, and will wait for 1 second before continuing to the next loop. After the call to the Queue service, add the following lines to determine if the testcase should terminate:
```
if ((queueResult.rc == 0) && !(queueResult.result.equals(null)))
{
    STAFQueueMessage message = new STAFQueueMessage(queueResult.result);
    if (message.message.equals("STAFTestcase4/Terminate"))
    {
        System.exit(0);
    }
}
```
In the C:\STAF\testcases directory, type "javac STAFTestcase4.java"

From a command prompt, type

staf local process start command java parms "STAFTestcase4 100" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases

Note the handle number given to the testcase.

As the testcase is running, type the command
```
staf local queue queue handle YY message STAFTestcase4/Terminate
```
where YY is the handle number for STAFTestcase4.

When you execute this command, the testcase should terminate as expected.

Exercise 1.9 - Starting a process on a remote machine

Objective - Learn how to execute a process on a remote system

Work with a neighbor on this exercise. Find out the hostname of your neighbor's machine.

From a command prompt, type

staf XX process start command java parms "STAFTestcase4 100" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases

where XX is the hostname of your neighbor's machine.

You should get a return code 25. Type "staf local help error 25". This means that you don't have access to run the process on your neighbor's machine.

From a web browser, go to "staf.sourceforge.net", and click the "Documentation" link, and then click on STAF V3 User's Guide. Section 8.11 describes the Process service. Note that in section 8.11.2, where the PROCESS START command is described, under the "Security" section it states this command requires Trust level 5.

From a command prompt, type
```
staf XX trust list
```
where XX is the hostname of your neighbor's machine. Your machine's is not listed, and the Default Trust level is 3.

Now have your neighbor shutdown STAFProc. Next your neighbor should edit their C:\STAF\staf.cfg file, and add the statement "TRUST LEVEL 5 MACHINE ZZ" where ZZ is your machine's hostname. Have your neighbor save their changes to the staf.cfg file, and then restart STAFProc on their machine.

Now try the command again from your machine
```
staf XX process start command java parms "STAFTestcase4 100" 
    env CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases
```
where XX is the hostname of your neighbor's machine. This time the testcase should successfully start. Note the handle number given to the testcase.

As the testcase is running, type the command
```
staf XX queue queue handle YY message STAFTestcase4/Terminate
```
where XX is the hostname of your neighbor's machine and YY is the handle number for STAFTestcase4.

When you execute this command, the testcase should terminate as expected.

Now re-run this exercise with you and your neighbor reversing roles.

Exercise 1.10 - Using the Process, FS, and Log services

Objective - Learn how to use the Process, FS, and Log services

Run the following command:
```
staf local process start shell command "java -version" stderrtostdout returnstdout wait
```
The result should contain the version information for the Java installed on your machine.

Run the following command:
```
staf local fs list directory {STAF/Config/STAFRoot}/bin
```
The result should contain contents of the STAF bin directory.

Run the following commands:

staf local log log machine logname log3 level info message test-message

staf local log log machine logname log3 level info message "Another message"

Now query the log:

staf local log query machine {STAF/Config/MachineNickname} logname log3

The result should contain the 2 records in the log.

Exercise 1.11 - Tracing and Debugging

Objective - Learn how to trace and debug STAF

Run the following command to see the help for the trace service
```
staf local trace help
```
Run the following command to turn on tracing every time a service request is initiated, and every time a service request completes:

staf local trace enable tracepoints "servicerequest serviceresult"

Run the following command

staf local ping ping

Now check the STAFProc window, and you should see the trace output. If you were running a lot of STAF requests, you can imagine that there could potentially be a lot of trace output, so you may want to limit which services to trace (by default all services will be traced).

Run the following command to turn off tracing for all services:

staf local trace disable all services

Now run the ping command again:

staf local ping ping

Now check the STAFProc window, and you should not see the trace output for that request.

Next let's turn on tracing for the Process service:

staf local trace enable service process

Run the following command

staf local process start shell command time returnstdout wait

Now check the STAFProc window, and you should see the trace output for the process service.

Next run the following command to turn off tracing:

staf local trace disable all services