How to define a message

Messages generally should appear in collating sequence by message ID. Each message within the library consists of two required lines and (optionally) additional long message lines. The additional lines can contain up to 512 bytes of long message text. These diagrams illustrate the syntax for defining messages:

Line 1 syntax

Line 2 syntax

Additional long message text lines – optional.

Line 3 syntax

Line 4 syntax

Line 5 syntax

msgid

Required. Each message is referred to by a message identifier (ID). A message ID can be four to eight characters long. It is defined as follows:

• Prefix: one to five alphabetic characters (A-Z, #, $, or @)
• Number: three numeric characters (0-9)
• Suffix (optional): one alphabetic character.

If the prefix is five characters long, the suffix must be omitted so that the total length does not exceed eight characters. Use the message ID suffix if more than 10 messages are to be included in one member.

short message

Optional. If a short message is specified on an ISPF panel, it is displayed first (before the long message). Its maximum length is 24 bytes. The short message is displayed in a pop-up window if the text is longer than will fit in the short message area or if you defined a message window using the .WINDOW keyword for the message. Otherwise, the short messages are right-justified and displayed, with a high intensity attribute, either:

• At the right end of the first line on the screen, if an action bar is not defined
• At the right end of the line following the action bar

If the user enters the HELP command, the long message is displayed, with a high intensity attribute. If the user enters the HELP command again, tutorial mode is entered.

The location of the short and long messages in a user-designed panel is specified by the SMSG and LMSG keywords. These keywords are defined under Defining the body section.

When messages are written to the ISPF log file, both the short message, if any, and the long message are written in the same output line. The short message comes first, followed by the long message.

Note: For long or short messages in pop-up windows, if the message originates from panel processing, such as a verification error message, the message pop-up window is placed adjacent to the field that is the object of the validation.

.LOG=YES

Optional. Ensures that ISPF will write a copy of the message to the ISPF log, if it is allocated.

.HELP=panel | *

Optional. (Can be abbreviated to .H) If the user enters tutorial mode, the panel name specified by .HELP is the first tutorial page displayed. If .HELP=* is specified, the first tutorial page is the one specified in the panel definition, that is, the panel on which this message is being displayed. The default is *.

NOKANA|KANA

Optional. The NOKANA keyword allows messages to contain lowercase characters, and still display correctly on a Katakana terminal. Because hexadecimal codes for some lowercase characters overlap those of some Katakana characters, they would display as meaningless characters on a Katakana terminal. If the NOKANA keyword is present in a message definition, ISPF translates any lowercase message characters to uppercase before displaying the message on a Katakana terminal.

In summary, if the terminal is Katakana, and:

• KANA is specified, all characters are left as is.
• NOKANA is specified, lowercase characters are translated to uppercase.
• If neither KANA nor NOKANA is specified, all characters are left as is.

If the terminal is not Katakana, and:

• KANA is specified, lowercase characters are displayed as periods
• NOKANA is specified, all characters are left as is.
• If neither KANA nor NOKANA is specified, all characters are left as is.

Note:

1. On non-Katakana terminals, the KANA keyword can be used to display overlapping Katakana characters as periods rather than as meaningless lowercase characters.
2. On Katakana terminals, the NOKANA keyword is necessary in messages containing lowercase English characters.
3. See Extended code page support for the discussion of the treatment of the KANA or NOKANA keywords if a CCSID is specified.

.ALARM=YES|NO

Optional. (Can be abbreviated to .A) If .ALARM=YES is specified, the audible alarm sounds when the message displays. If .ALARM=NO is specified, the alarm does not sound unless .ALARM is set to YES in the panel definition. The default is NO.

.WINDOW=RESP|NORESP|LRESP|LNORESP

Optional. (Can be abbreviated to .W) The .WINDOW keyword tells ISPF to display the message in a message pop-up window.

.WINDOW=RESP (R is a valid abbreviation for RESP) requests ISPF to display both long and short messages in a message pop-up window that requires the user to press Enter before data can be entered into the underlying panel. The user cannot enter data or interact with the underlying panel until Enter (or some other attention key) is pressed.

.WINDOW=NORESP (N is a valid abbreviation for NORESP) requests ISPF to display both long and short messages in a message pop-up window that does not require direct user response. The user can enter data into the underlying panel while this message is being displayed.

.WINDOW=LRESP (LR is a valid abbreviation for LRESP) requests ISPF to display only long messages in a message pop-up window that requires the user to press Enter before data can be entered into the underlying panel. The user cannot enter data or interact with the underlying panel until Enter (or some other attention key) is pressed.

.WINDOW=LNORESP (LN is a valid abbreviation for LNORESP) requests ISPF to display only long messages in a message pop-up window that does not require direct user response. The user can enter data into the underlying panel while this message is being displayed.

The MSGLOC parameter on the DISPLAY, TBDISPL, and SETMSG services controls the placement of the message pop-up window. For messages that originate from panel processing, such as a verification error message, the message pop-up window is placed adjacent to the field which is the object of the validation. The window placement will be such that it does not overlay the object field, if possible. If no correlation can be made between the validation and a field (such as when the variable being validated is not a panel field name), the message pop-up window is displayed at the bottom of the logical screen or below the active pop-up window, if one exists. See the sections on these services in the z/OS ISPF Services Guide for a complete description of the MSGLOC parameter.

.TYPE=NOTIFY|WARNING|ACTION|CRITICAL

Optional. (Can be abbreviated to .T) The .TYPE keyword in the message definition identifies the type of message. There are four types of messages, NOTIFY, WARNING, ACTION, and CRITICAL. N, W, A, and C are valid abbreviations.

This table summarizes the characteristics of the different types of messages.

Table 1. Message characteristics

Type	Color	Intensity	Placement	Response	Alarm
NOTIFY	White	High	Message area or pop-up window	Optional	Off
WARNING	Yellow	High	Message area or pop-up window	Optional	On
ACTION	Red	High	Message area or pop-up window	Optional	On
CRITICAL	Red	High	Pop-up window	Required	On

The .TYPE keyword overrides any .ALARM value that can be specified. A .TYPE=CRITICAL message is always displayed as though .WINDOW=RESP was specified. The defined color and highlighting characteristics apply to messages displayed in the default short/long location and a pop-up message window. The dialog application controls the field attributes for alternate message location fields.

long message

Required. If a short message is not specified, the long message is automatically displayed first, with a high intensity attribute, in the long message area or in a message pop-up window. The long message is displayed in a pop-up window if the text is longer than will fit in the long message area, if you defined a message window using the .WINDOW keyword for the message, or if you have selected this option on the Settings panel.

The location of the short and long messages in a user-designed panel is specified by the SMSG and LMSG keywords. These keywords are defined under Defining the body section.

The maximum length of the long message text is 512 bytes. If the message text is greater than 512 bytes, it will be truncated. Messages greater than 78 bytes require multiple long message lines. The continuation of the long message text into additional lines is indicated by one or more spaces following the ending quote (') followed by a plus (+) sign. For example:

ISPX001 'short message text'
'Long message text' +
' continued over ' +
'multiple lines.  The maximum length is ' +
'512 bytes.'

For the best results, use the fewest number of message lines possible.

ISPX001 'short message text'
'Long message text continued over multiple lines.  The maximum' +
' length is 512 bytes.'

Consecutive SOSI characters resulting from multiple lines of DBCS data are automatically removed. For example,

'Long messageSDBS' +
             O  I
'SCSSdata.'
 O  I

Result:  Long messageSDBCSSdata.
                     O    I

The ending SI in the first record and the beginning SO in the second record are automatically removed.

When messages are written to the ISPF log file, both the short message, if any, and the long message are written in the same output line. The short message comes first, followed by the long message.

The long message text will be written to multiple records if the text is greater than 78 characters.

Existing dialogs which have VDEFINEd the system variable ZERRLM as 78 characters should be updated to VDEFINE this variable as 512 characters.

Note: For long or short messages in pop-up windows, if the message originates from panel processing, such as a verification error message, the message pop-up window is placed adjacent to the field which is the object of the validation.