MSG (Message)

The MSG tag defines a message within a message member.

Syntax


>>-<MSG--SUFFIX=message-suffix-number--------------------------->

>--+---------------------------+--+-----------------------+----->
   '-HELP=-+-help-panel-name-+-'  |          .-INFO-----. |   
           +-%varname--------+    '-MSGTYPE=-+-WARNING--+-'   
           '-*---------------'               +-ACTION---+     
                                             +-CRITICAL-+     
                                             '-%varname-'     

>--+---------------------------+--+------------------+---------->
   |           .-AREA--------. |  '-DISP=-+-KANA---+-'   
   '-LOCATION=-+-MODAL-------+-'          '-NOKANA-'     
               +-MODAL(L)----+                           
               +-MODELESS----+                           
               +-MODELESS(L)-+                           
               '-%varname----'                           

>--+---------------------+--+---------------------+------------->
   |        .-NO-------. |  |         .-NONE----. |   
   '-ALARM=-+-YES------+-'  '-ABBREV=-+-KEYWORD-+-'   
            '-%varname-'              +-VALUE---+     
                                      '-BOTH----'     

>--+------------------+--+-------------------------+-->--------->
   |         .-FLOW-. |  '-SMSG=short-message-text-'      
   '-FORMAT=-+-ASIS-+-'                                   

>--+--------------+--+--------+--------------------------------><
   '-message-text-'  '-</MSG>-'

Parameters

SUFFIX=message-suffix-number

This attribute specifies the suffix of the message. The suffix consists of either 1 numeric character (0-9) or a numeric character (0-9) and an optional alpha suffix character as defined for ISPF messages, which is added to the MSGMBR message-member-name to form the ISPF message ID.

Each message-suffix-number within a message member must be unique. Attempts to define duplicate suffixes result in a warning message and the duplicate MSG is ignored.

HELP=help-panel-name | %varname | *

Specifies the name of the help panel that is associated with this message and that is displayed if the user requests help for the message.

If you specify a help panel, ISPDTLC generates ".HELP=help-panel-name" (or ".HELP=&varname" or ".HELP=*") in the ISPF message ID definition. If you don't specify a help panel, no help is available for the message.

The help-panel-name must follow the standard naming convention described in Rules for variable names.

MSGTYPE=INFO | WARNING | ACTION | CRITICAL | %varname

This attribute specifies the severity of the message. ISPF displays INFO messages without an alarm. ISPF displays WARNING, ACTION, and CRITICAL messages with an alarm.

ACTION and CRITICAL message types are used to identify the most severe errors. This level of error usually requires a user response. ISPF always displays CRITICAL messages in a pop-up. ACTION messages are displayed based on the value of the LOCATION attribute.

The %varname value specifies that the value INFO, WARNING, ACTION, or CRITICAL is provided in the named variable by the application before issuing the message.

The conversion utility changes INFO to .TYPE=NOTIFY when formatting the message member.

ISPF recognizes message types (.TYPE=) of NOTIFY, WARNING, ACTION, and CRITICAL. ISPF uses the TYPE value specified in conjunction with the value of .WINDOW to determine the display characteristics of the message. The .WINDOW value is generated from the value specified for the LOCATION attribute. For more information on ISPF messages, refer to z/OS ISPF Dialog Developer's Guide and Reference.

This attribute specifies how the message is displayed.

LOCATION=AREA (the default) specifies that the message is to appear in the panel message area. However, if the text of the message exceeds the length of the panel message area, ISPF displays the message in a pop-up.

LOCATION=MODAL specifies that the message is to appear in a pop-up which requires a user response. The conversion utility generates .WINDOW=RESP in the ISPF message definition.

LOCATION=MODAL(L) specifies that the long message is to appear in a pop-up which requires a user response. The conversion utility generates .WINDOW=LRESP in the ISPF message definition.

LOCATION=MODELESS specifies that the message is to appear in a pop-up which does not require a user response. The conversion utility generates .WINDOW=NORESP in the ISPF message definition.

LOCATION=MODELESS(L) specifies that the long message is to appear in a pop-up which does not require a user response. The conversion utility generates .WINDOW=LNORESP in the ISPF message definition.

LOCATION=%varname specifies that the value AREA, MODAL, or MODELESS is provided in the named variable by the application before issuing the message. The conversion utility generates .WINDOW=&VARNAME in the ISPF message definition.

DISP=KANA | NOKANA

This attribute specifies the addition of either the KANA or NOKANA keyword to the message control information.

ALARM=NO | YES | %varname

This attribute controls the use of the alarm when the message is displayed.

ALARM=%varname specifies that the value YES or NO is provided in the named variable by the application before issuing the message.

ABBREV=NONE | KEYWORD | VALUE | BOTH

This attribute specifies the format of the message control information. You may abbreviate the message control keyword, the message control keyword value, or both.

FORMAT=FLOW | ASIS

This attribute specifies the formatting of the message-text.

The default of FLOW means to flow the message text continuously within the WIDTH of the MSGMBR.

When FORMAT=ASIS, the generated message preserves embedded blanks, but drops leading or trailing blanks.

SMSG=short-message-text

You can provide a short message of up to 24 bytes which ISPF displays in the short message area of the panel.

The VARSUB tag is not supported within the short-message-text. If a substitution variable is required, you may code "&variable" to place the variable name in the message. A short-message-text consisting of more than one word must be enclosed within quotation marks (" "). If the short-message-text contains a single apostrophe ('), the conversion utility generates double apostrophes as it does for message-text, as described for the next parameter (message-text).

The short message is not recommended by the CUA Architecture definition.

A short message cannot be created unless the message-text is also provided.

message-text

This is the text of the message. The message-text is placed in the long-message area of a message file. The message-text is limited to 512 characters. The conversion utility truncates all message-text after 512 characters and issues a warning message. If no message-text is coded, then no message is generated.

Several characters within the long message area have a special meaning to ISPF. If you use the apostrophe within message-text, the conversion utility generates double apostrophes so the single apostrophe is displayed when ISPF issues the message. If you use the ampersand (&) within the long message, it must be coded as "&amp" followed by a blank or semicolon to be interpreted as a literal ampersand character (through ENTITY substitution).

For ISPF substitution variables, you should code the VARSUB tag. ISPF does not perform output translation (specified in the associated VARCLASS tag) on ISPF runtime substitution variables.

See z/OS ISPF Dialog Developer's Guide and Reference for a description of the syntax rules you should use for defining consistent messages.

Comments

The MSG tag defines a message within a message member. Each MSG definition within a message member must have a unique message-suffix-number.

Restrictions

You must code the MSG tag within a MSGMBR definition. See MSGMBR (Message Member) for a complete description of this tag.
When a "%varname" notation is found on any of the attributes that allow a variable name, the "%varname" entry must follow the standard naming convention described in Rules for “%variable” names.

Processing

Table 1. Tags you can code within a MSG definition
Tag	Reference	Usage	Required
VARSUB	VARSUB (Variable Substitution)	Multiple	No

Examples

Here is markup that contains the message member MSGG88, which contains nine MSG definitions. The text of messages MSGG883 and MSGG888 contain variable substitutions. Figure 1 shows the generated ISPF message member.

<!DOCTYPE DM SYSTEM>

<VARCLASS NAME=msgcls TYPE='char 20'>
<VARLIST>
  <VARDCL NAME=phoneno VARCLASS=msgcls>
  <VARDCL NAME=cnum    VARCLASS=msgcls>
</VARLIST>

<MSGMBR NAME=msgg88>
  <MSG SUFFIX=1 disp=kana abbrev=keyword>Name must be alphabetic.
  <MSG SUFFIX=2 disp=nokana abbrev=value>Enter only number of days.
  <MSG SUFFIX=3 MSGTYPE=critical>The only rooms we have available
      are either SINGLE or DOUBLE.  Please call the manager of the hotel
      who will arrange equivalent lodging at another
      hotel in the area.  This is our mistake, and we will, of course,
      pick up the bill.  Please call collect <VARSUB VAR=phoneno>.
  <MSG SUFFIX=4 MSGTYPE=action LOCATION=modal abbrev=both>
      Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.
  <MSG SUFFIX=5 MSGTYPE=warning LOCATION=modeless>Please enter your name.
  <MSG SUFFIX=6>Please enter Y or N.
  <MSG SUFFIX=7>Card number is a seven-digit number.
  <MSG SUFFIX=8 MSGTYPE=warning>The card number you entered,
       <VARSUB VAR=cnum> is not valid.
  <MSG SUFFIX=9>Message '9' contains embedded quotes.
</MSGMBR>

Figure 1. Messages

MSGG881 .T=NOTIFY KANA
'Name must be alphabetic.'
MSGG882 .TYPE=N NOKANA
'Enter only number of days.'
MSGG883 .TYPE=CRITICAL
'The only rooms we have available are either SINGLE or DOUBLE. Please call th' +
'e manager of the hotel who will arrange equivalent lodging at another hotel ' +
'in the area. This is our mistake, and we will, of course, pick up the bill. ' +
'Please call collect &PHONENO.'
MSGG884 .T=A .W=R
'Please enter either BIGCHARGE, V I S T A, EZCARD, CHECK, or CASH.'
MSGG885 .TYPE=WARNING .WINDOW=NORESP
'Please enter your name.'
MSGG886 .TYPE=NOTIFY
'Please enter Y or N.'
MSGG887 .TYPE=NOTIFY
'Card number is a seven-digit number.'
MSGG888 .TYPE=WARNING .ALARM=YES
'The card number you entered, &CNUM is not valid.'
MSGG889 .TYPE=NOTIFY
'Message '9'' contains embedded quotes.'