MGCRE - Execute form

Use the execute form of the MGCRE macro together with the list form of the macro. The execute form of the macro stores the parameters into the storage area defined by the list form.

Parent topic: MGCRE — Issue internal commands

Syntax

The execute form of the MGCRE macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢  
  One or more blanks must precede MGCRE.
   
MGCRE  
   
␢ One or more blanks must follow MGCRE.
   
TEXT=text addr text addr: RX-type address or address in register (2) - (12).
   
,CONSID=console id console id: RX-type address or register (2) - (12).
,CONSNAME=console name console name: RX-type address or address in register (2) - (12).
   
   ,CMDFLAG=NOHCPY  
   
   ,CMDFLAG=TSO (NOT a programming interface)
   
   ,TOKEN=token token: RX-type address or register (2) - (12).
   
   ,UTOKEN=utoken addr utoken addr: RX-type address or address in register (2) - (12).
   
   ,CART=cart cart: RX-type address or address in register (2) - (12).
   
   ,ENVRIN=envrin addr envrin addr: RX-type address or address in register (2) - (12).
   
   ,AUTHCMDX=authcmdx addr authcmdx addr: RX-type address or address in register (2) - (12).
   
   ,PLISTVER=plistver plistver: 1 - 3.
   
,MF=(E, list addr) list addr: RX-type address or register (2) - (12).
   

Parameters

The parameters are explained as follows:

TEXT=text addr
Specifies the required input field that contains the address of a command area. If a register is used, it should contain the address of the command area. The first 2 bytes of this command area contain the length of the command. The command text immediately follows this 2-byte area, and can be up to 126 characters. The command must be in storage addressable by the caller at the time the caller issues MGCRE.
Operator commands may contain the following characters:
  • A to Z
  • 0 to 9
  • ' # $ & ( ) * + , - . / ¢ < | ! ; ¬ % _ > ? : @ " =

The system translates characters that are not valid into null characters (X'00').

To code: Specify the RX-type address of a pointer field that contains the address, or the register (2) - (12), of a particular field.

,CONSID=console id
,CONSNAME=console name
CONSID specifies the required input field that contains the 4-byte ID of the console that issued the command specified in the TEXT parameter. If a register is used, it should contain the 4-byte console ID. If you specify CONSID, do not specify CONSNAME.

CONSNAME specifies the required input field that contains the console name. The console name is a 2- to 8-byte character string. If a register is used, it should contain the address of an 8-byte field containing the console name. This name identifies the console that issued the command specified in the TEXT parameter. The console name is left-justified and padded with blanks. If you specify CONSNAME, do not specify CONSID.

You must specify either CONSID or CONSNAME. Use the DISPLAY CONSOLES command to obtain these values.

Note: When you specify a console ID of X'00000000' on the CONSID parameter, the issuer receives MASTER command authority. Entries in the hardcopy log for the command have the name INTERNAL associated with them.
,CMDFLAG=NOHCPY
Requests that no copy of the command appear in the hardcopy log.
Note: If you do not specify this option, the system logs the command in the hardcopy log.
,CMDFLAG=TSO
NOT a programming interface. Causes the CONSID value to be treated as a TSO identifier instead of a console ID.
Note: This option allows TSO to use MGCRE instead of MGCR.
,TOKEN=token
Specifies the optional input field that contains a 31-bit right-justified program token for the command specified in the TEXT parameter. If a register is used, it should contain a 31-bit right justified token. Any 4-byte value is valid as input. TOKEN is optional.
,UTOKEN=utoken addr
Specifies the optional input field that contains the address of a security token for the command identified in the TEXT parameter. If a register is used, it should contain the address of a data area for the UTOKEN. You can obtain the UTOKEN value by using the RACROUTE REQUEST=TOKENXTR, RACROUTE REQUEST=VERIFYX, or RACROUTE REQUEST=TOKENBLD macros. See z/OS Security Server RACROUTE Macro Reference for more information on the RACROUTE macros. Command processing passes the UTOKEN to SAF (Security Authorization Facility) to validate the authority of the issuer. The UTOKEN should be that of the user on whose behalf the command is issued. UTOKEN is an optional parameter; if it is omitted, the address space's UTOKEN is used.
,CART=cart
Specifies the optional input field that contains the address of the 8-byte field that contains a command and response token. If a register is used, it should contain the address of a data area containing the command and response token. Your installation can use any value as a CART. The program that issues the command can tag each command with this token, which associates the command with its response. CART is an optional parameter.
,ENVRIN=envrin addr
Specifies the optional field that contains the address of the ENVR data structure for the command identified in the TEXT parameter. The ENVR object should be one that was obtained on the same system where the MGCRE macro is issued or unpredictable results may occur. If ENVRIN is specified, then UTOKEN must also be specified.
,AUTHCMDX=authcmdx addr
Specifies the optional input field that contains the address of a data structure depicting the issuer's authority. The data is formatted like the CMDXAUTH 16 bit structure.

1000000000000000 - Master Authority
0100000000000000 - Sys Authority
0010000000000000 - IO Authority
0001000000000000 - Cons Authority
0000000000000000 - Info Authority

,PLISTVER=plistver
Specifies the version of the macro. PLISTVER determines which parameter list that the system generates. PLISTVER is an optional input parameter on all forms of the macro, including the list form. When using PLISTVER, specify it on all macro forms used for a request and with the same value on all of the macro forms. The values are:
1 - 2
Use PLISTVER=1 or PLISTVER=2 if you use the base set of parameters. If you omit PLISTVER, the value of 1 is used.
3
Use PLISTVER=3 if you use ENVRIN.
,MF=(E,list addr)
Specifies the execute form of MGCRE. This form generates the code to store the parameters into the parameter list and execute the MGCRE macro.

list addr specifies the area that the system uses to store the parameters.

ABEND codes

MGCRE might abnormally terminate with abend code X'D22'. See z/OS MVS System Codes for an explanation and programmer response for this code.

Return and reason codes

Register 15 contains one of the following hexadecimal return codes as the result of a START, MOUNT, or LOGON command. No return codes result from any other commands.

Table 1. MGCRE Return Codes
Return Code Meaning and Action
00 Meaning: The START command processed successfully. Register 0 contains the right-justified ASID of the started address space.

Action: None.
04 Meaning: A START, MOUNT, or LOGON command was suppressed by the SSI or an MVS commands installation exit. Register 0 does ot contain a valid ASID; instead it contains all zeros.

Action: None.
08 Meaning: Environmental error. The START command failed for one of the following reasons:
  • The START command specified a console that is not authorized for entering the command
  • The system did not allow the address space to be created at this time due to a heavy system workload
  • There is not enough storage available to schedule the command
  • The system tried to obtain more address spaces than the maximum number supported.

Action: Check to see if the START command specified a console that is not authorized for entering the command, and correct the situation if necessary. Next, retry the request. If the problem persists, record the return code and supply it to the appropriate IBM support personnel.

Example

Create the list form of MGCRE, modify it using the execute form of MGCRE, and issue a display consoles command associated with a console named CON4. 
DOMTST   CSECT
R2       EQU   2
         USING *,R12
         LA    R2,CMD                   R2 POINTS TO THE COMMAND AREA
         MGCRE MF=(E,LAREA),TEXT=(R2),CMDFLAG=(NOHCPY),CONSNAME=MYCON
CMD      DS    0CL6                     THE COMMAND AREA
CMDLEN   DC    XL2'4'                   LENGTH OF COMMAND
CMDCOMM  DC    CL4'D C '                THE ACTUAL COMMAND
MYCON    DC    CL8'CON4    '            NAME OF ISSUING CONSOLE
LAREA    MGCRE MF=L                     LIST FORM OF MGCRE
         END