The validate action is used to validate dialog fields before sending the values to the next tool. It is supported by the "Validate Action" attribute of the Open Modeled Dialog and the Execute ISPF Dialog tool descriptors. The validate action is executed when the OK button is clicked in the dialog box.
Tools defined in a validate action can return specific validate messages that are interpreted by AWM. Any AWM tool descriptor is able to return validation messages if additional API programming has been implemented to create these messages.
There is already specific support for validate messages available for the following tool descriptors:
Messages are identified by the prefix "VALMSG" and are only returned if any of the modeled tools detects validation error(s), warning(s) and/or information(s) in the dialog fields. The prefix "VALMSG" is followed by special keywords. The order of the keywords is not relevant. Permitted keywords are "MSGTEXT", "SEVERITY" and "POS". Values of keywords are given in parentheses. Keywords and their values are not case sensitive.
The keyword "MSGTEXT" is mandatory. It contains the validate text that is shown in the dialog.
The keyword "SEVERITY" contains the severity of a validate message. Permitted values are "I" for Information, "W" for Warning and "E" for Error. The default value is "I".
The keyword "POS" contains the position of the dialog field to which the validate message refers. A validate message can correspond to multiple dialog fields. In this case the positions are separated by blank or comma. Dialog fields corresponding to these positions are decorated with a validation message text depending on the severity. The focus is set to the dialog field corresponding to the lowest position value.
Example of a tool validation message:
VALMSG MSGTEXT (Unfiltered member selection may produce a large output.) SEVERITY(W) POS(5)
The following table shows how validation messages are processed depending on their severity.
| Highest message severity | Message processing |
|---|---|
| I , W | Display all messages in the header of the dialog marked as information (I) or warning (W).
If the user changes a dialog field, the validate action is called again when the OK button is clicked. Otherwise the action directly proceeds with the next tool when the user clicks OK the next time and the validation action is not executed again. |
| E | Display all messages in the header of the dialog marked as error. The validate action is called again when the OK button is clicked. |