Example of managing an extended MCS console session

The following example shows an overview of how an application might use MVS™ services to set up and use an extended MCS console. Additional processing that a typical application might do, such as process a command response, is not shown but is represented by three stacked dots within the example. The example shows an application that:

Activates an extended MCS console
Issues a command from the console
Waits until the system queues a message, the command response, to the console
Receives the message from the console
Deactivates the console.

Figure 1. Managing an Extended MCS Console Session Overview

*****************************************
* 1 - Activate an extended MCS console  *
*****************************************

               MCSOPER   REQUEST=ACTIVATE
                         NAME=CONS1              CONSOLE NAME
                         CONSID=(2)              CONSOLE ID
                         TERMNAME=(4)            TERMINAL NAME
                         MCSCSA=(3)              CONSOLE STATUS AREA
                         MCSCSAA=(3)             ALET FOR CONSOLE STATUS AREA
                         MSGECB=MESSAGE_ECB      MESSAGE ECB
⋮

****************************************
* 2 - Issue a command from the console *
****************************************

               XC        TEXTAREA,TEXTAREA       CLEAR THE COMMAND AREA
               L         R1,L'CMD                OBTAIN THE LENGTH OF THE COMMAND
               STH       R1,TEXTLEN              SAVE THE LENGTH IN THE COMMAND AREA
               MVC       TEXTCMD(L'CMD),CMD      PUT THE COMMAND IN THE COMMAND AREA
               MGCRE     TEXT=TEXTAREA           TEXTAREA CONTAINS THE COMMAND
                         CONSID=(2)              CONSOLE ID
                         CART=USER_DEF_CART      COMMAND/RESPONSE TOKEN
                         MF=(E,LISTADDR)         ADDRESS OF PARAMETER LIST
⋮

               DS        0F                      
TEXTAREA       DS        0CL128                  COMMAND AREA
TEXTLEN        DS        H                       LENGTH OF COMMAND
TEXTCMD        DS        CL126                   THE COMMAND
CMD            DC        C'DISPLAY EMCS EXAMPLE COMMAND'
⋮

*********************************************************
* 3 - Wait for the system to queue the command response *
*     to the console                                    *
*********************************************************
               WAIT      ECB=MESSAGE_ECB         WAIT FOR COMMAND RESPONSE
⋮
************************************************************
* 4 - Retrieve the command response so it can be processed *
************************************************************
               MCSOPMSG  REQUEST=GETMSG
                         CONSID=(2)              CONSOLE ID

⋮

*******************************************
* 5 - Deactivate the extended MCS console *
*******************************************
               MCSOPER   REQUEST=DEACTIVATE
                         CONSID=(2)              CONSOLE ID

⋮
MESSAGE_ECB    DS    F
USER_DEF_CART  DS    CL8
⋮

The following description provides additional detail about the example. The numbers in each of the following steps correspond to the numbers in the comment blocks above.

MCSOPER activates the extended MCS console named CONS1. The system returns the following values to the application:
- In register 2, the address of the 4-byte console identifier
- In register 3, the address of the console status area
- In AR3, the ALET for the address space or data space that contains the console status area.
The MSGECB parameter identifies the ECB that the system is to post when there is a message queued for the extended MCS console.
MGCRE issues a command from the extended MCS console. The CART parameter identifies a user-defined token that the command processor is to return with any response related to the command being issued.
In this example, the application cannot continue processing until it receives a command response. Therefore, the application waits on the ECB. After the system issues the command response the ECB gets posted and the application can continue processing.
MCSOPMSG retrieves the message that is queued to the extended MCS console and places it into a message data block (MDB). In this case, the message is the command response. The MDB also contains the command response token the application provided on the CART parameter of the MGCRE macro. The system returns the address of the MDB in register 1 and the ALET for the address space or data space where the MDB is located in AR1. For more information on the MDB, see What is the message data block (MDB). When an application has issued multiple commands and expects command responses, the command response token enables the application to associate each response with the corresponding command.
The application issues MCSOPER REQUEST=DEACTIVATE to deactivate the extended MCS console.

SYS1.SAMPLIB contains an additional example of an extended MCS console application. The example is in IEAEXMCS.