SETMSG—set next message

The SETMSG service allows a dialog function to display a message on the next panel that is written by ISPF to the terminal. The next panel does not have to be displayed as a result of action taken by the function routine. In fact, the function routine can have terminated before the next panel is displayed.

The specified message is retrieved from the message library at the time the set message request is issued. Values for all variables defined in the message are substituted at this time and the message is saved in a message area for the application. When the next panel is displayed, the message is retrieved from the save area and displayed on the panel.

If multiple set-message requests have been issued before a panel is displayed, only the last message is displayed. You can use the optional COND parameter to request that the specified message is to be displayed only if there is no prior SETMSG request pending. A message specified on the panel display request is overridden by any outstanding set next message request.

A message that has been set with SETMSG is displayed the next time any full-screen output is sent to the display, regardless of whether that output is a panel, table display, Browse data, or Edit data. The SETMSG service executed in the batch environment causes the message to be written to the log at the point at which it would normally be sent to the screen for display.

The message is preserved across CONTROL NONDISPL; that is, the message is displayed on the next actual output to the terminal. If the next panel is processed in non-display mode, the message remains pending, to be displayed with any following panel that is processed in display mode.

If the message refers to a help panel, the help panel should not include substitutable variables. Variables in related help panels contain the values current at the time the HELP command is issued, not at the time the SETMSG service is invoked.

Command invocation format


>>-ISPEXEC--SETMSG--MSG(message-id)--+------+------------------->
                                     '-COND-'   

>--+----------------------------+------------------------------><
   '-MSGLOC(message-field-name)-'

Call invocation format


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


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

>--,-+-'CONDbbbb'-+--,-+-message-field-name-+-)----------------><
     '-'b'--------'    '-'b'----------------'

Parameters

message-id: Specifies the identification of the message to be displayed on the next panel.
COND: Specifies that the message is to be displayed on the next panel only if no prior SETMSG request is pending.
message-field-name: Used to position the message pop-up window. If the application specifies this parameter, the Dialog Manager positions the message pop-up relative to the named field.
If this parameter is omitted and a message is displayed in a message pop-up window, the window is displayed at the bottom of the logical screen or below the active ADDPOP pop-up window if one exists.

For compatibility with later versions, this parameter should be specified only when the message will display in a pop-up window.
Note: When running in GUI mode, this parameter is ignored.
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.
4: SETMSG with COND parameter issued and a SETMSG request was pending.
12: The specified message field name or message not be found.
20: Severe error.

Example 1

On the next panel that is displayed, put a message whose ID, ABCX015, is in a dialog variable named TERMSG.

ISPEXEC SETMSG MSG(&TERMSG )

Set the program variable BUFFER to contain:

SETMSG MSG(ABCX015 )

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

CALL ISPEXEC (BUFLEN, BUFFER);

or alternately

CALL ISPLINK ('SETMSG  ','ABCX015 ');

Example 2

This SETMSG and DISPLAY request displays message TSTA110 in a message pop-up window that requires a response from the end user before interaction with the underlying panel is possible. The message pop-up window is positioned relative to the field FLD1.

PROC 0
ISPEXEC SETMSG MSG(TSTA110) MSGLOC(FLD1)
ISPEXEC DISPLAY PANEL(A)

Using this message definition for TSTA110

TSTA110               .WINDOW=RESP
'ENTER NUMERIC DATA'

Results in:

                 PANEL A



FIELD===> FLD1
         ┌────────────────────┐
         │                    │
         │ ENTER NUMERIC DATA │
         │                    │
         └────────────────────┘