Tool Descriptor

Tools are central to an AWM model. Tools are defined by a function package and provide the functionality which can be used in actions of the model. An action always consists of a sequence of tools. Every tool returns a tool execution code. When the tool execution code is higher than the maximum permitted return code specified under Application Options, the action is terminated.

The input and output parameters of a tool have to be modelled. This enables the tools of an action to exchange information. The value of an output parameter of a tool can be used as input value for a subsequent tool in the tool chain of an action.

You can write tools in an atomic and modular way, encapsulating a specified functionality so that a tool can be reused in various action contexts.

AWM provides two features to control the tool execution within an action:

Statements
- A statement can define a conditional execution of tools (if/else) or a loop over a tool sequence. The if/else or loop condition is determined by run-time values of properties.
Parameter override in an Action_Has_Tool or Statement_Has_Tool relationship
- Enables you to override an input parameter of a tool, for example, with a static value in a certain action context facilitating the reusability of the tool by this means.

By default, the execution of a tool is a black box process. In certain cases a tool might need to affect the AWM resource(s) on which it is applied. For example, a deletion tool that removes the AWM resource from the AWM cash. AWM provides the resource processing concept to support this requirement which would be modeled using the ResourceProcessing attribute of a tool.

The following rules apply for resource processing:

Resource processing is supported for elements.
Any new elements added to the Table Results or Application Explorer view by an action are inserted at the bottom of the list, or if the list has been sorted, according to the sorting criteria.
Inserted elements need not match the filter criteria after they are added to the element list. Refreshing the list shows only elements consistent with the filter criteria.
Property values returned when updating or inserting an element are assigned to the element except for key properties.
By default, resource processing applies for the selected resource. UPDATE and DELETE can be applied on any AWM element if its key properties and match name are provided by the operation. Providing the match name is optional, as long as the action is executed on an element of the same type as the target element.
Resource processing is not executed if the corresponding tool execution returns an error code higher than the maximum permitted return code.

The following resource processing can be modeled for a tool descriptor:

Resource Processing	Description
COPY	Creates a new element based on the selected element. All the property values are copied first. Property values returned by the tool are assigned to the copied resource. The copied element is inserted into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element.
DELETE	Removes the selected elements from all lists. It does not necessarily mean that the elements are deleted in the attached application system. This depends on the modeled tool. Supports deleting specific elements if their key properties and match name are returned with the resource processing.
INSERT	Inserts a new element into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element. If an element with the same ID already exists, an UPDATE is performed instead.
INSERT-CHILD	Inserts a new element as a child of the current selection. Works only if the selected resource is able to have children, such as an element that has a "Get Children" action and is only relevant for the Application Explorer view. If an element with the same ID already exists, an UPDATE is performed instead.
MOVE	Creates a new element based on the selected element. All the property values are copied first. Property values returned by the tool are assigned to the copied resource. Then it removes the selected element from all lists. It does not necessarily mean that the element is deleted in the attached application system. This depends on the modeled tool. The new element is inserted into the Application Explorer or Table Results view. In the tree view the element is inserted on the same hierarchical level as the selected element.
READ	Standard value. Does not make any changes to elements.
REFRESH	Updates all property values of the selected element by means of the "GetAllProperties" action assigned to the element type. If you want to refresh an element directly after inserting an element, you can use the "Refresh Resource" attribute of the tool descriptor instead.
UPDATE	Updates the selected element with the values returned by the tool. Key property values cannot be updated. Supports updating specific elements if their key properties and match name are returned with the resource processing.
TOOL_DEFINED	The rules about which element operations are to be used for this tool descriptor are set in the attached tools and not in the model. This makes dynamic implementation of resource processing possible. It also enables you to deal with more than one resource. See Tool-defined Resource Operations for more information.

The attributes which are displayed for a tool descriptor in the model editor depend on the tool description in the corresponding function package.

Like all attributes, clicking on an attribute in the Properties view will display a short description at the bottom of the window. Opening the contextual help page with the tool descriptor selected (default key: F1) will display the help page for the tool with additional information.

Note: If a tool was developed by a third-party supplier, the tool descriptor might not have a contextual help page associated with it.

Attributes that are valid for all tool descriptors are listed in the table below:

Attribute	Type	Description
ID *	ID *	The ID of the tool descriptor.
RefreshResource	Boolean	Indicates whether the element is updated after successful execution of the tool. This means that the "GetAllProperties" action of the element is always called after a successful execution of the tool. See Get All Properties Action for more information. The default value is `false`.
ResourceProcessing	Selection	Defines the impact on AWM resources the tool expects from AWM after a successful execution of the tool. Valid values include: COPY DELETE INSERT INSERT-CHILD MOVE READ (this is the default value) REFRESH TOOL_DEFINED UPDATE
In Parm Separator [O]	String	Separator used to separate input parameter values for command based tools. Can be entered with double quotes, which are removed at run time. The default value is `" "` (Blank).
Out Parm Separator [O]	String	Separator that parses returned output parameter values from command based tools. Can be entered with double quotes, which are removed at run time. The default value is `" "` (Blank).

Relationship	Cardinality	Description
Has Input Parameter	0..*	Relationship to a property. The property value is passed as an input parameter to the tool.
Has Output Parameter	0..*	Relationship to a property. The value returned by the tool is mapped to the modelled output parameter property.

Tool Parameters

Tools typically support input and/or output parameters modelled as a Tool_Has_Input_Parameter or Tool_Has_Output_Parameter relationship.

The parameter types and number of mandatory or optional parameters are determined by the tool definition. Mandatory parameters will be created automatically by AWM, while optional parameters can be created manually.

Some tools may have additional children, which are referred to as complex attributes.

Note: Legacy tool descriptor types, which have been specified with the deprecated API from version 4.0 or earlier, are unable to define valid parameter types. To resolve this issue, you can add generic parameter types in the model editor.

Examples

Tool SCLM_TOOL_AWM_UI_ChangeLanguage

Attribute	Value	Description
Essential:
Dialog Type	Input Dialog	The tool represents an AWM input dialog. All referenced properties are represented as fields in the input dialog. The "Preview Dialog" action can be used in the model editor to display a preview of the dialog. See Open Modeled Dialog for more information.
ID	SCLM_TOOL_AWM_UI_ChangeLanguage	Unique identifier of the tool in this model.
Optional:
Description	Change or Retrieve a new valid SCLM language.	Informational message displayed in the header of the AWM input dialog.
Help Text	---	No special help text is specified for this dialog box; modelled help text is associated with the question mark in the bottom of the dialog dox.
In Parm Separator	---	No input parameter separator is needed for a tool of type "Open Modeled Dialog"
Out Parm Separator	---	No output parameter separator is needed for a tool of type "Open Modeled Dialog"
Title	Change SCLM Language	Text shown as the title of the AWM input dialog.
Validate Action	---	No validate action is specified for this dialog. A reference to an action could be specified here. The action is executed when the OK button is clicked before the dialog is closed, see Validate Action for more information.
Resource Processing:
Refresh Resource	false	The GetAllProperties action must not be called after the successful execution of this tool.
Resource Processing	UPDATE	Resource processing UPDATE means that the properties of the selected AWM element are updated after the successful execution of the tool by changes on properties in the dialog, in this case the SCLM language. It is not necessary to explicitly specify the output parameters for resource processing. This is because the AWM input dialog parameters are also treated as output parameters.

Tool SCLM_TOOL_ISPF_REX_CopyElement

Attribute	Value	Description
Essential:
ID	SCLM_TOOL_ISPF_REX_CopyElement	Unique identifier of the tool in this model.
Invocation Form	REXX	Specifies how the ISPF tool is called; for a REXX procedure the invocation form REXX is the default.
Program ID	TAUSCCPY	Name of the REXX to be called.
Run As Job	NO	The tool should be executed directly in the associated server.
Optional:
Help Text	---	Help text is irrelevant for tools of type "Execute ISPF Command".
In Parm Separator	" "	The input parameters for the tool are separated by blanks.
Out Parm Separator	" "	The output parameters for the tool are separated by blanks.
Resource Processing:
Refresh Resource	true	The GetAllProperties action is called after successful execution of the tool.
Resource Processing	COPY	A new AWM element is created and initialized with the property values of the selected AWM element. The new AWM element is updated by property values returned by the tool as output parameters.

Tool SCLM_TOOL_ISPF_REX_PromoteOnline

SCLM ISPF properties of tool to promote online

The tool SCLM_TOOL_ISPF_REX_PromoteOnline is an example of the usage of different tool output parameter types.

Parameter Type	Description
String Output	Return message of the tool under the OUTPARM parameter.
File Output	File descriptors containing additional SCLM information concerning the SCLM action. The corresponding REXX procedure returns the file names under the OUTPARM parameters. Setting the attribute "To Output Dialog" in the relationship Tool_Has_OutputParameter to true has the effect that an AWM output dialog is opened presenting the content of the returned files after all tools of the corresponding action are executed.
ToolDefinedResourceProcessing	Set of properties to which the resource processing values returned by the tool are mapped. If the standard AWM ISPF tool interface is used the resource operation values can be returned in the ISPF table TAUTOTBI.