Tool Descriptor
An AWM tool descriptor describes how a tool provided by a function package is called at run time. Tool descriptors can only be referenced by action descriptors where they are defined in a fixed sequence. The return code of a tool is checked against the maximum allowed return code defined under Application Options. If the return is high this prevents the execution of all following tools defined in the action descriptor. Output parameters of tools can be used as input parameters for subsequent tools.
The basic requirement for the implementation of a tool is an implementation of a tool interface. The function package to which the tool descriptor belongs defines the connection between tool descriptors and the communication interfaces. The function package has to implement the AWM model extension point. See the function package topics for details about all provided AWM tool descriptors.
Any tool making changes to one or more AWM elements in the attached application should be specified in the tool descriptor in such a way that AWM can react to such operations. This is modeled using the ResourceProcessing attribute.
Configurable resource operations are based on the following rules:
- Resource operations are 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 must not match the filter criteria after they are inserted. 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 operations apply 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 operations are not executed if the corresponding tool execution returns an error code higher than the maximum allowed return code.
The following resource operations can be modeled for a tool descriptor:
| Resource Operation | 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 operation. |
| 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 should 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 operation. |
| 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 operations possible. It also allows for dealing 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 may depend on the function package provider. The function package specific tool attributes are documented in the function package topics. See Extending the AWM Meta Model for more information.
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 should be 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 operations that the tool carries out with elements, so that the AWM can react to this.
Valid values include:
|
| 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). |
| HelpText [O] | String
(multi line) |
Help text associated with the tool. If this help text is defined for a UI tool, the help text appears when the question mark is clicked in the dialog box. |
| 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 property value is passed as an output parameter to the tool. |
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 show 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 shown 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 should 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 | Defines 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
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. |