MCSOPMSG retrieves messages queued to an extended MCS console, and returns message information in a message data block (MDB). “Retrieving” a message more specifically means that MCSOPMSG returns the address of the MDB that contains the message and information pertaining to that message. MCSOPMSG also resumes queuing to a message storage area if queuing was previously suspended.
Use MCSOPMSG to retrieve messages delivered to the EMCS console that has been activated using the MCSOPER macro. For more information on MCSOPMSG, see z/OS MVS Programming: Authorized Assembler Services Guide.
The requirements for the caller are:
Environmental factor | Requirement |
---|---|
Minimum authorization: | Supervisor state and any PSW key |
Dispatchable unit mode: | Task |
Cross memory mode: | PASN=HASN=SASN |
AMODE: | 31-bit |
ASC mode: | Access register (AR) |
Interrupt status: | Enabled for I/O and external interrupts |
Locks: | No locks held |
Control parameters: | Must be in the primary address space |
None.
Before issuing the MCSOPMSG macro, the caller does not have to place any information into any register unless using it in register notation for a particular parameter, or using it as a base register.
Some callers depend on register contents remaining the same before and after issuing a service. If the system changes the contents of registers on which the caller depends, the caller must save them before issuing the service, and restore them after the system returns control.
None.
The standard form of the MCSOPMSG macro is written as follows:
Syntax | Description |
---|---|
name | name: Symbol. Begin name in column 1. |
␢ | One or more blanks must precede MCSOPMSG. |
MCSOPMSG | |
␢ | One or more blanks must follow MCSOPMSG. |
REQUEST=GETMSG | See Table 1 for parameters valid with REQUEST services. |
REQUEST=RESUME | |
,CMDRESP=NO | Default: CMDRESP=NO |
,CMDRESP=YES | |
,CART=cart addr | cart addr: RX-type address or register (2) - (12). |
,MASK=mask addr | mask addr: RX-type address or register (2) - (12). |
,CONSID=console id addr | console id addr: RX-type address or register (2) - (12). |
,NAME=console name addr | console name addr: RX-type address or register (2) - (12). |
,RTNCODE=return code addr | return code addr: RX-type address or register (2) - (12). |
,RSNCODE=reason code addr | reason code addr: RX-type address or register (2) - (12). |
Parameters | REQUEST=GETMSG | REQUEST=RESUME |
---|---|---|
CMDRESP | optional | not valid |
CART | optional | not valid |
MASK | optional | not valid |
NAME | either NAME or CONSID (not both) | either NAME or CONSID (not both) |
CONSID | either NAME or CONSID (not both) | either NAME or CONSID (not both) |
RTNCODE | optional | optional |
RSNCODE | optional | optional |
The parameters are explained as follows:
GETMSG retrieves a queued message from storage, and RESUME resumes message queuing.
None.
When control returns from MCSOPMSG, GPR 15 (and return code addr, if you coded RTNCODE) contains one of the following hexadecimal return codes and GPR 0 (and reason code addr, if you coded RSNCODE) contains one of the following hexadecimal reason codes.
Return Code | Reason Code | Meaning and Action |
---|---|---|
00 | None | Meaning: MCSOPMSG completed successfully.
If REQUEST=GETMSG was specified, MCSOPMSG retrieved a message; if
REQUEST=RESUME was specified, message queuing resumed. Action: None |
04 | None | Meaning: Program error. MCSOPMSG retrieved
a message, but either message queuing is disabled (if you specified
REQUEST=GETMSG) or message queuing was already enabled (if you specified
REQUEST=RESUME). Action: For REQUEST=GETMSG, continue until all messages have been retrieved. Then, attempt a REQUEST=RESUME to allow the system to send messages to that console again. |
08 | 00 | Meaning: Program error. For REQUEST=GETMSG,
MCSOPMSG attempted to retrieve a message, but there are no messages
available for the specified search criteria. Note that this is the
normal, expected, return and reason code issued when MCSOPMSG retrieved
all messages currently queued to this EMCS console. Action: None if all messages have been retrieved or change the search criteria and reissue MCSOPMSG. |
08 | 01 | Meaning: Environmental error. For REQUEST=RESUME,
queueing is not resumed because the message queue is being rebuilt. Action: If you specified ALERTECB=alert address on the MCSOPER request to define this extended MCS console, the calling program will receive control when the queue has been rebuilt. Either add this parameter to the MCSOPER specification and provide an ECB to be posted, or retry the request at a later time. |
0C | None | Meaning: Program error or environmental
error. MCSOPMSG did not retrieve a message. Message queuing is disabled,
because either the queue limit or the memory limit has been reached.
Either the dataspace has simply filled up with messages, or you specified
search criteria on the CMDRESP, CART, or MASK parameters and the dataspace
is filled with messages which do not match your search criteria. Action: If you specified search criteria on REQUEST=GETMSG, specify different search criteria, or specify only the CONSID parameter (in order to clear out the messages which do not match your search criteria). If you specified only the CONSID parameter, the dataspace is full; issue REQUEST=RESUME on the MCSOPMSG macro to start reading again. |
10 | 01 | Meaning: Program error. The specified console
is not active. Action: Verify that you specified the correct console. If so, take steps to activate the console and retry the request. If not, correct the error and retry the request. |
10 | 02 | Meaning: Program or environmental error.
The specified console was not activated by this address space. Action: Ensure that you specified the correct console and that you issued MCSOPMSG from the correct address space. Correct the problem and retry the request. |
14 | 01 | Meaning: Program error. The parameter list
contains an incorrect acronym or an incorrect version indicator. Action: Correct the problem and retry the request. |
14 | 02 | Meaning: Program error. The caller is not
in AR mode. Action: Correct the problem and retry the request. |
14 | 03 | Meaning: Environmental error. Another MCSOPMSG
request is in progress for this console. Action: This duplication can happen only if you specified MSGDLVRY=FIFO on the initial MCSOPER request. Either wait for the current request to complete and then retry, or do not specify MSGDLVRY=FIFO when you issue the MCSOPER macro. |
14 | 04 | Meaning: Program error. The extended console
was activated with MSGDLVRY=FIFO, but MCSOPMSG was issued with the
CMDRESP parameter. Action: Issue MCSOPMSG without the CMDRESP parameter. |
14 | 05 | Meaning: Program error. The caller is not
in supervisor state. Action: Reissue MCSOPMSG in supervisor state. |
18 | None | Meaning: System error. The service ended
abnormally. Action: Record the return code and supply it to the appropriate IBM support personnel. |
MDR CSECT
R12 EQU 12
R13 EQU 13
R14 EQU 14
STM R14,R12,12(R13) 0000600
BALR R12,0
USING *,R12
MCSOPMSG REQUEST=RESUME,NAME=CONSNM, X
MF=(E,DATA,COMPLETE)
LM R14,R12,12(R13)
BR R14
DROP R12
*******************************************************************
* CONSTANTS AND DATA *
*******************************************************************
CONSNM DS CL8
MCSOPMSG MF=(L,DATA)
IEAVM105
END MDR