MSGID (Message Identifier) keyword for display files

You use this field-level keyword to allow an application program to identify, at program run time, the message description that contains text for a named field.

The parameter values on this keyword can specify fields that contain the message identifier, message file, and library. After the program sets the fields to the values you want, an output operation causes the message to be retrieved from the message file and displayed. The retrieved message is truncated if it is longer than the MSGID field. The retrieved message is padded with blanks if it is shorter than the MSGID field.

See System/36 environment considerations for display files for information about how to specify the MSGID keyword in files that are used in the System/36 environment.

The format of the keyword is:

MSGID(message-identifier [library-name/]message-file)
or
MSGID(*NONE)

The message-identifier parameter describes the message description containing the text for the named field. You can specify this parameter in one of two ways:

[msg-prefix] &field-name
A message-prefix and a field-name. The field-name must exist in the same record format as the MSGID field. If you specify a prefix, the length of the prefix must be three, and you must define the field-name as a character field of length four (4), and usage H, P, B, or O. If you do not specify a prefix, you must define the field-name as a character field length of seven (7), and usage H, P, B, or O.
[msgid-prefix] msg-id
You can also use a value or a combination of values to specify the message identifier. If you specify a prefix, the prefix length must be three (3), and the msg-id length must be four (4). If you do not specify a prefix, the msg-id length must be seven (7).

The message-identifier is a required parameter.

The message-file and library parameters identify the message file containing the message description. You can specify the message-file and library parameters in one of the following forms:

[library-name/]file-name
[&field1/]&field2
where the lengths of field1 and field2 are ten (10).

The field names must exist in the same record format as the MSGID field, and the fields must be defined as having character lengths of ten (10) and usage H, P, B, or O.
Combination of field names and constants:
- library-name/&field1 (length of field1 is 10)
- &field2/file-name (length of field2 is 10)

The message-file is a required parameter. If you do not specify the library parameter, *LIBL is used to search for the message file at program runtime. The library is an optional parameter.

The *NONE parameter indicates that no message text is to be displayed.

The user or program can override the message file name by using the OVRMSGF command.

You can specify multiple MSGID keywords on a field. When more than one MSGID keyword is specified, option indicators are required on all except the last MSGID keyword on a field. Option indicators are not allowed on the last (or only) MSGID keyword specified on a field. If more than one MSGID keyword is in effect for a field, the first MSGID specified is used.

You can specify multiple MSGID keywords within a record format. You can specify field names used as parameters on more than one MSGID keyword.

You must have use authority to the message file at program runtime.

The MSGID field must be output-capable (usage B or O). The length specified for the field is the length of the message text that is to be displayed. It should be the length of the longest message to be displayed.

The MSGID field itself does not appear in the output buffer, but it does appear in the input buffer if it is defined as input/output (usage B). MSGID fields that are defined as output-only cannot be used in high-level language programs.

The MSGID parameter fields (if any) appear in the output buffer, but they appear in the input buffer only if they are defined as hidden or input/output (usage H or B) fields.

A program-to-system field can be specified as the message-id, file, or library name.

You cannot specify MSGID in a subfile record format (SFL keyword).

The following keywords cannot be specified on a field with the MSGID keyword:

DFT
DFTVAL
FLTFIXDEC
FLTPCN
MSGCON

Example

The following example shows how to specify the MSGID keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A          R RECORD1
     A            MSGFIELD1     40A  B 02 10MSGID(CPD0001 QGPL/USRMSG)
     A  01        MSGFIELD2     10A  O 02 60
     A  25                                  MSGID(&MSGIDNUM &MSGFILENM);
     A                                      MSGID(CPD1234 QGPL/USRMSG)
     A            MSGFIELD3     80A  B 02 60
     A                                      MSGID(USR &MSGNBR +
     A                                      QGPL/&MSGGILENM);
     A            MSGIDNUM       7A  P
     A            MSGFILENM     10A  H
     A            MSGNBR         4A  B 07 01
     A

When RECORD1 is displayed:

MSGFIELD1 contains the first 40 characters of message CPD0001 from message file USRMSG in library QGPL. Because the field is input/output (usage B), the value of the field can be changed by the user.
If option indicator 01 is off, MSGFIELD2 is not displayed. When option indicators 01 and 25 are on, MSGFIELD2 contains the first 10 characters of the message identified by the fields MSGIDNUM and MSGFILENM. Values for MSGIDNUM (the message identifier) and MSGFILENM (the message file) must be set in the program before the display of RECORD1.
When option indicator 01 is on but option indicator 25 is off, MSGFIELD2 contains the first 10 characters of message CPD1234 from the message file USRMSG in library QGPL. Because MSGFIELD2 is an output-only field (usage O), it cannot be used in the program.
MSGFIELD3 contains the first 80 characters of the message identified by the prefix USR, the message number set in field MSGNBR, and the message file set in field MSGFILENM.