Difference between revisions of "PTP/user-guides/jaxb etfw workflow"

Revision as of 17:12, 22 March 2013

Overview

The intent of this user guide is to provide information on writing ETFw XML workflows using Resource Manager (RM) JAXB by going through the various parts of the workflow. This user guide is not yet complete so if you are currently using this page as a reference for building JAXB workflows, take note that some of how this information is organized may change.

Extension Point

The extension point for adding new JAXB ETFw workflows is org.eclipse.ptp.etfw.jaxb.workflows. The following information is required for a new workflow:

• workflowDefinitionXML
  • name - the name of the tool. This is displayed in the tool selection dropdown menu (e.g. TAU, PPW_UPC, etc).
  • file - the path to the XML file containing the ETFw workflow.

<extension point="org.eclipse.ptp.etfw.jaxb.workflows">
  <workflowDefinitionXML
    name="TAU"
    file="TAU.xml">
  </workflowDefinitionXML>
</extension>

Creating an ETFw Workflow

This section explains how to create new ETFw workflows, provide reference information for the XML tags inside an ETFw workflow, and show some snippets of the TAU XML file. Each ETFw workflow begins with the top-level tag <etfwTool>. Within this top-level tag can be one or more Control Data (<controlData>), Build Tool (<buildTool>), Execution Tool (<execTool>) and/or Analysis Tool (<analysisTool>) tags.

<etfwTool>
  <controlData>
  ...
  </controlData>
  <buildTool>
  ...
  </buildTool>
  <execTool>
  ...
  </execTool>
  <analysisTool>
  ...
  </analysisTool>
</etfwTool>

Control Data

For those that are familiar with creating target configurations, this is probably a familiar term. The control data tag contains all of the attributes that are associated with the workflow. The attributes are used to control UI actions and store information based on user selections. Below is a snippet from the ETFw TAU XML workflow. These attributes were selected because they illustrate how environment variables are stored, how UI options can be translated into program arguments and how a program argument can be paired with another attribute that has the value to pass in. In the next few sub-sections, each set of attributes are explained in more detail with the corresponding XML UI code.

<controlData>
  <!-- This is how an environment variable, TAU_SYNCHRONIZE_CLOCKS is set -->
  <attribute name="TAU Runtime.performance.options.environmentvariables.configuration_id_TAU_SYNCHRONIZE_CLOCKS" type="boolean" translateBooleanAs="1, ">
    <rm:default>1</rm:default>
  </attribute>
  <!-- This is how a program option is set, e.g. -optVerbose, which gets passed as a command line argument -->
  <attribute name="Tau Compiler.performance.options.configuration_id_-OPTVERBOSE_ARGUMENT_DEFAULT" type="boolean" translateBooleanAs="-optVerbose, ">
    <rm:description>Turn on verbose debugging message</rm:description>
    <rm:tooltip>Turn on verbose debugging message</rm:tooltip>
    <rm:default> </rm:default>
  </attribute>
  <!-- These last two attributes contain the program argument, -optPdtDir=, and the value to set it equal to -->
  <attribute name="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT" type="boolean" translateBooleanAs="-optPdtDir=, ">
    <rm:description></rm:description>
    <rm:tooltip></rm:tooltip>
    <rm:default> </rm:default>
  </attribute>
  <attribute name="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED" type="string">
    <rm:default></rm:default>
  </attribute>
</controlData>

Environment Variables Attributes

The primary parts of the attribute for setting environment variables are:

• name
  • TAU Runtime.performance.options.environmentvariables.configuration_id_ is the key and should match the option panes <configVarId /> tag to which it belongs.
  • TAU_SYNCHRONIZE_CLOCKS is the environment variable to set.
• type
  • boolean
  • string
  • choice
  • integer
• translateBooleanAs - In many cases, environment attributes are tied to checkbox UI options that returns a boolean that needs to be translated to something else (e.g. 1 or 0, or even a string). In the case of this attribute above, the boolean is translated as 1 for true, empty for false.

Below is a snippet of the XML workflow that creates the checkbox attribute and associate it with a tool pane. The critical parts to understand are the <configVarId> and the <rm:widget> tags. The other XML tags are explained later in this document.

<execTool tool-name="TAU Runtime">
  <global>
    <toolPanes virtual="false" embedded="false">
      <configId>TAU Runtime.performance.options.configuration_id_</configId>
      <configVarId>TAU Runtime.performance.options.environmentvariables.configuration_id_</configVarId>
      <optionPane>
        <rm:title>Tau Runtime</rm:title>
        <rm:layout>
          <rm:grid-layout />
        </rm:layout>
        <rm:composite>
          <rm:layout>
            <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" />
	  </rm:layout>
          <rm:layout-data>
            <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" />
          </rm:layout-data>
          <rm:widget type="checkbox" title="Synchronize Clocks" style="SWT.LEFT" attribute="TAU Runtime.performance.options.environmentvariables.configuration_id_TAU_SYNCHRONIZE_CLOCKS">
	    <rm:layout-data>
              <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" />
            </rm:layout-data>
  	  </rm:widget>
        </rm:composite>
      </optionPane>
    </toolPanes>
  </global>
</execTool>

Program Argument Attributes

This section discusses how UI options get translated into program arguments using the above control data as an example. In the Control Data, the option -optVerbose should get passed as a program argument based on a boolean translation (similar to the environment variable). As with the environment variable, the main parts of the attribute are:

• name
  • Tau Compiler.performance.options.configuration_id_ is the key and should match the option panes <configId /> tag to which it belongs. This lets the system know that it is a program argument for this tools option pane and the value should be passed to the tool.
  • -OPTVERBOSE_ARGUMENT_DEFAULT - Unlike the environment variable, this string can be anything since it doesn't have any significance.
• type
  • boolean
  • string
  • choice
  • integer
• translateBooleanAs - Similar to environment variables, attributes containing program arguments are primarily tied to checkbox UI widgets that returns a boolean that needs to be translated to something else (e.g. a string value). In the case of this attribute above, the boolean is translated as -optVerbose for true, empty for false.

Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and associate it with the specified tool pane. The critical parts to understand are the <configId> and the <rm:widget> tags. The other XML tags are explained later in this document.

<toolPanes virtual="false" embedded="false" pane-name="Tau Compiler" prepend-with="-tau_options=" enclose-with="'" separate-with=" ">
  <configId>Tau Compiler.performance.options.configuration_id_</configId>
  <configVarId>Tau Compiler.performance.options.environmentvariables.configuration_id_</configVarId>
  <optionPane>
    <rm:title>Tau Compiler</rm:title>
    <rm:layout>
      <rm:grid-layout />
    </rm:layout>
    <rm:composite>
      <rm:layout>
        <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" />
      </rm:layout>
      <rm:layout-data>
        <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" />
      </rm:layout-data>
      <rm:widget type="checkbox" title="Verbose" style="SWT.LEFT" attribute="Tau Compiler.performance.options.configuration_id_-OPTVERBOSE_ARGUMENT_DEFAULT">
        <rm:layout-data>
          <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="3" />
        </rm:layout-data>
      </rm:widget>
    </rm:composite>
  </optionPane>
</toolPanes>

Paired Program Argument Attributes

This section discusses the other type of program arguments, paired program arguments. That is, when you have something similar to the previous discussion about program arguments, but you want to pass a value for that argument. For example, looking at the control data, we want to pass a value for the program argument -optPdtDir= where one UI widget contains the program argument and another contains the value to pass. The last two attributes in the control data above represent paired program arguments and the details about how they are paired are highlighted below.

First attribute:

• name
  • Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT

Second attribute:

• name
  • Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED

As with normal program arguments, the first part of the name must match the value found in the tool pane's <configId /> field so that the system knows that the program argument is for the tool that the pane is associated with. The difference is that the second key that has the value must end with _SAVED. When parsing program arguments, the system looks at the launch configuration to see if there is another attribute that matches the original key value, but ends with _SAVED. This way it knows that -optPdtDir= should be paired with whatever value is in the second attribute. Below is a snippet of the XML workflow that creates the checkbox widget for this program argument and a browse widget that allows the user to either browse for the location of PDT or enter it. The critical parts to understand are the <configId> and the pair of <rm:widget> and <rm:browse> tags. The first is for the checkbox and the other for a special widget for the browse button / Text field. The other XML tags are explained later in this document.

<rm:widget type="checkbox" title="PdtDir" buttonId="PdtDir" style="SWT.LEFT" attribute="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT">
  <rm:layout-data>
    <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="1" />
  </rm:layout-data>
</rm:widget>
 
<rm:browse title="Browse..." localOnly="true" directory="true" textStyle="SWT.BORDER" attribute="Tau Compiler.performance.options.configuration_id_-OPTPDTDIR_ARGUMENT_SAVED">
  <rm:text-layout-data>
    <rm:grid-data horizontalSpan="1" horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" />
  </rm:text-layout-data>
  <rm:button-layout-data>
    <rm:grid-data horizontalSpan="1" horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="false" />
  </rm:button-layout-data>
  <rm:text-control-state>
    <rm:enable-if button="PdtDir" selected="true" />
  </rm:text-control-state>
  <rm:button-control-state>
    <rm:enable-if button="PdtDir" selected="true" />
  </rm:button-control-state>
</rm:browse>

ETFw Tag Reference

• <etfwTool> - Top level tag for enclosing an ETFw workflow.
  • Attributes:
    • xmlns:rm "http://eclipse.org/ptp/schemas" - resource manager (rm) namespace
    • name - string - the workflow name
    • prepend-execution - boolean - If true the actual executable is an argument passed to one or more additional utilities.
    • recompile - boolean - If true the program is recompiled with performance-analysis specific modifications.
    • explicit-execution - boolean - If true there is no automatic assumptions about when execute steps must be performed. Automatic execution does not take place after build steps!
• <controlData> - Contains all of the attributes associated with the workflow. These are tied to UI widgets to save information based on user selections.
  • <attribute name="" type="" translateBooleanAs="">
• <buildTool> - Represents a compilation step in the workflow.
  • Attributes:
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
    • require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.
    • replace-compiler - boolean - specify true if the compiler command is entirely replaced rather than prepended.
    • set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
  • <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets to control what options are available for the tool. It represents a UI tab from the RM JAXB schema.
  • <cc-compiler>, <cxx-compiler>, <f90-compiler>, upc-compiler, <all-compilers> - Special cases representing the different compiler types that can either replace or be prepended to the default compilers for those languages. If the individual compiler tags are not defined and a command is specified for allcompilers it replaces or prepends the command for every language. If the individual compilers are defined along with allcompilers the individual compilers are used and each is given arguments defined by allcompilers. Since these are all represented by the same data type, this can probably be simplified.
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-command - string - command used to invoke the tool
    • tool-group - string - tools in the same group are assumed to share the same binary location
    • out-to-file - string - the file to which the standard out of this tool must be written
    • visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
  • <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
    • <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <execute-if> - execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
• <execTool> - Represents a execution step in the workflow.
  • Attributes:
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
    • require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.
    • prepend-execution - boolean - if true, the actual executable is an argument passed to one or more utilities
    • replace-execution - boolean - if true, the executable and arguments in the launch configuration are ignored and the utilities are run instead
    • set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
  • <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most liklely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
  • <execUtils>
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-command - string - command used to invoke the tool
    • tool-group - string - tools in the same group are assumed to share the same binary location
    • out-to-file - string - the file to which the standard out of this tool must be written
    • visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is printed on the console.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
  • <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
    • <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <execute-if> - execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
• <analysisTool> - Represents a analysis step in the workflow.
  • Attributes:
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-type - string - This tag applies only to the analysis step. It should be set to view for tools that show data or to process for tools that process data and (generally) output another file.
    • require-true - string - a launch configuration attribute name which causes this tool step execute if it is defined.
    • depth - integer -
    • useDefaultLocation - boolean -
    • useLatestFileOnly - boolean -
    • set-success-attribute - string - a launch configuration attribute name which is set to "true" if the step executes successfully and "false" if the step fails execution.
  • <global> - Some environment variables do not logically fit with the invocation of a particular tool. In that case, the environment variables and the UI for defining which variables to set, can be placed in the global construct rather than a particular tools panel. Currently, the global tag is only used by the <execTool> tag.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1. This most likely remains unused for the global panels since they were intended to add environment variables that did not fit with other tool panes.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
  • <analysis-commands>
    • tool-id - string - a unique tag for this application. Optional.
    • tool-name - string - name of the tool
    • tool-command - string - command used to invoke the tool
    • tool-group - string - tools in the same group are assumed to share the same binary location
    • out-to-file - string - the file to which the standard out of this tool must be written
    • visualizer - boolean - if true, the command is launched and the output is not handled. Otherwise, output is manged for printing on the console.
    • <toolPanes virtual="" embedded="" pane-name="" prepend-with="" enclose-with="" separate-with=""> - the array of tool panes associated with the tool. This contains information about how arguments should be enclosed, separated, etc.
      • <configId> - unique string identifying the tool pane that all program argument attributes should start with so they can be associated with the correct tool. See example 1.
      • <configVarId> - unique string identifying the tool pane so that all environment variable attributes can be associated with the correct tool.
      • <optionPane> - this is where the User Interface is defined by adding widgets. It represents a UI tab from the RM JAXB schema.
  • <for-all-like> - TBD
  • <tool-state> - Determines if the tool step does or does not execute by evaluating a conditional expression containing launch configuration attributes which were set by a previous tool step's set-success-attribute.
    • <execute-if attribute="" [value=""]> - execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if either the attribute is defined [no value given] or matches the value [value given].
    • <execute-if> - execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].
    • <do not execute-if> - do not execute this tool step if the contained conditional expression is true.
      • <not>|<and>|<or> - the 'not', 'and', and 'or' of the contained conditional expression.
        • <rule attribute="" [value=""]> - true if either the attribute is defined [no value given] or matches the value [value given].

Appendix 1: PerfSuite Example

This section provides detailed steps for creating an ETFw XML workflow for the PerfSuite profiling tool. This example assumes that PerfSuite is compiled and running on your machine with PAPI support. Most of PerfSuite's options can either be passed to the psrun executable at the command line or set as environment variables. For this example, most are passed at the command line and one is set as an environment variable to illustrate how the ETFw JAXB system works.

The profiling tool from PerfSuite we want to run is psrun. The configurable commands are listed below under three categories, environment variables, program arguments and paired program arguments:

• Environment Variables
  • File Format - output the results in XML or plain text.
• Program Arguments
  • MD5 checksum - include MD5 checksums in output
• Paired Program Arguments
  • Configuration - specify the configuration file to use.
  • Domain - select the counting domain (user, kernel, all)
  • POSIX - enable POSIX thread support
  • Resource Usage - include resource usage statistics
  • Resource Usage Only - include only resource usage statistics
  • Write Signal Numbers - Specify signal numbers to write before process exits.
  • Overflow Threshold - specify overflow threshold to use for profiling

The environment variables is set in the environment prior to launch, program arguments and paired program arguments are passed to the psrun executable at the command line. For example, to specify that we include md5 checksums and set the domain to kernel the command is:

psrun --md5 -d kernel shallow

where shallow is the name of the program executable to profile. Now that we know the inputs we need to tie to the User Interface (UI), we can start building the XML workflow that ties the UI selections to program arguments or environment variables.

The extension point for PerfSuite is shown below:

<extension point="org.eclipse.ptp.etfw.jaxb.workflows">
  <workflowDefinitionXML
    name="PerfSuite"
    file="perfsuite.xml">
  </workflowDefinitionXML>
</extension>

Since PerfSuite is run with the program executable as input, we don't need to concern ourselves with the buildTool and analysisTool tags. We only need the execTool tag. The basic workflow is something similar to the one below:

<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas"
	xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false">
 
  <!-- attributes are stored in the control data -->
  <controlData>
 
  </controlData>
 
  <!-- This is the tool to execute -->
  <execTool tool-name="PerfSuite">
 
  </execTool>
 
</etfwTool>

For simplicity, we just add the necessary pieces to perform the previous example (e.g. psrun --md5 -d kernel shallow) and specify that we want to have the output in XML (by specifying the environment variable PS_HWPC_FORMAT.

<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas"
	xsi:schemaLocation="etfw_tool_type.xsd" name="perfsuite" prepend-execution="false" recompile="false" explicit-execution="false">
 
  <!-- attributes are stored in the control data --->
  <controlData>
    <attribute name="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT" type="choice">
      <rm:description>Specify the output format (XML or plain text)</rm:description>
      <rm:choice>xml,text</rm:choice>
      <rm:default>xml</rm:default>
    </attribute>
    <attribute name="PERFSUITE_psrun.configuration_id_-MD5" type="boolean" translateBooleanAs="--md5, ">
      <rm:description>Include MD5 checksums in output</rm:description>
      <rm:default> </rm:default>
    </attribute>
    <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN" type="boolean" translateBooleanAs="-d, ">
      <rm:description>Specify domain</rm:description>
      <rm:default> </rm:default>
    </attribute>
    <attribute name="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED" type="choice">
      <rm:description>Specified domain</rm:description>
      <rm:choice>user,kernel,all</rm:choice>
      <rm:default>user</rm:default>
    </attribute>
  </controlData>
 
  <execTool tool-name="PerfSuite">
    <!-- This is the set of tools to execute, in this case just one tool is defined -->
    <execUtils tool-command="psrun">
      <!-- A single tool could have multiple panes, in this case there is just one -->
      <toolPanes virtual="false" embedded="false">
        <configId>PERFSUITE_psrun.configuration_id_</configId>
        <configVarId>PERFSUITE_psrun.environmentvariables.configuration_id_</configVarId>
 
        <!-- This is the actual UI tab that is displayed with the defined UI widgets -->
        <optionPane>
          <rm:title>PerfSuite</rm:title>
          <rm:layout>
            <rm:grid-layout />
          </rm:layout>
          <rm:composite>
            <rm:layout>
              <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" />
            </rm:layout>
            <rm:layout-data>
              <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" />
            </rm:layout-data>
            <rm:widget type="combo" title="File Format" readOnly="true" style="SWT.LEFT"
              attribute="PERFSUITE_psrun.environmentvariables.configuration_id_PS_HWPC_FORMAT">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" />
              </rm:layout-data>
              <rm:tooltip>Output format, either XML or text</rm:tooltip>
            </rm:widget>
            <rm:widget type="checkbox" title="Domain" buttonId="domain-button" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="1" />
              </rm:layout-data>
              <rm:tooltip>Select counting domain (user, kernel, all)</rm:tooltip>
            </rm:widget>
            <rm:widget type="combo" readOnly="true" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-DOMAIN_SAVED">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" />
              </rm:layout-data>
              <rm:control-state>
                <rm:enable-if button="domain-button" selected="true" />
              </rm:control-state>
            </rm:widget>
            <rm:widget type="checkbox" title="MD5 checksum" style="SWT.LEFT" attribute="PERFSUITE_psrun.configuration_id_-MD5">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" />
              </rm:layout-data>
              <rm:tooltip>Include MD5 checksums in output</rm:tooltip>
            </rm:widget>
          </rm:composite>
        </optionPane>
      </toolPanes>
    </execUtils>
  </execTool>
</etfwTool>

Using the above XML workflow as a reference, let's break down where the pieces of the command psrun --md5 -d kernel shallow are in the workflow. If you find the execUtils tag, you see that it contains the tool-command we want to run, 'psrun. The rest of what is contained between the tags allows the user to select the additional input flags. For example, looking at the checkbox widget with title MD5 checksum, you see that it is tied to the attribute PERFSUITE_psrun.configuration_id_-MD5. If you find that attribute in the controlData section, it translates to --md5 when it is selected and the empty string when it is not selected. In addition, notice that the first part of the attribute, PERFSUITE_psrun.configuration_id_ corresponds to the configId for that tool's pane. This is how the system understands which attributes belong to which tools so the correct tool gets the --md5 input flag.

The rest of the inputs, including the environment variable for specifying text or XML output can be deduced by reviewing the sections above about setting environment variables and pairing attributes and then locating the UI widgets in the XML workflow.

Appendix 2: Converting ETFw XML to ETFw Resource Manager (RM) JAXB XML

This appendix is to aid developers in converting existing ETFw XML to the new ETFw Resource Manager (RM) JAXB XML.

1. The existing "org.eclipse.ptp.etfw.workflows" extension point with <workflowDefinitionXML> containing XMLFile in plugin.xml file from:

<extension point="org.eclipse.ptp.etfw.workflows">
  <workflowDefinitionXML
    XMLFile="HPCTOptions.xml">
  </workflowDefinitionXML>
</extension>

to new "org.eclipse.ptp.etfw.jaxb.workflows" extension point with <workflowDefinitionXML> containing file and name in plugin.xml file :

<extension point="org.eclipse.ptp.etfw.jaxb.workflows">
  <workflowDefinitionXML
    file="HPCTOptions.xml"
    name="HPC Toolkit">
  </workflowDefinitionXML>
</extension>

2. Change outermost XML definition in HPCTOptions.xml file from <toolset.01><tool>:

<?xml version="1.0" encoding="UTF-8"?>
<toolset.01>
  <tool name="HPC Toolkit" explicitexecution="true">
  ...
  </tool>
</toolset.01>

to <etfwTool> with matching explicit-execution and a <controlData> section in HPCTOptions.xml file:

<etfwTool xmlns="http://org.eclipse.ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:rm="http://eclipse.org/ptp/schemas"
 xsi:schemaLocation="etfw_tool_type.xsd" name="hpctoolkit" prepend-execution="false" recompile="false" explicit-execution="true">
  <controlData>
  ...
  </controlData>
  ...
</etfwTool>

3. Change each execute/global from <execute><global> in <toolset.01><tool>:

    ...
    <execute>
      <global name="HPC Toolkit">
        ...
      </global>
    </execute>
    ...

to <execTool><global><toolPanes> with <configId> and <configVarId> in <etfwTool>:

   ...
  <execTool tool-name="HPC Toolkit">
    <global>
      <toolPanes virtual="false" embedded="false">
        <configId>HPCTOOLKIT_global.configuration_id_</configId>
        <configVarId>HPCTOOLKIT_global.environmentvariables.configuration_id_</configVarId>
        ...
      </toolPanes>
      <!-- ************************************************************************************** --> 
    </global>
  </execTool>
  ...

4. Change each option pane from <optionpane> in <execute><global>:

        ...
        <optionpane title="Data Collection" virtual="true" displayoptions="false">
          ...
        </optionpane>
        ...

to <optionPane><rm:composite> with <rm:title>, <rm:layout>, and <rm:composite> in <execTool><global><toolPanes>:

        ...
        <optionPane>
          <rm:title>Data Collection</rm:title>
          <rm:layout>
            <rm:grid-layout />
          </rm:layout>
          <rm:composite>
            <rm:layout>
              <rm:grid-layout numColumns="3" makeColumnsEqualWidth="false" />
            </rm:layout>
            <rm:layout-data>
              <rm:grid-data horizontalAlign="SWT.FILL" verticalAlign="SWT.FILL" grabExcessHorizontal="true" />
            </rm:layout-data>
            ...
          </rm:composite>
        </optionPane>
        ...

5a. Checkbox: Change each checkbox environment variable from type=toggle <togoption> in <optionpane>:

          ...
          <togoption label="Generate unique filenames:" optname="HPC_UNIQUE_FILE_NAME" envvar="true" tooltip="Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)">
            <optvalue type="toggle" seton="yes" />
          </togoption>
          ...

to a type=boolean attribute in <controlData> and type=checkbox RM widget definition in <optionPane><rm:composite>:

    ...
    <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME" type="boolean" translateBooleanAs="yes,no">
    </attribute>
            ...
            <rm:widget type="checkbox" title="Generate unique filenames:" style="SWT.LEFT" 
              attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_UNIQUE_FILE_NAME">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="3" />
              </rm:layout-data>
              <rm:tooltip>Generate unique filenames for each MPI task's output (HPC_UNIQUE_FILE_NAME)</rm:tooltip>
            </rm:widget>
            ...

5b. Text Field: Change each text field environment variable from type=text <togoption> in <optionpane>:

          ...
          <togoption label="Output file name:" optname="HPC_OUTPUT_NAME" envvar="true" required="true" tooltip="Specify output file name (HPC_OUTPUT_NAME)">
            <optvalue type="text" fieldrequired="true" />
          </togoption>
          ...

to a type=string attribute in <controlData> and type=label & type=text RM widget definitions in <optionPane><rm:composite>:

    ...
    <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME" type="string">
    </attribute>
            ...
            <rm:widget type="label" style="SWT.LEFT">
              <rm:layout-data>
                <rm:grid-data horizontalAlign="SWT.BEGINNING" verticalAlign="SWT.CENTER" grabExcessHorizontal="false" />
              </rm:layout-data>
              <rm:fixed-text>Output file name: </rm:fixed-text>
            </rm:widget>
            <rm:widget type="text" style="SWT.BORDER"
              attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_OUTPUT_NAME">
              <rm:layout-data>
                <rm:grid-data horizontalAlign="SWT.FILL" grabExcessHorizontal="true" horizontalSpan="2" />
              </rm:layout-data>
              <rm:tooltip>Specify output file name (HPC_OUTPUT_NAME)</rm:tooltip>
            </rm:widget>
            ...

5c. Choice: Change each choice environment variable from type=combo <togoption> in <optionpane>:

          ...
          <togoption label="Application time criteria: " optname="HPC_EXCEPTION_METRIC" envvar="true" required="true"
            tooltip="Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)">
            <optvalue type="combo" items="ELAPSED_TIME:::CPU_TIME" />
          </togoption>
          ...

to a type=choice attribute in <controlData> and type=combo RM widget definition in <optionPane><rm:composite>:

    ...
    <attribute name="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC" type="choice">
      <rm:choice>ELAPSED_TIME,CPU_TIME</rm:choice>
      <rm:default>ELAPSED_TIME</rm:default>
    </attribute>
            ...
            <rm:widget type="combo" title="Application time criteria: " readOnly="true" style="SWT.LEFT"
              attribute="HPCTOOLKIT_global.environmentvariables.configuration_id_HPC_EXCEPTION_METRIC">
              <rm:layout-data>
                <rm:grid-data widthHint="150" horizontalAlign="SWT.FILL" grabExcessHorizontal="false" horizontalSpan="2" />
              </rm:layout-data>
              <rm:tooltip>Select run time criteria: wall clock or elapsed time (HPC_EXCEPTION_METRIC)</rm:tooltip>
            </rm:widget>
            ...

Appendix 3: Temporary XML Schema Modification until Officially Committed

The ETFw schema file "etfw_tool_type.xsd", which can be found in project org.eclipse.ptp.etfw.jaxb needs to be modified. It is presently pointing at where the RM schema was located in a local development environment workspace (/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd). If you open this ETFw schema file, near the top you'll see a few comments about the resource manager schema and why it points at a local one instead of the existing remote one. In short, the ETFw schema file was modified because the resource manager schema needed to be changed to support the additional TAU widgets. Otherwise, TAU wouldn't work since it would always fail to load those widgets.

If you apply all the patches (for both bug reports: Bug 397684 - ETFw using JAXB framework, and Bug 397685 - TAU JAXB workflow for ETFw), then you have to update the ETFw schema to point at the resource_manager_type.xsd in your local org.eclipse.ptp.rm.jaxb.core project. If you apply only the framework itself (for bug report: Bug 397684 - ETFw using JAXB framework) , then you can safely point at the RM schema at http://eclipse.org/ptp/schemas/rm.xsd. In other word, if you patch for the TAU support then you need the modified RM schema.

Here is what you do for the time being until these changes are formally released:

Changed in project org.eclipse.ptp.etfw.jaxb in data/etfw_tool_type.xsd from

<!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU -->
<xs:import schemaLocation="file:/home/cnavarro/workspaces/ptp-dev/git/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" />

to

<!-- Point this schema to the location of the resource manager schema. This is required until the new widgets are added for TAU -->
<xs:import schemaLocation="file:User_Development_Environment_Directory/org.eclipse.ptp/rms/org.eclipse.ptp.rm.jaxb.core/data/resource_manager_type.xsd" namespace="org.eclipse.ptp" />

Appendix 4: Conditional Workflow Processing Examples

The first workflow, workflow1.xml, is patterned after an existing workflow, that is, one that does not contain any <tool-state><execute-if> elements. This workflow has three steps. The first is a pre-processing analysis step which invokes the Java class BeforeStep. The second is the execution step which launches the application specified within the launch configuration. The third step is a post-processing analysis step which invokes the Java class AfterStep. Execution starts on the first step and proceeds sequentially. Depending upon the launch configuration setting the execution step can be made to fail. Below is the output for both a successful execution and an unsuccessful one.

<?xml version="1.0" encoding="UTF-8"?>
<etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd"
				name="SAMPLE1" prepend-execution="false" recompile="false"
				explicit-execution="true">
 
	<analysisTool>
		<analysis-commands tool-command="BeforeStep" tool-group="internal" />
	</analysisTool>
 
	<execTool/>
 
	<analysisTool>
		<analysis-commands tool-command="AfterStep" tool-group="internal" />
	</analysisTool>
 
</etfwTool>

For the first workflow the console output of a successful execution is as follows. First the BeforeStep writes its output, next the execution step runs, and finally the AfterStep writes its output.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt
 
!ENTRY org.eclipse.ptp.rm.lml.monitor.core 4 4 2013-03-22 14:50:03.892
!MESSAGE /home/bwatt/runtime-Eclipse/.metadata/.plugins/org.eclipse.ptp.rm.lml.monitor.core/monitors.xml (No such file or directory)
@@@ In AfterStep.process projname=shallow_Linux configuration=Sample 1 Pass projectLocation=/u/bwatt

For the first workflow the console output of a failed execution is as follows. First the BeforeStep writes its output, next the execution step fails, which causes the AfterStep step to NOT run. Internally a global state variable is used. Initially is is set to true. Before each step is run this variable is checked if it is true the step is run if it is false the step is not run. After each step is run the step's success is 'anded' into the global state. Therefore following along with this workflow's execution, the global state is true and the BeforeStep is runs and completes successfully, next because the global state is true the execution step runs, but it fails which sets the global state to fails, which causes the AfterStep to NOT run. In other words, once the global state is set to false all follow-on steps are not executed, that is, failure cascades unless they use <tool-state><execute-if> elements. which this workflow does not.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 1 Fail projectLocation=/u/bwatt
 
!ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:17.313
!MESSAGE Execution Error
!STACK 1
org.eclipse.core.runtime.CoreException: d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2286::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
 
 
	at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160)
	at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591)
	at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233)
	at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95)
	at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53)
!SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:17.314
!MESSAGE d956bfa5-5b7b-458b-ba67-cbcc9e665cc0: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2286::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow

The second workflow, workflow2.xml, ...

<?xml version="1.0" encoding="UTF-8"?>
<etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd"
				name="SAMPLE2" prepend-execution="false" recompile="false"
				explicit-execution="true">
 
	<analysisTool>
		<analysis-commands tool-command="BeforeStep" tool-group="internal" />
	</analysisTool>
 
	<execTool set-success-attribute="x"/>
 
	<analysisTool>
		<analysis-commands tool-command="AfterStep" tool-group="internal" />
		<tool-state>
			<do-not-execute-if attribute="x" value="false"/>
		</tool-state>
	</analysisTool>
 
	<analysisTool>
		<analysis-commands tool-command="CleanupStep" tool-group="internal" />
		<tool-state>
			<execute-if attribute="x" value="false"/>
		</tool-state>
	</analysisTool>
 
</etfwTool>

For the second workflow the console output of a successful execution is as follows.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt
@@@ In AfterStep.process projname=shallow_Linux configuration=Sample 2 Pass projectLocation=/u/bwatt

For the second workflow the console output of a failed execution is as follows.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt
 
!ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:50:57.876
!MESSAGE Execution Error
!STACK 1
org.eclipse.core.runtime.CoreException: 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2512::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
 
 
	at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160)
	at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591)
	at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233)
	at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95)
	at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53)
!SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:50:57.876
!MESSAGE 2cb4d5ff-8c36-448d-9bda-de295ea4a45c: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2512::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
 
 
@@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 2 Fail projectLocation=/u/bwatt

The third workflow, workflow3.xml, ...

<?xml version="1.0" encoding="UTF-8"?>
<etfwTool xmlns="http://eclipse.org/ptp/etfw" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
				xmlns:rm="http://eclipse.org/ptp/rm" xsi:schemaLocation="etfw_tool_type.xsd"
				name="SAMPLE3" prepend-execution="false" recompile="false"
				explicit-execution="true">
 
	<analysisTool set-success-attribute="x">
		<analysis-commands tool-command="BeforeStep" tool-group="internal" />
	</analysisTool>
 
	<execTool set-success-attribute="y">
	</execTool>
 
	<analysisTool>
		<analysis-commands tool-command="AfterStep" tool-group="internal" />
		<tool-state>
			<do-not-execute-if>
				<or>
					<rule attribute="x" value="false"/>
					<rule attribute="y" value="false"/>
				</or>
			</do-not-execute-if>
		</tool-state>
	</analysisTool>
 
	<analysisTool>
		<analysis-commands tool-command="CleanupStep" tool-group="internal" />
		<tool-state>
			<execute-if>
				<or>
					<rule attribute="x" value="false"/>
					<rule attribute="y" value="false"/>
				</or>
			</execute-if>
		</tool-state>
	</analysisTool>
 
</etfwTool>

For the third workflow the console output of a successful execution is as follows.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt
@@@ In AfterStep.process projname=shallow_Linux configuration=Sample 3 Pass projectLocation=/u/bwatt

For the third workflow the console output of a failed execution is as follows.

@@@ In BeforeStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt
 
!ENTRY com.ibm.jdg2e.concurrency 4 4 2013-03-22 14:51:16.469
!MESSAGE Execution Error
!STACK 1
org.eclipse.core.runtime.CoreException: 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2679::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
 
 
	at org.eclipse.ptp.core.util.CoreExceptionUtils.newException(CoreExceptionUtils.java:49)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.checkJobForError(LaunchController.java:189)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.runCommand(LaunchController.java:897)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.doJobSubmitCommand(LaunchController.java:329)
	at org.eclipse.ptp.internal.rm.jaxb.control.core.LaunchController.submitJob(LaunchController.java:1160)
	at org.eclipse.ptp.launch.AbstractParallelLaunchConfigurationDelegate.submitJob(AbstractParallelLaunchConfigurationDelegate.java:591)
	at org.eclipse.ptp.launch.ParallelLaunchConfigurationDelegate.launch(ParallelLaunchConfigurationDelegate.java:233)
	at org.eclipse.ptp.etfw.parallel.ParallelToolLaunchConfigurationDelegate.launch(ParallelToolLaunchConfigurationDelegate.java:61)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.performLaunch(ETFWLaunchTool.java:308)
	at org.eclipse.ptp.etfw.internal.ETFWLaunchTool.run(ETFWLaunchTool.java:95)
	at org.eclipse.core.internal.jobs.Worker.run(Worker.java:53)
!SUBENTRY 1 org.eclipse.ptp.core 4 4 2013-03-22 14:51:16.469
!MESSAGE 343bf3cf-520e-4fca-94b0-f9673d08fae3: FAILED
ATTENTION: 0031-381 Global synchronized clock is not available. NTP synchronized system clock will be used. 
must have at least 2 processes, not 1
::::PoePid=2679::::
argc=1 argv[0]=/u/bwatt/shallow_Linux/shallow
 
 
@@@ In CleanupStep.process projname=shallow_Linux configuration=Sample 3 Fail projectLocation=/u/bwatt

The sample plugin XML contains references to the previous three workflows as "Sample 1" file workflow1.xml. "Sample 2" file workflow2.xml, and "Sample 3" file workflow3.xml. It also defines three analysis tools as Java classes BeforeStep, AfterStep and CleanupStep. Each of these tools output a single line of output when their process method is executed, for example, "@@@ In [BeforeStep|AfterStep|CleanupStep].process ...".

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
 
   <extension point="org.eclipse.ptp.etfw.jaxb.workflows">
      <workflowDefinitionXML
            file="workflow1.xml"
            name="Sample 1">
      </workflowDefinitionXML>
   </extension>
 
   <extension point="org.eclipse.ptp.etfw.jaxb.workflows">
      <workflowDefinitionXML
            file="workflow2.xml"
            name="Sample 2">
      </workflowDefinitionXML>
   </extension>
 
   <extension point="org.eclipse.ptp.etfw.jaxb.workflows">
      <workflowDefinitionXML
            file="workflow3.xml"
            name="Sample 3">
      </workflowDefinitionXML>
   </extension>
 
   <extension point="org.eclipse.ptp.etfw.dataManagers">
      <PerformanceDataManager
         class="com.sample.workflow.BeforeStep">
      </PerformanceDataManager>
   </extension>
 
   <extension point="org.eclipse.ptp.etfw.dataManagers">
      <PerformanceDataManager
         class="com.sample.workflow.AfterStep">
      </PerformanceDataManager>
   </extension>
 
   <extension point="org.eclipse.ptp.etfw.dataManagers">
      <PerformanceDataManager
         class="com.sample.workflow.CleanupStep">
      </PerformanceDataManager>
   </extension>
 
</plugin>

FAQ

• What happens to attributes that are prefixed with the <configId>? Answer: They become program arguments at launch.
• What happens to attributes that are prefixed with the <configVarId>? Answer They become environment variables at launch.
• What happens to attributes that are not prefixed with either <configId> or <configVarId>? Answer: ETFw with JAXB parsing won't know what those attributes are and wouldn't do anything with them except put them in the launch config.

References

• The ETFw documentation at: http://wiki.eclipse.org/PTP/ETFw/PTP_External_Tools_Framework
• The rm (resource manager) documentation is located at: http://wiki.eclipse.org/PTP/designs/Resource_Manager_Configuration
• The rm (resource manager) schema is located at: http://eclipse.org/ptp/schemas/rm.xsd