ERRMSG (Error Message) and ERRMSGID (Error Message Identifier) keywords for display files
You can use one of these field-level keywords to identify a message that is displayed on the message line and that is associated with that field.
A warning message appears at file creation time if either of these keywords is specified on a record with the DSPMOD keyword. At run time, these keywords are ignored when the display mode changes.
Option indicators are valid for these keywords.
For ERRMSG, the parameters specify the message text and, optionally, a response indicator. The message text is the message to be displayed. (The Help key is not supported. Message help is not displayed when the Help key is pressed.)
If you specify a response indicator, it should be the same as the option indicator used to condition ERRMSG. On the input operation that follows the display of the error message, the IBM® i operating system turns off the indicator. If the response and the option indicators are the same, they are both turned off. One exception to this rule is if the response indicator is also specified for another keyword, such as CHANGE, CAnn, or CFnn. In that case, the on/off setting of the response indicator is based on the results of the function provided by the CHANGE or CFnn keyword. When a response indicator is specified, the first 50 characters of the message are also used as indicator text. Separate response indicator text is not valid for the ERRMSG keyword.
ERRMSGID(msgid [library-name/]msg-file [response-indicator] [&msg-data])
For ERRMSGID, the parameters specify:
- The message identifier for the message to be displayed
- The message file and, optionally, the library
- Optionally, a response indicator
- Optionally, a msg-data field name
The response indicator, if specified, should be the same as the option indicator used to condition the ERRMSGID keyword. On the subsequent input operation, after the display of the error message, the IBM i operating system turns off the indicator. However, if the response indicator is also specified on another keyword, such as CHANGE, CAnn, or CFnn, the on/off setting of the response indicator is based on the results of the function provided by the CHANGE, CAnn, or CFnn keyword.
The msg-data field, if specified, contains the replacement text for the specified message. The field must exist in the record format and the field must be defined as a character field (data type A) with usage P. For more information about how replacement text works, refer to the Send Program Message (CL) command in the Control language topic.
Priority among selected keywords
You can specify ERRMSG and ERRMSGID more than once for a single field. During program processing, use option indicators to select a particular message to be displayed.
Only one message can be displayed at one time even if messages are in effect for several fields on the same output operation. The field whose message is displayed is the first field for which the program selected a message.
If several keywords are in effect for one field on an output operation, the message to be displayed is the first of the following keywords:
- ERRMSG (If more than one ERRMSG keyword is selected, the first one the program selects is displayed.)
- ERRMSGID (If more than one ERRMSGID keyword is selected, the first one the program selects is displayed.)
A message field is displayed only if no error message keywords are also to be displayed.
For a list of priorities including the SFLMSG and SFLMSGID keywords, see SFLMSG (Subfile Message) and SFLMSGID (Subfile Message Identifier) keywords for display files.
Conditions occurring during message display
The displaying of a message using ERRMSG and ERRMSGID is similar to the displaying of messages by the IBM i operating system when field validation errors are detected.
When a message is displayed because of either the ERRMSG or the ERRMSGID keyword, all fields on the display are kept, including the field the message is associated with. Except for option indicators, data in the output buffer is ignored (that is, any new data from the program is not sent to the display).
The function keys valid following display of a message are:
- Function keys specified at the file level
- Function keys specified for the record format for which a message is displayed, if selected when the message is displayed
- For all errors:
- The message is highlighted.
- The cursor is blinked and the keyboard locked until the workstation user presses the Reset key.
- For errors associated with input-capable fields:
- All fields in error are displayed with their images reversed.
If a field in error has both the underline (UL) display attribute and the highlight (HI) attribute or the underline (UL) attribute and COLOR(BLU, WHT, or YLW) specified, its image is not reversed.
- The cursor is repositioned to the first displayed field that is in error.
- All fields in error are displayed with their images reversed.
- For errors associated with output-only fields:
- The display attribute of the field is not changed.
- The cursor is not positioned to the field (it does not change position).
Restoration of reversed image fields
- An input request with cancel (canceling a read operation with NOWAIT)
- A close request when the KEEP keyword is in effect
- Any request to a subfile record (no data is sent to the device)
- An output operation to a subfile-control record format that does not display the subfile control record or subfile records (for example, clearing, deleting, or initializing the subfile)
Restrictions and notes
- When an ERRMSG or ERRMSGID keyword is in effect, no processing other than the processing for these keywords is performed for the record. If neither keyword is in effect, the record is processed in the normal manner.
- When the RMVWDW keyword is active, error messages are not displayed.
- ERRMSG and ERRMSGID are valid for output-only, input-only, or input/output fields. These two keywords cannot be specified for a constant, hidden, program-to-system, or message field.
- For input or output capable fields, ERRMSG and ERRMSGID are in effect only if the record containing the field for which they are specified is already on the display.
- ERRMSG and ERRMSGID cannot be specified in a subfile record format (SFL keyword specified). To display error messages for a subfile, see SFLMSG (Subfile Message) and SFLMSGID (Subfile Message Identifier) keywords for display files.
- ERRMSG and ERRMSGID are ignored if the variable start line number (SLNO(*VAR) specified) has changed since the last output operation.
- If you specify ERRMSG or ERRMSGID, you should also specify RSTDSP(*YES) on the Create Display File (CRTDSPF) or Change Display File (CHGDSPF) command. Otherwise, data on the display can be lost if the file is suspended.
- On an output operation that causes the display modes to be changed, ERRMSG and ERRMSGID are ignored.
The following example shows how to specify the ERRMSG and ERRMSGID keywords.
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8 00010A R CUSMST 00020A : 00030A : 00040A : 00050A QTYORD 10A I 5 3 00060A 61 ERRMSG('No stock available' 61) 00070A 62 ERRMSG('Partial stock available' + 00080A 62) 00090A 63 ERRMSGID(MSG2000 CONSOLEMSG 63 + 00100A &RPLTXT); 00110A RPLTXT 78A P A