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

Exercise 4.1 - 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 C:\STAFCD\Part4\exercise4.1 to C:\STAF\xml as follows:

   COPY C:\STAFCD\Part4\exercise4.1\*.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.

Exercise 4.2 - Using STAXDoc

Objectives:

1. Learn how to use STAXDoc.

Steps:

1. Now let's create some STAXDoc documentation for the Part 4 sample jobs.
   
   
2. In a command prompt, go to C:\STAFCD\Part4, and run the following command:

   java -jar c:\STAF\services\STAX\STAXDoc.jar -d c:\STAXDoc\samples samples

3. This will create the STAXDoc documentation in the c:\STAXDoc\samples directory. Open a browser and navigate to this directory.
   
   
4. Open the index.html file. It will show you the documents that are available. Click on the link for "FunctionParameters.xml" (since this is one of the STAX job for which we included the <function> information).
   
   
5. The right side of the page shows the details about the function and its parameters.

Exercise 4.3 - Using STAX Extensions

Objectives:

1. Learn how to use STAX Extensions.

Steps:

1. In this exercise we will add the "Delay" extension. It provides <ext-delay>, <ext-wait>, and <ext-sleep> elements that can be used in your STAX jobs to delay for a specified number of seconds. In the STAX Monitor, these elements will be displayed in the "Active Job Elements" tree as progress bars.
2. Edit your STAF.cfg file and add

   PARMS "EXTENSION C:/STAFCD/Part4/extensions/ExtDelay.jar"

   to the STAX service configuration statement. This statement should now look like:

   service stax library JSTAF execute c:/staf/services/stax/STAX.jar \
       PARMS "EXTENSION C:/STAFCD/Part4/extensions/ExtDelay.jar"
   

3. Restart STAFProc on your machine.
4. Open your favorite text editor, and copy/paste the following STAX job:

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

<stax>

  <defaultcall function="test"/>
   
  <function name="test">     
  
   <parallel>
   
    <block name="'Block A'">
  
      <parallel>
        <stafcmd>
          <location>'local'</location>
          <service>'delay'</service>
          <request>'delay 10000'</request>
        </stafcmd>
        <ext-delay>20</ext-delay>
      </parallel>
      
    </block>
    
    <block name="'Block B'">

      <ext-sleep>30</ext-sleep>
      
    </block>
   
    <block name="'Block C'">

      <parallel>
        <ext-delay>10</ext-delay>
      </parallel>
      
    </block>
    
    <block name="'Block D'">

      <parallel>
        <ext-wait>8</ext-wait>
      </parallel>

    </block>

   </parallel>

  </function>

</stax>

5. Save the file and run it via the STAX Monitor. You should see 4 progress bars, representing the Delay elements, in the "Active Job Elements" tree. Also note that STAX extensions can provide aliases (you can use <ext-delay>, <ext-sleep>, or <ext-wait>, which all do the same thing).

Exercise 4.4 - Using STAX Breakpoints

Objectives:

1. Learn how to use STAX Breakpoints.

Steps:

1. Copy the xml files in directory C:\STAFCD\Part4\samples to C:\STAF\services\stax as follows:

   COPY C:\STAFCD\Part4\samples\*.xml C:\STAF\services\stax\*.*

2. Start the STAX Monitor, and click on the "Submit New Job..." button.
3. Click on the "Clear All Parameters" button.
4. In the "Job Info" tab, in the "Filename" field (for "local machine"), enter C:/STAF/services/stax/TestcaseDebug.xml (or use the "Browse..." button to select the TestcaseDebug.xml file).
5. In the "Breakpoints" tab, select the "Set breakpoint at first function" checkbox.
6. Click on the "Submit New Job" button.
7. In the STAX Job Monitor dialog for the STAX job, select the "Debug" tab. You should maximize the dialog, and use the vertical and horizontal sliders so that you can view all of the Debug tab content.
8. In the "Threads" tab, note that there is only 1 thread running, and it is at a breakpoint. Click on thread 1 in the "Threads tab". Notice that the lower 3 tabs ("Thread Variables", "Thread Info", and "XML File") now have information about the thread you just selected.
9. Note that the "XML File" tab is displaying the contents of the TestcaseDebug.xml file, and is scrolled to line 14 (the <function> element). This is because we selected the "Set breakpoint at first function" checkbox when submitting the job.
10. In the "Threads" tab, click on the "Step Into" button to step the breakpoint.
11. Note that the breakpoint is now at line 16 (the <sequence> element).
12. Click on "Step Into" repeatedly until the breakpoint is at line 29 (the <call> element).
13. Click on "Step Into" again. Notice that the "XML File" tab now shows the contents of file FunctionParametersLogging.xml and the breakpoint is at line 8 (the <function> element).
14. Click on "Step Into" repeatedly until the breakpoint is back in the TestcaseDebug.xml file at line 32 (the <if> element).
15. In the "Thread 1 Variables" tab, scroll down to the "callResult" entry. On line 30 of the TestcaseDebug.xml file, it sets variable callResult to the STAXResult variable (which contains the value returned from the function call, in this case the random number that was previously generated).
16. Click on "Step Into" repeatedly until the breakpoint is at line 25 (the <sequence> element).
17. Next click on the "Step Over" button. Nntice that the all of the tasks within the <sequence> are executed, and the next breakpoint is at line 23 (the <testcase> element).
18. Click on the "Resume" button. The job will complete.
19. In the main STAX Job Monitor dialog, click on the "Resubmit Previous Job" button.
20. In the STAX Job Monitor dialog for the STAX job, select the "Debug" tab. You should maximize the dialog, and use the vertical and horizontal sliders so that you can view all of the Debug tab content.
21. In the "Breakpoints" tab, click on the "Add Breakpoint Line..." button.
22. In the "Line Number" field, enter 32, and leave the other fields blank. Click on the "Add" button.
23. Select thread 1, and click on the "Resume" button.
24. The breakpoint should now be in the TestcaseDebug.xml file at line 32 (the <if> element).
25. In the "Thread 1 Variables" tab, scroll down to the "callResult" entry. On line 30 of the TestcaseDebug.xml file, it sets variable callResult to the STAXResult variable (which contains the value returned from the function call, in this case the random number that was previously generated).
26. For this exercise, we want to change the callResult variable so that all 10 testcases will fail. If the value for variable callResult is less than or equal to 50, then in the "Execute Python Code in Current Thread" text field, type "callResult = 99" (without the double quotes), and click on the "Execute" button. If you clicked on the "Execute" button, verify that you get a popup dialog indicating that the update was successful (RC = 0), and that the callResult variable is now set to 99. Click on the "Resume" button to resume the thread.
27. Repeat the previous step for the remaining 9 testcases, using the "Execute" button to change the callResult value to 99 if it is less than or equal to 50.
28. After the job completes, in the "Testcase Info" tab, verify that it shows 0 Passes and 10 Fails.
29. Note that the only difference between the Testcase.xml job and the TestcaseDebug.xml job is that the following line was added at line 30:

    <script>callResult = STAXResult</script>
    

    and line 32 was changed to check callResult instead of STAXResult:

    <if expr="callResult <= 50">
    

    Why was it necessary to make these changes? Why couldn't we just check/update the STAXResult value directly?
    ______________________________________________________________________________________
    ______________________________________________________________________________________