STAX Hands-On Class Exercises

Important Notes:

  1. The STAX Exercises assume that drive D: is your CD-ROM drive (or the drive where the STAX directory containing information for this class has been copied). If not, substitute your the correct drive letter whenever you see D: specified.

  2. The STAX Exercises assume that some of the STAF Exercises have been performed, including:


Exercise 12 - Installing the STAX Service

Objectives:

  1. Learn how to install and configure the STAX Service, assuming that STAF has already been installed with the Log and Event Services registered.
  2. Learn how to verify that the STAX Service is correctly configured.
  3. Learn how to start the STAX Monitor for the first time.

Steps:

  1. Install the STAX Service:

    1. Make a directory called services in C:\STAF.
      C:
      cd \STAF
      mkdir services      (This directory may already exist.)
      
    2. Unzip the STAXV1521.zip file into C:\STAF\services:
      cd services
      D:\stax\tools\unzip D:\STAX\install\STAXV1521.zip
      
  2. Assumes Java 1.3.1 has been installed in the C:\jdk1.3.1 directory and that C:\jdk1.3.1\bin is in the system PATH as part of the initial setup of the systems. Type the following to verify:
    java -version
  3. Assumes the Event Service has already been installed into C:\STAF\services, and the Event Service has been configured in the STAF.cfg file by performing STAF Exercise 5.

  4. Configure the STAX Service:

    1. Edit the STAF configuration file by typing:
      notepad C:\STAF\bin\STAF.cfg
      
    2. Register the STAX Service by adding the following line to the end of the file:
      service stax library JSTAF execute c:/staf/services/STAX.jar

    3. Save and exit editing the STAF.cfg file.

  5. Stop STAF if it is already running:
    STAF local SHUTDOWN SHUTDOWN
  6. Start STAF by typing the following and making sure no error messages are displayed in the STAFProc window:
    STAFProc
  7. Verify the LOG, EVENT, and STAX services are listed as services, along with many other services, by typing:
    STAF local SERVICE LIST
    
  8. Do a STAX HELP request to list the request syntax supported by the STAX Service:
    STAF local STAX HELP
    Verify that you see the following:
    Response
    --------
    STAX Service Help:
    
    EXECUTE   < <FILE <xml file name> [MACHINE <machine name>]> | DATA <xml data> >
              [JOBNAME <Job Name>] [FUNCTION <Function ID>] [ARGS <Arguments>]
              [SCRIPTFILE <file name>... [SCRIPTFILEMACHINE <machine name>]]
              [SCRIPT <Python code>]... [CLEARLOGS]
              [ HOLD | TEST | WAIT [Timeout] [RETURNRESULT] ]
    
    GET       DTD
    
    LIST      JOBS | JOB <Job ID> <THREADS | PROCESSES | STAFCMDS | 
                                   SUBJOBS | BLOCKS | TESTCASES>
    
    QUERY     JOB <Job ID> [THREAD <Thread ID> | PROCESS <Location:Handle> |
                            STAFCMD <Request#> | BLOCK <Block Name> | 
                            TESTCASE <Test Name>]
    
    HOLD      JOB <Job ID> [BLOCK <Block Name>]
    
    RELEASE   JOB <Job ID> [BLOCK <Block Name>]
    
    TERMINATE JOB <Job ID> [BLOCK <Block Name>]
    
    UPDATE    JOB <Job ID> TESTCASE <Testcase name> STATUS <Status>
              [MESSAGE <Message text>] [FORCE]
    
    VERSION
    
    HELP
    
  9. Do a STAX VERSION request:
    STAF local STAX VERSION
    What is the version? ________________

  10. 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 STAX 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 
    ****************************************************************************** 
    

  11. Start the STAX Monitor:

    1. Type the following:
      java -jar C:/STAF/services/STAXMon.jar
      
    2. The first time you start the STAX Monitor, the "STAX Monitor Properties" window will be displayed.

    3. The STAX and Event service machines default to your local system. Click on the "Save" button to save as the default settings should be correct.

    4. The "STAX Job Monitor" panel should be displayed. It displays information about all running and/or monitored jobs (but since no jobs have been started yet, no jobs will be listed in the table now). It also allows you to launch new jobs, monitor existing jobs, and terminate jobs.

Exercise 13 - Starting the STAX Monitor and Running a Job

Objectives:

  1. Learn how to use the STAX Monitor to run a job, monitor it's progress, and view its job logs.

Steps:

  1. Start the STAX Monitor by typing the following (if it's not already started):
    java -jar C:/STAF/services/STAXMon.jar
    
  2. Run a sample STAX Job via the STAX Monitor:

    1. Click on the "Submit New Job..." button to submit a new STAX Job.

    2. The "STAX Job Parameters" panel should be displayed. In the "XML Job File" section, leave "local machine" selected and set the "Filename" to C:\STAF\services\samples\sample1.xml (you can type this file name or click on the "Browse" button to use the file browser function to select it). Note that this is a sample STAX XML document provided with the STAX service. Click on "Yes" for the "Clear Logs" option (so that the STAX Job and Job User logs will be deleted before the job is executed).

    3. Click on the "Submit New Job" button to run the job.

    4. A "STAX Job Monitor" window should be displayed. The sample job runs for 2 minutes.

      What is its Job ID? _______
      Hint: It is a number displayed in the STAX Job Monitor panel's title.

    5. While the job is running, once a process called TestProcess appears in the "Active Job Elements" panel, select it to display information about it in the "Current Selection" panel.

      What is its Command value? _____________________
      What is its Parms value? ________________________________________

    6. While the job is running, right mouse click on a block named 'local_1" in the "Active Job Elements" panel, and click on "Hold" to hold the block. The block icon should turn red and the block icons of the block nested within it should turn yellow.

    7. Release the block you held. Its block icon should turn green (as well as the nested block icon).

    8. When the job completes (after running for 2 minutes), check the "Testcase Info" panel.

      How many tests ran successfully and how many tests failed?
      PASS: ________ FAIL: __________

      The number of passes and fails recorded within the 2 mintues could vary based on the speed of your system.

    9. Browse the "Messages" panel. The last message should be:
      Test complete - ran for 120 seconds
      It may show a slightly different value for seconds (e.g. 121), depending on your system.

  3. Display the STAX Job Log for this job:

    1. Query the STAX Job Log for the job you just ran by selecting "Display" from the menu bar and then select "Display Job Log".
    2. Note that a "Start" message is logged containing the File name specified and other job start information.
    3. Note that there are some "Info" messages logged whenever a block is held or released.
    4. Note that there are some "Fail" and "Pass" messages logged for each testcase that specified some status information.
    5. Note that there is a "Status" message logged summarizing for each Testcase, its total number of passes and failures.
    6. Note that the last "Status" message logged summarizes the total number of Testcases ran in this job and the total number of testcase passes and failures. These Pass and Fail totals should match the numbers you noted when monitoring the job.
    7. Note that a "Stop" message is logged for the job.
    8. Close the window displaying the STAX Job Log by selecting "File" from the menu bar and then select "Exit".

  4. Close the STAX Job Monitor window (the one that shows the results for the job you just ran).

Exercise 14 - Using STAX Command Line Requests

Objectives:

  1. Learn how to run a sample job via a STAX command line request instead of via the STAX Monitor.
  2. Learn how to get information about a running job via STAX LIST and QUERY command line requests.
  3. Learn how to use the Log Service to query the results of a STAX job.

Steps:

  1. Use the STAX EXECUTE command line request specifying to run the job defined by the STAX XML document in file C:\STAF\services\samples\sample1.xml. Specify a job name of "Sample Job".

    Hints:

    What is its Job ID? _______

    Hint: It is the number displayed in the Response from the STAX EXECUTE request.

  2. Use the STAX LIST JOBS command line request to list all jobs running. Information about the job you just started should be displayed, including job name "Sample Job".

    Hints:

  3. Use the STAX LIST JOB command line request to list all blocks currently running in the job.

    Hint:

    How many blocks are currently running? _________

  4. Use the STAX LIST JOB command line request to list all threads currently running for this job

    Hint:

    How many threads are currently running? _________
    Write down the thread ID of each thread currently running: __________________________

  5. Use the STAX QUERY command line request to show general information about the job currently running, including "Start Time" and "Blocks Running".

    Hint:

    How many blocks are currently running? __________
    How many blocks are currently held? __________

  6. Use the STAX QUERY command line request to query more information about a thread currently running in the job.
    Hint: Look at the STAX QUERY request syntax again. You are going to use the JOB and THREAD options.
    STAF local STAX QUERY JOB <Job ID> THREAD <Thread ID>
    Replace <Job ID> with the Job ID number you recorded in an earlier step and replace with one of the thread IDs shown in a previous step where you listed all the threads.

    Write the thread's call stack here:




  7. Use the LOG service to check the STAX Job Log for this STAX job that you just ran:

    1. Query the STAX Job Log for the job you just ran by typing the following, replacing <Machine> with the host name of your machine and replacing <JobID> with the Job ID number that you noted in the previous step when running the job:
      STAF local LOG QUERY MACHINE <Machine> LOGNAME STAX_Job_<JobID>
    2. Note that a "Start" message is logged containing the File name specified and other job start information.
    3. Note that there are some "Info" messages logged whenever a block is held or released.
    4. Note that there are some "Fail" and "Pass" messages logged for each testcase that specified some status information.
    5. Note that there is a "Status" message logged summarizing for each Testcase, its total number of passes and failures.
    6. Note that the last "Status" message logged summarizes the total number of Testcases ran in this job and the total number of testcase passes and failures. These Pass and Fail totals should match the numbers you noted when monitoring the job.
    7. Note that a "Stop" message is logged for the job.

Exercise 15 - Create a Simple STAX Job and Run it

Objectives:

  1. Learn how to create a simple STAX XML document that runs a non-STAF enabled testcase and checks its return code to determine if it ran successfully and sends a message to the STAX Monitor (and logs the message) which says whether the testcase ran successfully.
  2. Learn how to change how a testcase runs (without editing the XML document) by passing different variables to it via the Script option.

Steps:

  1. Note: This exercise requires that you completed STAF Exercise 6 so that SimpleTestcase.class exists in your C:\STAF\testcases directory (as well as .; has been added to the system CLASSPATH).

  2. Make a directory called xml in C:\STAF and change to this directory. This directory (C:\STAF\xml) is where you will put your xml files that define STAX jobs.

  3. Copy D:\stax\exercises\exercise15\*.* to C:\STAF\xml as follows:
    COPY D:\stax\exercises\exercise15\*.* C:\STAF\xml\*.*
  4. Use an editor (e.g. notepad) to view file simple1.xml in directory C:\STAF\xml. This STAX XML document demonstrates a simple STAX job that runs a Java testcase called SimpleTestcase on the local machine. It looks like the following:
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <!DOCTYPE stax SYSTEM "stax.dtd">
    
    <stax>
    
      <defaultcall function="Main"/>
    
      <script>numLoops = 10</script>
    
      <function name="Main">
    
          <sequence>
     
            <process>
              <location>'local'</location>
              <command>'java'</command>
              <parms>'SimpleTestcase %s' % numLoops</parms>
              <env>'CLASSPATH={STAF/Env/Classpath};C:/STAF/testcases'</env>
           </process>
    
           <if expr="RC == 0">
             <sequence>
               <message>'Completed %s loops' % numLoops</message>
               <log>'Completed %s loops' % numLoops</log>
             </sequence>
             <else>
               <sequence>
                 <message>'Failed with RC=%s' % RC</message>
                 <log>'Completed %s loops' % numLoops</log>
               </sequence>
             </else>
           </if>
    
         </sequence>  
    
      </function>
    
    </stax>
  5. Save the file.

  6. Start the STAX Monitor by typing:
    java -jar c:/STAF/services/STAXMon.jar
  7. Click on the "Submit New Job..." button.

  8. Enter the following information:
    Job Name:  Simple Job
    Filename:  C:\STAF\xml\simple1.xml
  9. Click on the "Test" button to verify that the XML document is valid. You should get a "Validation Successful" popup message. If you don't, then you have a typo in the document. The error message displayed should point you to the line in error. Edit the XML document and fix the problem and retest.

  10. Click on the "Submit New Job" button to start the job.

  11. While the job is running:

    1. What is its Job ID? _______
      Hint: It is a number displayed in the STAX Job Monitor panel's title.

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

    3. Note that in the "Active Job Elements" panel (in the Job Monitor window), you should see a process named Process1 running for 10 seconds. To the right of it, you should see its elapsed time is displayed (and continually updated). To the right of the elapsed time, you should see a message <No STAF Monitor information available>. This is because the testcase itself that is running is not STAF enabled and thus, is not using the STAF Monitor service to log its current status.

  12. When the job completes:

    1. Verify the "Messages" section displays "Completed 10 loops".

    2. Verify the STAX Job User log contains an "Info" message that 10 loops were performed by selecting "Display" from the menu bar and then select "Display Job User Log". After verifying this, close the window displaying the Job User Log.

  13. Run the same STAX XML file again, this time changing the value of numLoops from 10 to 30. Note that you can do this without editing the XML file by adding a Script option containing:
    numLoops = 30
    before submitting the job.

  14. While the job is running:

    1. What is its Job ID? _______
      Hint: It is a number displayed in the STAX Job Monitor panel's title.

    2. You should notice that a new command prompt window has opened and is executing SimpleTestcase (it loops for 30 seconds and displays a message every second). When the testcase completes, this command prompt window closes.

  15. When the job completes:

    1. Verify the "Messages" section displays "Completed 30 loops".

    2. Verify the STAX Job User log contains an "Info" message that 30 loops were performed by selecting "Display" from the menu bar and then select "Display Job User Log". After verifying this, close the window displaying the Job User Log.

Exercise 16 - Create Another Simple STAX Job and Run it

Objectives:

  1. Learn how to create a simple STAX XML document that runs a STAF enabled testcase which updates its current status using the Monitor Service.
  2. Understand how the STAX Monitor displays the current status of a testcase when it uses the STAF Monitor service.

Steps:

  1. Note: This exercise requires that you completed STAF Exercise 7 so that STAFTestcase.class exists in your C:\STAF\testcases directory (as well as .; has been added to the system CLASSPATH).

  2. Copy C:\STAF\xml\simple1.xml to C:\STAF\xml\simple2.xml as follows:
    COPY C:\STAF\xml\simple1.xml C:\STAF\xml\simple2.xml
  3. Use an editor (e.g. notepad) to edit simple2.xml in directory C:\STAF\xml. Change the value of the process's <parms> element to contain:
    'STAFTestcase %s' % numLoops
    (replacing SimpleTestcase with STAFTestcase)

    Now it will run a Java testcase called STAFTestcase on the local machine. This testcase uses the STAF Monitor service to update its current status in the STAX Job Monitor while the testcase is running.

  4. Save the file.

  5. Start the STAX Monitor by typing:
    java -jar C:/STAF/services/STAXMon.jar
  6. Click on the "Submit New Job..." button.

  7. Enter the following information:
    Job Name:  Simple Job
    Filename:  C:\STAF\xml\simple2.xml
  8. Click on the "Submit New Job" button to start the job.

  9. While the job is running:

    1. What is its Job ID? _______
      Hint: It is a number displayed in the STAX Job Monitor panel's title.

    2. You should notice that it runs just like the sample1.xml job except for one thing. Note that in the "Active Job Elements" panel (in the Job Monitor window), you should see a monitor message that displays the current loop number (and is continually updated).

Exercise 17 - Debugging STAX Jobs

Objectives:

  1. Learn how to debug problems encountered when submitting and running STAX jobs.

Steps:

  1. Copy the xml files in directory D:\stax\exercises\exercise17 to C:\STAF\xml as follows:
    COPY D:\stax\exercises\exercise17\*.xml C:\STAF\xml\*.xml
  2. Debug some XML parser errors:

    1. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\debug1.xml. If it displays an error, find the error and edit the XML document to fix the problem, save it, and re-submit the job. Repeat until successful.

      What is the first error found and how did you fix it?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

      What is the second error found and how did you fix it?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

    2. When the job is successful and complete, it will display that three tests passed (0 failures) in the "Testcase Info" panel and the "Messages" panel.

  3. Debug some Python errors:

    1. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\debug2.xml If it displays an error, find the error and edit the XML document to fix the problem, save it, and re-submit the job. Repeat until successful.

      What is the first error found and how did you fix it?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

      What is the second error found and how did you fix it?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

      What is the third error found and how did you fix it?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

    2. When the job is successful and complete, it will display that three tests passed (0 failures) in the "TestCase Information" panel and the "Messages" panel.

  4. Debug some Process Start errors:

    1. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\debug3.xml If it displays an error, find the error and edit the XML document to fix the problem, save it, and re-submit the job. Repeat until successful.

      What are the errors found and how did you fix them?
      ______________________________________________________________________________________
      ______________________________________________________________________________________
      ______________________________________________________________________________________

    2. When the job is successful and complete, it will display that three tests passed (0 failures) in the "Testcase Info" panel and the "Messages" panel.

Exercise 18 - Modify a STAX Job to Release Machines from a Resource Pool

Objectives:

  1. Learn how to use imported functions.
  2. Learn how to iterate a Python list in STAX jobs.
  3. Learn how to use the Resource Pool service to allocate machines for use by a STAX job, run some tests, and then release the machines so that they are available for other tests.

Steps:

  1. Copy the xml files in directory D:\stax\exercises\exercise18 to C:\STAF\xml as follows:
    COPY D:\stax\exercises\exercise18\*.xml C:\STAF\xml\*.xml
  2. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\respool.xml

  3. After the job successfully completes, look at the "Messages" panel. It displays the results from querying the resource pool after 5 machines have been allocated from it. These results should look something like this, where 5 of the 10 machines are available and 5 of the 10 machines are owned.
    Description: Pool of test machines
    
    Pending requests: 0
    
    Resources:
    
    machine1;Available
    machine2;Available
    machine3;Owned;lucas;STAX/Job/48;235;20020510-14:20:55;20020510-14:20:55
    machine4;Owned;lucas;STAX/Job/48;235;20020510-14:20:56;20020510-14:20:56
    machine5;Available
    machine6;Available
    machine7;Available
    machine8;Owned;lucas;STAX/Job/48;235;20020510-14:20:56;20020510-14:20:56
    machine9;Owned;lucas;STAX/Job/48;235;20020510-14:20:55;20020510-14:20:55
    machine10;Owned;lucas;STAX/Job/48;235;20020510-14:20:56;20020510-14:20:56
    

  4. Edit C:\STAF\xml\respool.xml by inserting code into function 'ReleaseMachines' to release the machines that have been requested (allocated) from the resource pool, that are in Python list variable machineList.

  5. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\respool.xml again.

  6. After the job successfully completes, look at the "Messages" panel. The last query pool request should now displays results like the following the show that all 10 of the machines in the pool are available (now that you add the function to release them).
    Description: Pool of test machines
    
    Pending requests: 0
    
    Resources:
    
    machine1;Available
    machine2;Available
    machine3;Available
    machine4;Available
    machine5;Available
    machine6;Available
    machine7;Available
    machine8;Available
    machine9;Available
    machine10;Available
    

Exercise 19 - Execute and debug a STAX Job that executes several sub-jobs

Objectives:

  1. Learn how to the <job> element.
  2. Learn how to interact with sub-jobs in the STAX Monitor.

Steps:

  1. Copy the xml files in directory D:\stax\exercises\exercise19 to C:\STAF\xml as follows:
    COPY D:\stax\exercises\exercise19\*.xml C:\STAF\xml\*.xml

  2. Submit a STAX job using the STAX Monitor, specifying file C:\STAF\xml\subjob.xml. The purpose of this job is to execute 5 subjobs. The job should complete in 60 seconds.

  3. After the job successfully completes, look at the "Testcase Info" panel.

  4. Did all 5 testcases pass? If not, look in the "Messages" panel to see any additional information.

  5. Why did any failures occurs? (Hint: use "staf local help error rc#" )
    ______________________________________________________________________________________
    ______________________________________________________________________________________
    ______________________________________________________________________________________

  6. Correct the problem in the subjob.xml file, and click on the "Resubmit Previous Job" button. Verify that all 5 testcases now pass.

  7. Notice that in the "Active Job Elements" panel, when a subjob is started, the only information displayed in the tree is the subjob itself (with the yellow construction sign). You won't see any of the sub-job's processes, blocks, stafcmds, etc. To view the sub-job's active job elements, you can start monitoring that sub-job. Right-click the mouse on the sub-job in the Active Job Elements" panel, and click on "Start Monitoring". You should see a new STAX Monitor window open that show's all of the sub-job's activity.

  8. In the STAX Monitor window for subret.xml, click on the "Sub-jobs" tab. This tab shows all sub-jobs that have been executed by the subret.xml. You can view their log files by right-clicking on the sub-job's row in the table and select "Display Job Log" or "Display Job User Log". Notice that this table shows you the result that each sub-job returned.

  9. In the main STAX Monitor window, after the job completes you can see the result that subret.xml returned. Note that the result is also displayed in the title bar of the STAX Monitor window for the subret.xml job.