GETMSG—get a message

The GETMSG service obtains a message and related information from the message file. The short and long message text, help panel name, and alarm indicator can be obtained for a specified message-id. Values for all variables defined in the message are substituted when the message text is retrieved. If the desired message information is not present for the short message text, long message text, or help panel name, the corresponding variable name specified in the GETMSG service request is set to a null value. If the alarm indicator is not present on the message, a value of "NO" is returned in the alarm-name variable.

A message type of critical (.TYPE=CRITICAL) on the message definition statement overrides the values specified for the alarm and window keywords. For critical messages, the dialog manager sounds the alarm and places the message in a message pop-up window that requires a response. If GETMSG asks for the .ALARM value to be returned, the value returned will be YES, reflecting the fact that .TYPE=CRITICAL has forced that value. This is the case if .ALARM was not specified (which would normally default to NO) or if .ALARM=NO is actually defined for the message.

All the parameters except the message-id are optional. If the optional parameters are omitted, GETMSG simply validates the existence of the specified message.

Command invocation format


>>-ISPEXEC--GETMSG--MSG(message-id)----------------------------->

>--+------------------------------+----------------------------->
   '-SHORTMSG(short-message-name)-'   

>--+----------------------------+--+-------------------+-------->
   '-LONGMSG(long-message-name)-'  '-ALARM(alarm-name)-'   

>--+-----------------+--+-----------------+--------------------->
   '-HELP(help-name)-'  '-TYPE(type-name)-'   

>--+---------------------+--+-------------------+--------------><
   '-WINDOW(window-name)-'  '-CCSID(ccsid-name)-'

Call invocation format


>>-CALL--ISPEXEC--(buf-len,--buffer);--------------------------><


>>-CALL--ISPLINK--('GETMSGbb'--,message-id---------------------->

>--,-+-short-message-name-+--,-+-long-message-name-+------------>
     '-'b'----------------'    '-'b'---------------'   

>--,-+-alarm-name-+--,-+-help-name-+--,-+-type-name-+----------->
     '-'b'--------'    '-'b'-------'    '-'b'-------'   

>--,-+-window-name-+--,-+-ccsid-name-+-);----------------------><
     '-'b'---------'    '-'b'--------'

Parameters

message-id: Specifies the identification of the message for which information is to be retrieved.
short-message-name: Specifies the name of a variable into which the short message text, if any, is to be stored.
long-message-name: Specifies the name of a variable into which the long message text is to be stored.
alarm-name: Specifies the name of a variable into which the alarm indicator of "NO" or "YES" is to be stored.
help-name: Specifies the name of a variable into which the help panel name, if any, is to be stored.
type-name: Specifies the name of the variable into which the message type, if any, (notify, warning or critical) is to be stored.
window-type: Specifies the name of the variable into which the window type, if any (RESP or NORESP), is to be stored.
ccsid-name: Specifies the name of the variable into which the CCSID, if any, is to be stored.
buf-len: Specifies a fullword fixed binary integer containing the length of "buffer".
buffer: Specifies a buffer containing the name of the service and its parameters in the same form as they would appear in an ISPEXEC call for a command procedure.

Return codes

These return codes are possible:

0: Normal completion.
12: The specified message could not be found.
20: Severe error.

Example

For the message named ABCS102, return the text of the long message in variable ERRMSG and the help panel name in variable HPANEL.

ISPEXEC GETMSG MSG(ABCS102) LONGMSG(ERRMSG) HELP(HPANEL)

or Set the program variable BUFFER to contain:

GETMSG MSG(ABCS102) LONGMSG(ERRMSG) HELP(HPANEL)

Set program variable BUFLEN to the length of the variable BUFFER. Enter the command:

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('GETMSG  ','ABCS102 ',' ','ERRMSG ',
              ' ','HPANEL ');