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.

ERRMSG keyword

The format of the keyword is: 
ERRMSG('message-text' [response-indicator])

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 keyword

The format of the keyword is: 
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.

Note: Indicator text cannot be specified on the ERRMSGID 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
When the message is displayed, the following conditions occur:
  • 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.
  • 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).
Note: Some display attributes can cause fields on the IBM Color Display Station to appear as color fields.

Restoration of reversed image fields

Fields are displayed with their images reversed because of system-detected typing errors or because of the ERRMSG or the ERRMSGID keyword. Generally, the IBM i program restores the image on the next I/O operation to the display, typically the next request from your program. The restoration is done before the requested function is performed. The following list shows exceptions where requests from your program do not cause the IBM i operating system to restore 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.

Example

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