Description

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.

Environment

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

Programming requirements

The console for which you are issuing this macro must already be activated.
If you specified MSGDLVRY=NONE on the MCSOPER macro for a particular console, do not issue MCSOPMSG for that console.
Only the address space that activated the extended console can issue MCSOPMSG for that console.
If you specified MSGDLVRY=FIFO for MCSOPER and you are running in a multi-task environment, ensure that only one task is currently performing MCSOPMSG for the console at any time.
You can use the CMDRESP, CART, and MASK parameters only if you activate the console with MCSOPER MSGDLVRY=SEARCH.
You must include mapping macro IEAVM105. You can use mapping macro IEAVM105 to access fields in the message data block (MDB), which is returned by MCSOPMSG. Refer to z/OS MVS Data Areas in the z/OS Internet library for the format and content of this information.
IBM suggests that you code a loop around the MCSOPMSG invocation, so that the MCSOPMSG macro can retrieve messages that are currently queued to this EMCS console. Exit the loop when there are no more messages (MCSOPMSG RC=8,RSN=0).

Restrictions

None.

Input register information

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.

Output register information

When control returns to the caller, the GPRs contain:

Register: Contents
0: If GPR 15 contains a return code of 08, 10, or 14, GPR 0 contains a reason code; otherwise, GPR 0 contains zero.
1: Address of the MDB if REQUEST=GETMSG was specified and the return code is zero or four. Otherwise, GPR 1 is used as a work register by the system.
2-14: Unchanged
15: Return code

When control returns to the caller, the access registers (ARs) contain:

Register: Contents
0: Used as a work register by the system
1: If your program is in AR mode and GPR 1 contains the address of an MDB, AR 1 contains the ALET for the MDB; otherwise, AR 1 is used as work register by the system
2-14: Unchanged
15: Used as a work register by the system

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.

Performance implications

None.

Syntax

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).

Table 1. Parameters valid with REQUEST=services
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

Parameters

The parameters are explained as follows:

REQUEST=GETMSG
REQUEST=RESUME: Specifies the MCSOPMSG function you want to perform.
GETMSG retrieves a queued message from storage, and RESUME resumes message queuing.
,CMDRESP=NO
,CMDRESP=YES: Specifies the type of message search. NO indicates that MCSOPMSG will obtain the next message. YES indicates that MCSOPMSG will return the next command response message. CMDRESP is valid only with REQUEST=GETMSG, and is meaningful only if you specified MSGDLVRY=SEARCH on the MCSOPER macro.
,CART=cart addr: Specifies the address of an 8-character field that contains the name of the CART (command and response token) to use to search for the next message. A CART associates a command with a response. You can specify CART only if you specify CMDRESP=YES and you specified MSGDLVRY=SEARCH on MCSOPER.
,MASK=mask addr: Specifies the address of an 8-character field that contains the mask that MCSOPMSG will compare with the CART using the logical AND instruction. Specify MASK only if you specified CART.
,CONSID=console id addr: Specifies the address of the 4-byte console ID. CONSID or NAME is required, but both may not be specified.CONSID is mutually exclusive with NAME.
,NAME: Specifies the address of the 8-byte field containing the console name. NAME or CONSID is required, but both may not be specified. NAME is mutually exclusive with CONSID.
,RTNCODE=return code addr: Specifies the location where the system is to store the return code. The return code is also in GPR 15.
,RSNCODE=reason code addr: Specifies the location where the system is to store the reason code. The reason code is also in GPR 0.

ABEND codes

None.

Return and reason codes

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.

Table 2. Return and Reason Codes for the MCSOPMSG Macro
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.

Example

Obtain a message for a console. Request message queuing to resume using a parameter list named DATA. The parameter list was created using the list form of the macro.

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