Using the command and response token (CART) and mask

The command and response token (CART) is a keyword and subcommand for the TSO/E CONSOLE command and an argument on the GETMSG function. You can use the CART to associate MVS™ system and subsystem commands you issue with their corresponding responses.

To associate MVS system and subsystem commands with their responses, when you issue an MVS command, specify a CART on the command invocation. The CART is then associated with any messages that the command issues. During the console session, solicited messages that are routed to your user's console should not be displayed at the terminal. Use GETMSG to retrieve the solicited message from the command you issued. When you use GETMSG to retrieve the solicited message, specify the same CART that you used on the command invocation.

If several programs use the CONSOLE command's services and run simultaneously in one TSO/E address space, each program must use unique CART values to ensure it retrieves only messages that are intended for that program. You should issue all MVS system and subsystem commands with a CART. Each program should establish an application identifier that the program uses as the first four bytes of the CART. Establishing application identifiers is useful when you use GETMSG to retrieve messages. On GETMSG, you can use both the cart and mask arguments to ensure you retrieve only messages that begin with the application identifier. Specify the hexadecimal digits FFFFFFFF for at least the first four bytes of the mask value. For example, for the mask, use the value ‘FFFFFFFF00000000’X.

For the cart argument, specify the application identifier as the first four bytes followed by blanks to pad the value to eight bytes. For example, if you use a four character application identifier of APPL, specify 'APPL ' for the CART. If you use a hexadecimal application identifier of C19793F7, specify 'C19793F7'X for the CART. GETMSG ANDs the mask and CART values you specify, and also ANDs the mask with the CART values for the messages. GETMSG compares the results of the AND operations, and if a comparison matches, GETMSG retrieves the message.

You may also want to use CART values if you have an exec using console services that calls a second exec that also uses console services. The CART ensures that each exec retrieves only the messages intended for that exec.

Using different CART values in one exec is useful to retrieve the responses from specific commands and perform appropriate processing based on the command response. In general, it is suggested that your exec uses a CART for issuing commands and retrieving messages. For more information about console sessions and how to use the CART, see Writing REXX Execs to perform MVS operator activities.

Examples:

The following are some examples of using GETMSG.

You want to retrieve a solicited message in variables starting with the stem "CONSMSG.". You do not want GETMSG to wait if the message has not yet been routed to the user's console. Specify GETMSG as follows:
```
msg = GETMSG('CONSMSG.','SOL')
```
You want to retrieve a solicited message in variables starting with the stem "DISPMSG.". You want GETMSG to wait up to 2 minutes (120 seconds) for the message. Specify GETMSG as follows:
```
mcode = getmsg('dispmsg.','sol',,,120)
```
You issued an MVS command using a CART value of ‘C1D7D7D3F2F9F6F8’X. You want to retrieve the message that was issued in response to the command and place the message in variables starting with the stem "DMSG". You want GETMSG to wait up to 1 minute (60 seconds) for the message. Specify GETMSG as follows.
```
msgrett = getmsg('dmsg','sol','C1D7D7D3F2F9F6F8'X,,60)
```

You want to retrieve a list of unsolicited messages, including both single line messages and multiple line messages.

mrc = 0
msgindex = 0 
do while mrc = 0
  mrc = GETMSG('CNSL.','UNSOL',,,3)
  if mrc > 0 then leave
  do i = 1 to CNSL.0
    msgindex = msgindex+1
    msg.msgindex = CNSL.i
  end
end

msg.0 = msgindex

do i = 1 to msg.0
  say msg.i
end

Your exec has defined an application identifier of APPL for using CARTs. Whenever you issue an MVS command, you specify a CART of APPLxxxx, where xxxx is a four-digit number. For example, for the first MVS command, you use a CART of APPL0001. For the second MVS command, you use a CART of APPL0002, and so on.
You want to use GETMSG to retrieve solicited messages that are intended only for your exec. You can specify the mask and cart arguments to ensure that GETMSG retrieves only messages that are for the MVS commands your exec invoked. Specify 'FFFFFFFF00000000'X for the mask. Specify 'APPL ' (padded with blanks to 8 characters) for the CART. You also want to wait up to 30 seconds for the message.
```
conmess = getmsg('msgc.','sol','APPL    ','FFFFFFFF00000000'X,30)
```