Description

MCSOPER enables you to activate and manage extended MCS consoles. An extended MCS console is a program that acts as a console. It can issue MVS™ commands, and receive command responses and unsolicited message traffic. MCSOPER defines and activates an extended MCS console to the system and provides a means of storing operator messages and command responses. MCSOPER also deactivates the extended console or console class and allows the extended console to receive the hardcopy message set.

You can remove extended MCS consoles from your configuration using the IEARELEC sample program that is shipped in the V1R7 samplib. See z/OS MVS Planning: Operations for a description of how to use this program.

Use the MCSOPMSG macro to retrieve messages delivered to the EMCS console that has been activated using the MCSOPER macro. For more information on MCSOPER and MCSOPMSG, see z/OS MVS Programming: Authorized Assembler Services Guide.

Parent topic: MCSOPER - Manage extended MCS operations

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: Primary or 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

None.

Restrictions

If MSGDLVRY=NONE is specified on the MCSOPER ACTIVATE request, the OPERPARM console attribute for DOM will be forced to DOM=NONE. See z/OS MVS Programming: Authorized Assembler Services Guide for a description of console attributes.

Input register information

Before issuing the MCSOPER macro, the caller must ensure that the following general purpose register (GPR) contains the specified information:
Register
Contents
13
The address of an 18-word save area

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
If GPR 15 contains a hexadecimal return code of 00, 10, or 14, GPR 0 contains a reason code; otherwise, GPR 0 contains zero.
1
Used as a work register by the system
2-13
Unchanged
14
Used as a work register by the system
15
Return code
When control returns to the caller, the access registers (ARs) contain:
Register
Contents
0-1
Used as work registers 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

  • MSGDLVRY=FIFO delivers better performance than MSGDLVRY=SEARCH. Use MSGDLVRY=SEARCH when you are looking only for certain types of messages such as command responses.
  • If you request that an extended console receive the hardcopy message set from all the systems in a sysplex by specifying the MSCOPE=*ALL console attribute with the HARDCOPY OPERPARM option, you might experience performance problems.

Syntax

The standard form of the MCSOPER macro is written as follows:

Syntax Description
   
 name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede MCSOPER.
   
MCSOPER  
   
␢ One or more blanks must follow MCSOPER.
   
REQUEST=ACTIVATE See Table 1 for parameters available with REQUEST= services.
REQUEST=DEACTIVATE  
   
 ,NAME=opername addr opername addr: RX-type address or register (2) - (12).
   
 ,CONSID=console id addr console id addr: RX-type address or register (2) - (12).
   
 ,ABTERM=NO Default: ABTERM=NO
 ,ABTERM=YES  
   
 ,TERMNAME=terminal name addr terminal name addr: RX-type address or register (2) - (12).
   
 ,OPERPARM=parm area addr parm area addr: RX-type address or register (2) - (12).
   
 ,MCSCSA=csa addr csa addr: RX-type address or register (2) - (12).
   
 ,MCSCSAA=alet addr alet addr: RX-type address or register (2) - (12).
   
   ,MSGDLVRY=FIFO See Table 2 for parameters valid with MSGDLVRY services.
   ,MSGDLVRY=SEARCH  
   ,MSGDLVRY=NONE  
   
,MSGECB=ecb addr ecb addr: RX-type address or register (2) - (12).
   
   ,QLIMIT=qlimit addr qlimit addr: RX-type address or register (2) - (12).
  Default: QLIMIT=2147483647
   
   ,ALERTECB=alert addr alert addr: Rx-type address or register (2) - (12).
   ,ALERTECB=0 Default: ALERTECB=0
   
   ,ALERTPCT=percent addr percent addr: Rx-type address or register (2) - (12).
   ,ALERTPCT=percent num percent num: number from 0 to 100. Default: ALERTPCT=100
   
   ,QRESUME=qresume addr qresume addr: RX-type address or register (2) - (12).
   ,QRESUME=qresume num qresume num: number from 0 to 99. Default: QRESUME=0
   
   ,RTNCODE=ret code ret code: RX-type address or register (2) - (12).
   
   ,RSNCODE=reason code reason code: Rx-type address or register (2) - (12).
   

The following table lists the parameters available with REQUEST=ACTIVATE and REQUEST=DEACTIVATE. REQUEST=RELEASE can be used only to release a migration ID. Migration IDs are not supported at release V1R7; therefore, the REQUEST=RELEASE service is ignored.

Table 1. Parameters available with REQUEST= services
Parameters REQUEST= ACTIVATE REQUEST= DEACTIVATE
NAME required Either NAME or CONSID (not both)
CONSID required Either NAME or CONSID (not both)
ABTERM not valid optional
TERMNAME required not valid
OPERPARM optional not valid
MCSCSA required not valid
MCSCSAA required not valid
MSGDLVRY optional not valid
RTNCODE optional optional
RSNCODE optional optional
Table 2. Parameters available with MSGDLVRY= services
Parameters MSGDLVRY= FIFO MSGDLVRY= SEARCH MSGDLVRY= NONE
MSGECB required required not valid
QLIMIT optional optional not valid
ALERTECB optional optional not valid
ALERTPCT optional optional not valid
QRESUME optional optional not valid

Parameters

The parameters are explained as follows:

REQUEST=ACTIVATE
REQUEST=DEACTIVATE
Specifies the MCSOPER function you want to perform. This is a required parameter. The functions are as follows:
  • ACTIVATE identifies an extended console to MCS. It initializes a specific session. The application activating the extended console must have READ access to the MVS.MCSOPER.consname resource. See z/OS MVS Planning: Operations for more details. MCSOPER processing will perform the check unless the authorized application has already verified the authority and turned on bit MCSOBYPY in the MCSOP data area (IEZVG111).
  • DEACTIVATE identifies the console as inactive and terminates the session.

You can specify only one of these functions each time you invoke MCSOPER.

,NAME=opername addr
Specifies the address of an 8-byte field that contains the name of the console to be activated or deactivated.. NAME is required when you specify REQUEST=ACTIVATE. Do not use a name that might match the name of a device number (for example, BAD). If the name of a console matches a device number, a VARY command might not work as expected. If you specify REQUEST=DEACTIVATE, then either NAME or CONSID must be specified, but not both.
,CONSID=console id addr
Specifies the address of the 4-byte console ID. If you specified REQUEST=ACTIVATE, CONSID is an output area that will receive the console ID. CONSID is required if you specify REQUEST=ACTIVATE. If you specified REQUEST=DEACTIVATE, then either CONSID or NAME must be specified, but not both.
,ABTERM=NO
,ABTERM=YES
Indicates an abnormal termination of an extended MCS console. If you request to deactivate a console ID by abnormally terminating the console, the system fails the extended MCS console.

If ABTERM is not specified, ABTERM=NO is the default.

,TERMNAME=terminal name addr
Specifies the terminal name, VTAM® LU name, or other identification of the source for the activate request. The name is logged when the activate occurs and has no other use.
,OPERPARM=parm area addr
Specifies the address of the MCSOP data area, mapped by IEZVG111. That area contains information on operator parameters such as routing codes, command authority, message format, message level, and whether the console will receive the hardcopy message set. OPERPARM is optional. The system looks for information on operator parameters first in the user profile of a security product, such as RACF®. If the system does not find operator parameters in the user profile, it uses the operator parameters passed in the MCSOP data area, mapped by IEZVG111. If you did not specify the OPERPARM parameter, the system takes the default values of the operator parameters, also defined in the MCSOP data area. You can override the console attributes specified in the user profile of the security product by turning on bit MCSOVRDY in the MCSOP data area.
Note: When the RACF OPERCMDS class is not active, the OPERPARM segment on the RACF user profile is ignored.
For more information about OPERPARM, see z/OS MVS Programming: Authorized Assembler Services Guide.
,MCSCSA=csa addr
Specifies the address of a 4-byte output area that will contain the address of the MCS console status area. When MCSOPER posts the ECB and if the return and reason codes indicate that queueing has been disabled, you need to check the MCS console status area, which is defined in the MCSCSA data area, mapped by IEAVG131, to determine which problem has disabled queuing. The MCSCSA parameter is required if you specified REQUEST=ACTIVATE.
,MCSCSAA=alet addr
Specifies the address of a 4-byte output area on a fullword boundary that will contain the ALET that identifies the address or data space that contains the MCS console status area. MCSCSAA is required if you specified REQUEST=ACTIVATE.
,MSGDLVRY=FIFO
,MSGDLVRY=SEARCH
,MSGDLVRY=NONE
Specifies how MCSOPER queues messages to extended MCS consoles. Specifying FIFO will cause MCSOPER to deliver messages on a first-in, first-out basis. This is the default option. Specifying SEARCH allows you to request messages based on search arguments specified in the MCSOPMSG macro. Specifying NONE will keep messages from being delivered to this console. In addition, if NONE is specified, the OPERPARM console attribute for DOM will be forced to DOM=NONE. See z/OS MVS Programming: Authorized Assembler Services Guide for a description of console attributes.
,MSGECB=ecb addr
Specifies the address of the ECB that the system posts when it queues a message to the console. Note that the system posts this ECB for every message it delivers to the message dataspace. However, since it is not possible to tell how many times an ECB has been posted since it was last waited on, once an ECB is posted, users should issue MCSOPMSG to retrieve messages until they receive a return and reason code indicating that no more messages remain to be retrieved. This keyword is optional and is not valid if you specified MSGDLVRY=NONE.
Note: For system performance reasons, IBM recommends that the message ECB be in common storage.
,QLIMIT=qlimit addr
Specifies either the maximum number or the address of the maximum number of messages which the system can queue to the console issuing the request. You can specify the maximum number as any number from 1 to 2147483647 (2 gigabytes). QLIMIT=2147483647 is the default.
,ALERTECB=alert addr
,ALERTECB=0
Specifies the address of the ECB that the system will post when one of the following is true:
  • The number of messages in storage has reached the number specified in QLIMIT.
  • The number of messages in storage matches the percentage of the QLIMIT number specified in ALERTPCT.
  • You ran out of space for messages in storage.
  • There is a queuing error.

If you specify ALERTECB=0, MCSOPER will not post an ECB.

,ALERTPCT=percent addr
,ALERTPCT=percent num
Specifies the address of the percentage of the maximum number of messages specified in QLIMIT or the number representing the percent. When the queue reaches this percentage, the MCSOPER posts the ALERTECB. If you do not specify percent addr, or percent num is outside the range of 1 through 99, MCSOPER will operate on the default, 100.
,QRESUME=qresume
,QRESUME=qresume num
Specifies the address that contains the depth percent at which the queue must be to resume queuing. If the system disabled queuing because the number of messages in the data space reached the percentage of the QLIMIT (ALERTPCT) and you retrieve enough messages to meet the percentage you specify in QRESUME, queuing will resume automatically for the console issuing the request. If you do not specify QRESUME, or QRESUME is outside the range of 0 through 99, queuing will only resume after explicit action by the application using the MCSOPMSG REQUEST=RESUME macro. The default is QRESUME=0.
,RTNCODE=ret code
Specifies the location where the system is to store the return code. The return code is also in general purpose register (GPR) 15.
,RSNCODE=reason code
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 MCSOPER, GPR 15 (and ret code, if you specified RTNCODE) contains one of the following hexadecimal return codes. GPR 0 (and reason code, if you specified RSNCODE) contains one of the following hexadecimal reason codes.

Table 3. Return and Reason Codes for the MCSOPER Macro
Return Code Reason Code Meaning and Action
00 00 Meaning: Processing was successful.

Action: None.
00 04 Meaning: An EMCS console was successfully activated; however, a migration ID was not obtained if one was requested. Migration IDs are not supported as of z/OS® V1R8.

Action: Remove the request for a migration ID.

04 None Meaning: Environmental error. For REQUEST=ACTIVATE, an EMCS console with this name is already active on this system or on a system within the same GRS NONE or RING environments. For REQUEST=DEACTIVATE, the console was already inactive.

Action: If you specified the wrong console, correct the error and retry the request.
08 None Meaning: Program or environmental error. For REQUEST=DEACTIVATE, the console has not been defined.

Action: If you specified the wrong console, correct the error and retry the request. If the console should have been active, find out why it was not, correct the problem, and rerun the program.
0C None Meaning: For an ACTIVATE request, the issuer does not have READ access to the OPERCMDS resource name MVS.MCSOPER.console_name, where console_name is the name of the console the user tried to activate.

Action: Correct the problem and rerun the program.
10 00 Meaning: System error. The input parameter list contains an error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
10 08 Meaning: Program error. The specified console name is not valid. The reason could be one of the following:
  • The syntax of the console name is incorrect.
  • You specified the console name of a system console.
  • You specified a restricted console name.

Action: Correct any errors and rerun the program.
10 0C Meaning: Program error. The specified console ID is not valid. The reason could be one of the following:
  • The syntax of the console ID is incorrect.
  • You specified the console ID of a system console.
  • You did not specify the console ID of an EMCS console.

Action: Correct any errors and rerun the program.
10 18 Meaning: Program error. The authority level specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 1C Meaning: Program error. The message format specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 20 Meaning: Program error. The message level specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 24 Meaning: Program error. The message type specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 28 Meaning: Program error. The log command response specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 2C Meaning: System error. This reason code is used for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
10 30 Meaning: Program error. The key specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 38 Meaning: Program error. The command association specified in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
10 3C Meaning: Program error. The message scope specified in the OPERPARM segment is not valid. One of the following errors exists:
  • The calling program specified ALL with some other value
  • A system name contains a syntax error
  • A duplicate system name exists in the list of systems
  • The specified number of systems is not valid.

Action: Correct the problem and rerun the program.
10 44 Meaning: You issued MCSOPER while in cross-memory mode. You cannot issue MCSOPER if your program is in cross-memory mode.

Action: Correct the problem and rerun the program.
10 48 Meaning: Program error. The maximum dataspace size value in the OPERPARM segment is not valid.

Action: Correct the problem and rerun the program.
14 00 Meaning: System error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 08 Meaning: System error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 0C Meaning: Program or environmental error. There was an SAF routine error.

Action: Check your OPERPARM statement for incorrect entries. If you do not find an error, record the return and reason code and supply them to the appropriate IBM support personnel.
14 10 Meaning: System error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 14 Meaning: System error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 18 Meaning: Program error. The console ID you specified is not defined to the sysplex at this time.

Action: Check to see that you specified the correct console ID. Determine whether the console is active by issuing a DISPLAY EMCS command from a console. Correct the problem and rerun the program.
14 1C Meaning: System error. This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 20 Meaning: System error. There was a data space initialization error. The system could not create a data space because it could not obtain a data space or ALET.

Action: This might be a performance or tuning problem. Contact your system programmer.
14 24 Meaning: This reason code is for IBM diagnostic purposes only.

Action: Record the return and reason code and supply them to the appropriate IBM support personnel.
14 28 Meaning: System error. Necessary storage could not be obtained for the console.

Action: Attempt to rerun the program. If the error persists, record the return and reason code and supply them to the appropriate IBM support personnel.
14 2C Meaning: System error. The task terminated because abends cannot be performed any more.

Action: Try to run the program again. If the error persists, keep a record of the return and reason code and contact the IBM Support Center for help.
18 None Meaning: Program error. The caller is not in supervisor state.

Action: Correct your program and resubmit it.
1C nnnnnnnn Meaning: For REQUEST=ACTIVATE, an ALESERV ADD request failed. nnnnnnnn is the failed ALESERV ADD return code.

Action: See the ALESERV ADD return code information and correct the problem.

Example 1

This example activates a console named TAPE1 with operator parameter information contained in an area called PARMAREA, and values for MCSCSA and return and reason codes. 
MDR      CSECT
         STM   14,12,12(13)
         BALR  12,0
         USING *,12
   MCSOPER REQUEST=ACTIVATE,NAME=TAPE1,CONSID=IDAREA,                  X
               MSGECB=ALERT_ECB,TERMNAME=TERMINAL,                     X
               OPERPARM=PARMAREA,                                      X
               MCSCSA=STATUS_AREA,MCSCSAA=MY_ALET,                     X
               RTNCODE=RETCODE,RSNCODE=REASON
         LM    14,12,12(13)
         BR    14
*
PARMAREA DS    CL40
IDAREA   DS    CL4
ASCBPTR  DS    A
CLASSNAME DS   CL8
TERMINAL  DC    CL8'CN3E0'
TAPE1    DC    CL8'TAPE1'
RETCODE  DS    F
REASON   DS    F
ALERT_ECB DS  A
          DS  0D
STATUS_AREA DS   CL4
MY_ALET   DS  F
         IEZVG111
         END   MDR

Example 2

This example deactivates a console named TAPE1 by failing the console. 
MDR      CSECT
         STM   14,12,12(13)
         BALR  12,0
         USING *,12
    MCSOPER REQUEST=DEACTIVATE,NAME=TAPE1,ABTERM=YES,                  X
               RTNCODE=RETCODE,RSNCODE=REASON
         LM    14,12,12(13)
         BR    14
*
TAPE1    DC    CL8'TAPE1'
IDAREA   DS    CL4
RETCODE  DS    F
REASON   DS    F
         END   MDR

Example 3

Activate an extended MCS console and specify that it is to receive the hardcopy message set. 
TESTHC   CSECT
TESTHC   AMODE 31
TESTHC   RMODE ANY
*
R0       EQU   0
R1       EQU   1
R2       EQU   2
R3       EQU   3
R4       EQU   4
R5       EQU   5
R6       EQU   6
R7       EQU   7
R8       EQU   8
R9       EQU   9
R10      EQU   10
R11      EQU   11
R12      EQU   12
R13      EQU   13
R14      EQU   14
R15      EQU   15
*
         STM   R14,R12,12(R13)
         BALR  R12,0
         USING *,R12
         MODID BRANCH=YES
*
         GETMAIN RU,LV=DATAEND        Obtain storage for data areas
         LR    R11,R1
         USING DATAAREA,R11
         ST    R13,SAVEAREA+4
         LA    R15,SAVEAREA
         ST    R15,8(R13)
         LR    R13,R15
*
         LA    R8,OPERDATA            Address of operparm area
         USING MCSOPPRM,R8            IEZVG111 addressability
         XC    MCSOPPRM(MCSOPLEN),MCSOPPRM  Clear the operparm area
*************************************************************************
* Override the console attributes specified in the user profile
* of the security product by turning on bit MCSOVRDY in the MCSOP data
* area. Request the hardcopy attribute (to receive hardcopy message set).
*************************************************************************
         OI    MCSOFLAG,MCSOVRDY      Override console attributes
         OI    MCSOMISC,MCSOHDCY      Request the hardcopy attribute
*
         MODESET MF=(E,SUP)           Change to supervisor state
*                                     to issue MCSOPER ACTIVATE request
*************************************************************************
* Activate an extended MCS console whose name is contained in a field
* called HCCONSNM.  The attributes of the extended MCS console are
* contained in a field called OPERDATA, mapped by IEZVG111.  The
* console will have its messages delivered on a first-in-first-out
* basis.  The system will post a message ECB called HCMECB.
* The address of the output area that contains the
* address of the MCS console status area is contained in a field
* called HCSTATUS.  The address of the ALET that identifies the address
* or data space that contains the MCS console status area is
* contained in a field called HCSTATAL.
* The system returns the console ID in the field called HCCONSID.
* The system returns a return code and a reason code in fields
* called HCRETC and HCRNC, respectively.
*************************************************************************
         MCSOPER REQUEST=ACTIVATE,  Activate the console               X
               NAME=HCCONSNM,                                          X
               TERMNAME=HCCONSNM,                                      X
               OPERPARM=OPERDATA,                                      X
               MSGDLVRY=FIFO,                                          X
               MSGECB=HCMECB,                                          X
               MCSCSA=HCSTATUS,                                        X
               MCSCSAA=HCSTATAL,                                       X
               CONSID=HCCONSID,                                        X
               RTNCODE=HCRETC,                                         X
               RSNCODE=HCRSNC,                                         X
               MF=(E,MCSOPPL)
*
         MODESET MF=(E,PROB)       Return to problem state
*
         L     R13,4(R13)
         FREEMAIN RU,LV=DATAEND,A=(R11),SP=230
         LM    R14,R12,12(R13)
         BR    R14
*
HCCONSNM DC    CL8'HCMCSOP '
SUP      MODESET MODE=SUP,MF=L     Parmlist for supervisor state
PROB     MODESET MODE=PROB,MF=L    Parmlist for problem state
*
DATAAREA DSECT
         DS    0F
SAVEAREA DS    18F
         DS    0F
OPERDATA DS    CL(MCSOPLEN)
HCCONSID DS    CL4
HCSTATUS DS    A
HCSTATAL DS    F
HCMECB   DS    F
HCRETC   DS    F
HCRSNC   DS    F
         MCSOPER MF=(L,MCSOPPL)
DATAEND  EQU   *-DATAAREA
         IEZVG111
         END   TESTHC