MGCR — Issue an internal START or REPLY command

Description

Note: IBM recommends that you use the MGCRE macro rather than MGCR.

The MGCR macro starts a program or subsystem from within your program and passes 31 bits of information, in the form of a token, to the started program. The MGCR macro can also issue a reply to a WTOR macro. In other words, use MGCR to issue an internal START or REPLY command.

Environment

The requirements for the caller are:

Environmental factor Requirement
Minimum authorization: Supervisor state and PSW key 0-7
Dispatchable unit mode: Task
Cross memory mode: PASN=HASN=SASN
AMODE: 24- or 31-bit
ASC mode: Primary
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 command buffer can be located in 24-bit or 31-bit addressable storage.
  • A program token is meaningful only with the START command.

Restrictions

You can use MGCR to issue only START or REPLY commands. You must use MGCRE for any other commands.

Input register information

Before calling the MGCR macro, the caller must ensure that the following general purpose registers (GPRs) contain the specified information:
Register
Contents
0
Zero
1
A pointer to a parameter list mapped by IEZMGCR.

Output register information

When control returns to the caller, the GPRs contain:
Register
Contents
0
Unchanged
1
Used as a work register by the system
2-14
Unchanged
15
For the START command, GPR 15 contains a return code; otherwise, GPR 15 is 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 MGCR macro is written as follows:

Syntax Description
   
   name name: Symbol. Begin name in column 1.
   
␢ One or more blanks must precede MGCR.
   
MGCR  
   
␢ One or more blanks must follow MGCR.
   
command-buffer-address command-buffer-address: RX-type address or register (1) or (2) - (12).
   

Parameters

The parameters are explained as follows:

command-buffer-address
Specifies the address of a command buffer mapped by the IEZMGCR macro. The command buffer must contain the following information:
Name Length Contents
flags1 1 byte If bit 0 is one, then flags2 must contain meaningful information. Bits 1-7 must be zero.
length 1 byte Length of the buffer up to but not including the program token field.
flags2 2 bytes

X‘0000’ - neither a program token nor a user
security token are present.
X‘0800’ - a program token is present.
X‘0008’ - a user security token is present.
X‘0808’ - both a program token and a user
security token are present.
text up to 126 bytes Command, operands, and optional comments as follows: command operands comments
ptoken 31 bits right-justified An optional field containing any desired information, such as an identifier that indicates the issuing program.
utoken 80 bytes Indicates which user security token the system takes to use for a command issued from an MCS console. The possibilities are console, CTAS, *FAIL, or “undefined-user” ACEE.

ABEND codes

MGCR 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 command. No return codes result from the REPLY command.

Table 1. Return Codes for the START Command
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 command was suppressed by the SSI or a command exit. Register zero does not 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

Issue an internal REPLY command in response to an action message. Security tokens are not in use. 
ISSUMGCR EQU   *
         XC    MGCRPL(MGCRLTH),MGCRPL   Clear the parameter list
         MVC   MGCRTEXT(L'TXTINSRT),TXTINSRT   Move in the reply buffer
         MVC   REPLY,CTXTRPID           Insert the reply ID
         LA    REG1,(MGCRTEXT-MGCRPL)+L'TXTINSRT   Get MGCRPL length
         STC   REG1,MGCRLGTH            Save length in the MGCRPL
         SR    REG0,REG0                Clear register zero
         MGCR  MGCRPL                   Issue the command
         .
         .
         .
         IEZMGCR  DSECT=NO              Mapping of MGCR parameter list
         ORG   MGCRTEXT
COMMAND  DS    CL6                      Storage for REPLY verb
REPLY    DS    CL2                      Reply ID
REPLYMSG DS    CL3                      WTOR response
         ORG