GETMSG


>>-GETMSG(msgstem----------------------------------------------->

>--+------------------------------------------------------------+-->
   '-,-+---------+-+------------------------------------------+-'   
       '-msgtype-' '-,-+------+-+---------------------------+-'     
                       '-cart-' '-,-+------+-+------------+-'       
                                    '-mask-' '-,-+------+-'         
                                                 '-time-'           

>--)-----------------------------------------------------------><

GETMSG returns a function code that replaces the function call and retrieves, in variables, a message that has been issued during a console session. Table 1 lists the function codes that GETMSG returns.

Use GETMSG during an extended MCS console session that you established using the TSO/E CONSOLE command. Use GETMSG to retrieve messages that are routed to the user's console but that are not being displayed at the user's terminal. The message can be either solicited (a command response) or unsolicited (other system messages), or either. GETMSG retrieves only one message at a time. The message itself may be more than one line. Each line of message text is stored in successive variables. For more information, see msgstem.

To use GETMSG, you must:

Have CONSOLE command authority
Have solicited or unsolicited messages stored rather than displayed at the terminal during a console session. Your installation may have set up a console profile for you so that the messages are not displayed. You can also use the TSO/E CONSPROF command to specify that solicited or unsolicited messages should not be displayed during a console session.
Issue the TSO/E CONSOLE command to activate a console session.

You can use the GETMSG function only in REXX execs that run in the TSO/E address space.

Environment Customization Considerations: If you use IRXINIT to initialize language processor environments, note that you can use GETMSG only in environments that are integrated into TSO/E (see Types of environments - integrated and not integrated into TSO/E).

Responses to commands sent through the network to another system might be affected as follows:

The responses might not be returned as solicited even if a CART was specified and preserved; UNSOLDISPLAY(YES) may be required.
If the receiving system does not preserve the extended console identifier, ROUTCODE(ALL) and UNSOLDISPLAY(YES) might be required to receive the responses.

For information about ROUTCODE, see z/OS MVS Initialization and Tuning Reference. For information about UNSOLDISPLAY, see z/OS TSO/E System Programming Command Reference.

Table 1 lists the function codes that replace the function call. The GETMSG function raises the SYNTAX condition if you specify an incorrect argument on the function call or you specify too many arguments. A SYNTAX condition is also raised if a severe error occurs during GETMSG processing.

Table 1. Function codes for GETMSG that replace the function call
Function code	Description
0	GETMSG processing was successful. GETMSG retrieved the message.
4	GETMSG processing was successful. However, GETMSG did not retrieve the message. There are several reasons why GETMSG may not be able to retrieve the message based on the arguments you specify on the function call. GETMSG returns a function code of 4 if one of the following occurs: No messages were available to be retrieved The messages did not match the search criteria you specified on the function call You specified the `time` argument and the time limit expired before the message was available.
8	GETMSG processing was successful. However, you pressed the attention interrupt key during GETMSG processing. GETMSG did not retrieve the message.
12	GETMSG processing was not successful. A console session is not active. The system issues a message that describes the error. You must issue the TSO/E CONSOLE command to activate a console session.
16	GETMSG processing was not successful. The console session was being deactivated while GETMSG was processing. The system issues a message that describes the error.

The arguments you can specify on the GETMSG function are:

msgstem

the stem of the list of variables into which GETMSG places the message text. To place the message text into compound variables, which allow for indexing, msgstem should end with a period (for example, "messg."). GETMSG places each line of the retrieved message into successive variables. For example, if GETMSG retrieves a message that has three lines of text, GETMSG places each line of message text into the variables messg.1, messg.2, messg.3. GETMSG stores the number of lines of message text in the variable ending in 0, messg.0.

Note: If messg.0=0, no lines are associated with this message. This message might be a delete operator message (DOM) request. For more information about the DOM macro, see z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN.

If msgstem does not end with a period, the variable names are appended with consecutive numbers. For example, suppose you specify msgstem as "conmsg" (without a period). If GETMSG retrieves a message that has two lines of message text, GETMSG places the text into the variables conmsg1 and conmsg2. The variable conmsg0 contains the number of lines of message text, which is 2.

In addition to the variables into which GETMSG places the retrieved message text, GETMSG also sets additional variables. The additional variables relate to the field names in the message data block (MDB) for MVS/ESA System Product. For more information about these variables, see Additional variables that GETMSG sets.

msgtype

the type of message you want to retrieve. Specify one of the following values for msgtype:

SOL
indicates that you want to retrieve a solicited message. A solicited message is the response from an MVS™ system or subsystem command.
UNSOL
indicates that you want to retrieve an unsolicited message. An unsolicited message is any message that is not issued in response to an MVS system or subsystem command. For example, an unsolicited message may be a message that another user sends you or a broadcast message.
EITHER
indicates that you want to retrieve either type of message (solicited or unsolicited). If you do not specify the msgtype argument, EITHER is the default.

cart

the command and response token (CART). The CART is a token that lets you associate MVS system commands and subcommands with their responses. When you issue an MVS system or subsystem command, you can specify a CART on the command invocation. To use GETMSG to retrieve a particular message that is in direct response to the command invoked, specify the same CART value.

GETMSG uses the CART you specify as a search argument to obtain the message. If you specify a CART, GETMSG compares the CART you specify with the CARTs for the messages that have been routed to the user's console. GETMSG retrieves the message, only if the CART you specify matches the CART associated with the message. Otherwise, no message is retrieved.

The cart argument is used only if you are retrieving solicited messages, that is, the value for the msgtype argument is SOL. The CART is ignored if you specify UNSOL or EITHER for msgtype.

The cart argument is optional. If you do not specify a CART, GETMSG retrieves the oldest message that is available. The type of message retrieved depends on the msgtype argument.

For cart, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example:

'C1D7D7C1F4F9F4F1'X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks. If you specify more than 8 characters or more than 16 hexadecimal digits, the value is truncated to the first 8 characters or 16 digits and no error message is issued.

For more information, see Using the command and response token (CART) and mask.

mask

search argument that GETMSG uses as a mask with the cart argument for obtaining a message. If you specify a mask, GETMSG ANDs the mask value with the CART value that you specify on the GETMSG function. GETMSG also ANDs the mask with the CARTs associated with the messages that have been routed to the user's console. GETMSG then compares the results of the AND operations. If a comparison matches, GETMSG retrieves the message. Otherwise, no message is retrieved.

The mask argument is valid only if you are retrieving solicited messages and are using a CART. That is, mask is valid only if you specify SOL for msgtype and you specify the cart argument.

The mask argument is optional. If you do not specify a mask, GETMSG does not use a mask value when comparing CART values.

For mask, you can specify a character string of 1-8 characters or a hexadecimal string of 1-16 hexadecimal digits. For example:

'FFFFFFFF00000000'X

If you specify less than 8 characters or less than 16 hexadecimal digits, the value is padded on the right with blanks. If you specify more than eight characters or more than 16 hexadecimal digits, the value is truncated to the first eight characters or 16 digits and no error message is issued.

For more information, see Using the command and response token (CART) and mask.

time

the amount of time, in seconds, that GETMSG should wait, if the requested message has not yet been routed to the user's console. If you specify a time value and the time expires before the message is routed to the user's console, GETMSG does not retrieve the message. Otherwise, if the message is available before the time expires, GETMSG retrieves the message.

If you do not specify time, GETMSG uses a time value of 0 seconds. If the message has not been routed to the user's console, GETMSG does not retrieve the message.