STAF Hands-On Class Exercises

Pre-requisites

It is recommended that you run these exercises on a Windows 2000/XP machine. At least 50MB of hard drive space is required for the exercises.

It is recommended that you have network connectivity on the machine where you will be running the exercises (only exercise 9 requires network connectivity).

Install Java 1.3 SDK or later on the machine where you will be running the exercises. Installing a JRE is *NOT* sufficient. You must install an SDK so that the Java compiler will be available. Do not install Java to C:/Program Files/... Instead install it to a directory like c:/ibmsdk1.4.1. To verify that you have an SDK, must sure the "javac.exe" file exists in c:/ibmsdk1.4.1/bin

Add the following to your machine's System PATH environment variable:
```
c:\ibmsdk1.4.1\jre\bin;c:\ibmsdk1.4.1\bin
```
If you have User environment variables for PATH and/or CLASSPATH, ensure that they have references to the System PATH/CLASSPATH:
```
c:\abc\xyz;%PATH%
c:\abc\xyz;%CLASSPATH%
```
Create a directory on the machine where you will be running the exercises called "c:\STAFCD". Download the education package to this directory and unzip the file (by using PKZip or WinZip). The education package can be downloaded from: http://prdownloads.sourceforge.net/staf/STAF-STAX-HandsOn-Education-262.zip

If you have a c:\winnt\system32\java.exe file, rename it or remove it for the class.

Print a copy of the STAF exercises (c:\STAFCD\staf\exercises\win32\STAFExercises.html) and the STAX exercises (c:\STAFCD\stax\exercises\win32\STAXExercises.html) and bring these printouts to the class.

Exercise 1 - Installing STAF

Objective - Install STAF on your machine

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

On the Welcome panel, click on Next.

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

On the Setup Type panel, accept the default type of Typical and click on Next. Note that if you are installing STAF on a non-English system, you need to select "Custom" install, click on Next, and then select "Install additional codepages".

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

On the Program Folder panel, accept the default and click on Next.

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

Click on Next for the next 2 panels.

Exercise 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 STAFProc". You should see a new window open titled "Start STAF" with the text "STAFProc version 2.6.2 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 STAFProc". 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 STAFProc".

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 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 QUERY ALL

This command lists all of the current STAF handles.

STAF LOCAL HANDLE QUERY ALL

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

STAF LOCAL PROCESS QUERY ALL

This command lists all of the current STAF Processes.

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

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

Exercise 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 global set HandsOn/Variables/MyVar=xyz

Now type

staf local var resolve {HandsOn/Variables/MyVar}

Verify that you get "xyz" as the result.

Now shutdown STAFProc and restart it.

Now type
```
staf local var resolve {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 "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 STAFProc".

Click on "Start" on the Windows task bar. Then click on "Start STAFProc".

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 {HandsOn/Variables/MyVar}
```
and verify that the response is "xyz".

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

Click on "Start" on the Windows task bar. Then click on "Start STAFProc".

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

Exercise 5 - Configuring a Java STAF Service

Objective - Install and Configure the EventService

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

From the STAF/STAX CD, copy /stax/install/STAFEvent.jar to C:\STAF\services

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

Edit the C:\STAF\bin\STAF.cfg file and add the line
```
service event library JSTAF execute C:/STAF/services/STAFEvent.jar
```
Save the changes to the STAF.cfg file.

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

Type the command

staf local service list

and verify that the Event service is listed.

Type the command

staf local event version

and verify that the Event service version is 1.3.1.

Type the command

staf local event help

and verify that you get the Help for the Event Service.

Use your favorite editor to examine the following file:

C:/STAF/data/JSTAF/STAFJVM1/JVMLog.l

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

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

Exercise 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 /staf/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 query all
```
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 query all
```
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 query all". 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 7 - Executing a STAF-enabled Testcase

Objective - Executing a STAF-enabled testcase via STAF

From the STAF/STAX CD, copy /staf/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.

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

Type
```
staf local monitor query machine XX handle YY
```
substituting your machine's hostname for XX and 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 8 - Enabling a Testcase with STAF (OPTIONAL: Requires Java programming skills)

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

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 XX
```
where XX is your machine's hostname.

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 XX logname STAFTestcase1.log
```
where XX is your machine's hostname. You should see 15 Loop # lines.

Now type
```
staf local log query machine XX logname STAFTestcase1.log last 5
```
where XX is your machine's hostname. You should see the last 5 lines in the log file.

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.

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 {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 HandsOn/Variables/MyVar=STAFTestcase3/Terminate
```
where YY is the handle number for STAFTestcase3.

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

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 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 "Documents" link, and then click on STAF User's Guide. Section 8.10 describes the Process service. Note that in section 8.10.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 10 - Setting up and Running the STAF Demo (OPTIONAL)

Objective - Learn how to setup and run the STAF Demo

You can get a thorough explanation of the STAFDemoController and STAFProcess source code by going to the staf.sourceforge.net website, clicking on the "Documents" link, and then selecting "Getting Started with STAF".

The STAF Demo is located in C:\STAF\samples\demo. There should be a STAFDemo.jar file, as well as 2 java files: STAFDemoController.java and STAFProcess.java. STAFDemo.jar should already be in the machine's System CLASSPATH.

From a command prompt, type "java STAFDemoController". STAFDemoController is the program that drives the demo. You should see a dialog open titled "STAF Demo Controller".

Notice that the Machine name is the hostname of your machine.

Now click on the Start button. You should see 2 windows open: "Machine xx: Handle n" and "An Arbitrary Process: Handle n". Note that the windows may overlap so you may need to move the top panel to see the bottom panel.

The first dialog ("Machine:....") is the Control window, and the second dialog ("An Arbitrary Process...") is the sample application (STAFProcess). The sample application will loop indefinitely. Note that the titles of the sections in the Control window ("Queue/Semaphore", "Variable", "Monitor", "Log/Variable") indicate which STAF services are being utilized. At this point both the Control window and the application are running on the same local machine.
In the Control window, notice that the "background color to" combo box is set to "Blue". Select "Yellow" and click on the Set button. You should see the update to the sample application on your machine.

Note how we are able to change the behavioral characteristics of the application without needing to stop and start the application. At the top of each loop, the application simply checks the value of a STAF variable that defines what its background color should be. This is easily extended to any other type of dynamic information that you would like to be able to change while the application is executing.

Click the "Pause" button in the Control window. You should see that the application is no longer be incrementing its loop counter.

Click "Continue" in the Control window and note that the application is continuing its execution. This is accomplished through the semaphore service. The application simply waits on an event semaphore at the top of its loop. This semaphore is normally posted, so the application simply falls on through. When you clicked "Pause", this reset the event semaphore, which caused the application to wait for it to be posted. Clicking "Continue" causes the event semaphore to be posted, which enables the application to continue execution.

The Monitor service allows applications to publish their current status. Look at the "Timestamp:" and "Status:" fields in the "Monitor" group. You should see the information updated every few seconds. Note, you can determine where, in execution, the application is, without needing to actually look at the application display. This is particularly useful when the systems running the applications are not "conveniently" located. In order to do this, the application simply logs occasional messages via the Monitor service.

Click "Refresh Totals" in the Control window. You should see that the number of "Error" log messages has increased.

Click "Display Log" and you should see a new window which contains all the logged error messages.

Select the "Warning", "Info", and "Debug" checkboxes in the Control window and, then, click on "Set Log Mask".

Now wait for about 30 seconds, and, then, click "Refresh Totals". You should now see that the totals for all the logging levels have increased.

Click "Display Log" and you should see the other types of log messages at the end of the display. This is an example of the dynamic level masking of the STAF Log service. This allows you to define (and change) during runtime the types of messages that are actually being logged into the log file. Note that throughout its execution, the application is actually requesting messages to be logged for all 4 types of logs. However, since the log mask was originally set to only "Error", the Log service only wrote "Error" messages to the log. This allows you to have robust logging built into your application, while at the same time being able to dynamically, without changing the application or starting/stopping it, adjust how much information is written to the log.

Click "Clear Log" and you should see all the log totals reset to zero. You have just purged the log, even though the application is still logging data.

Now, go back to the main control window and start two more STAFProcess applications running on the remote machine. Be sure to change their background colors so that you can distinguish between them. At this point you should have 3 STAFProcess applications running on your machine.

Since there are initially only two resources available, you should notice that only two out of the three applications will be using a resource at any one time; the other application will be waiting for a resource. This is because each application needs a "resource" in order to continue execution. Periodically, the applications give up their resource and try to acquire a new one. Thus, you should see the applications swapping these two resources amongst themselves.

Now, from the main controller window, click the "+" button to the right of "Number of resource".

This will add another resource for the applications. You should now see all three applications using resources simultaneously.

Finally, go to one of the application control windows and click the "Stop" button.

This will send a message to the application's STAF queue. The application will check this at the top of its loop and terminate gracefully. You should see the application terminate. You should also see the monitor "Status:" display "terminating...". Note, you are still able to retrieve the monitor and log information even after the application has finished.

This is the end of the demo. You can click the "Stop" buttons on the other application controller windows to terminate those applications, and then close the "STAF Demo Controller" window.

Exercise 11 - Creating a Custom STAF service (OPTIONAL: Requires Java programming skills)

From the STAF/STAX CD, copy /staf/services/SampleService.java to C:\STAF\services.

In the C:\STAF\services directory, type "javac SampleService.java".

Add C:\STAF\services to your System CLASSPATH (note that usually you would create a Jar file for your service, and use the Jar file syntax when configuring the service in the STAF.cfg file).

Shutdown STAFProc on your machine. Edit C:/STAF/staf.cfg and add the line
```
service SampleService library JSTAF execute SampleService
```
Save the cfg file and restart STAFProc.

From a command prompt type "staf local service list" and verify that SAMPLESERVICE is now listed.

Type the command "staf local sampleservice version" and verify that you get the expected output.

Type the command "staf local sampleservice help" and verify that you get the expected output.

Type the command "staf local sampleservice list" and verify that you get the expected output.

Type the command "staf local sampleservice list printers" and verify that you get the expected output.

Type the command "staf local sampleservice list modems" and verify that you get the expected output.

Type the command "staf local sampleservice list widgets" and verify that you get an appropriate error message.

Type the command "staf local sampleservice query" and verify that you get an appropriate error message.

Type the command "staf local sampleservice query printer" and verify that you get an appropriate error message.

Type the command "staf local sampleservice query printer epson" and verify that you get the expected output.

Type the command "staf local sampleservice query modem" and verify that you get an appropriate error message.

Type the command "staf local sampleservice query modem lucent" and verify that you get the expected output.

From the C:\STAF\services directory, copy SampleService.java to SampleService1.java.

Edit SampleService1.java. Add an ADD and a DELETE option to the service, to Add and Delete both printers and modems. An ADD request should require a Trust level of 3, and a DELETE request should require a Trust level of 4. You don't need to actually implement any Add/Delete functionality; just do a System.out.println("Adding printer...."). SampleService1 should accept the following requests:
```
LIST    [PRINTERS] [MODEMS] 
QUERY   PRINTER  | MODEM  
ADD     PRINTER  | MODEM  
DELETE  PRINTER  | MODEM  
VERSION 
HELP 
```
You will need to add a fAddParser and fDeleteParser, and create methods handleAdd and handleDelete. Be sure to update handleHelp to include the Add and Delete options. Compile the service by typing "javac SampleService1.java".

Shutdown STAFProc on your machine. Edit C:\STAF\staf.cfg and add the line "service SampleService1 library JSTAF execute SampleService1". Restart STAFProc.

From a command prompt type "staf local service list" and verify that SAMPLESERVICE1 is now listed.

Type the command "staf local sampleservice1 help" and verify that you get the expected output.

Type the command "staf local sampleservice1 add" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 add printer" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 add printer epson" and verify that you get the expected output.

Type the command "staf local sampleservice1 add modem" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 add modem lucent" and verify that you get the expected output.

Type the command "staf local sampleservice1 delete" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 delete printer" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 delete printer epson" and verify that you get the expected output.

Type the command "staf local sampleservice1 delete modem" and verify that you get an appropriate error message.

Type the command "staf local sampleservice1 delete modem lucent" and verify that you get the expected output.