Thursday, April 8, 2010

Handling process launches in STAF / STAX

I have been a big fan of STAF test automation framework for many years. STAF is open-source and runs on all mainstream platforms (including IBM System z and Mac) . Its key strengths are distributing and coordinating tasks across multiple machines.

Launching processes in distributed machines is really well-implemented as a STAF service and also receives special treatment in the companion STAX execution engine. Process management is always a thorny discipline, dealing with process output, error codes, deciding whether or not to wait until they are done, and many other concerns.

I compiled a personal list of STAF/STAX options in launching new processes that always trick newcomers to the tool.

Waiting for a process launched through STAF

Running a command on any given machine running the STAF process is as simple as executing “staf PROCESS START ”.

What often derails people are the default launch settings, which instructs STAF to launch the process **asynchronously* and moving on, often breaking follow on commands that depend on the results of the first. If you must wait until the process completes its execution, you need to use the “WAIT” flag.




image

The next relevant flag is “SAMECONSOLE”, which prevents STAX from launching a new console (default behavior on Windows) . For most runs of unattended commands, SAMECONSOLE is your option of choice.


image

The last important flags are the ones indicating that you want STAF to collect the command results, namely RETURNSTDERR and RETURNSTDOUT, as follows:

image

Results from asynchronous launches

If you really must run a command asynchronously, you need to store the command handle returned by STAF and query its results later on.

image

Inside STAX

Launching the same process using the STAX engine requires more effort, which is understandable since STAX is a more sophisticated execution engine with support for programmatic constructs.

One of the most important observations about the call inside STAX is that it always waits for command invocation and it does not have the concept of consoles. In other words, STAX element always uses the equivalent of “WAIT SAMECONSOLE”  in the STAF PROCESS parameters.



  

    
 

    

        

            
                'local'
                'dir \\tmp'
                 
                 
                 
            
  

            
                "Result code: %i " % STAXResult[0][0]
            

            
                "Result data: %s " % STAXResult[0][1]
            

        
    
While observing the results in the Job monitor, we will see:

image


In conclusion


As usual, the excellent user guides shipped with both STAF and STAX are the most comprehensive material for learning about the intricacies of launching remote processes and manipulating their results. I just missed a short guide like the one above showing the STAF / STAX equivalence side-by-side.