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

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