Issuing an internal START or REPLY command (MGCR)

To issue an internal START or REPLY command, a program can issue the MGCR macro. The program issuing MGCR can pass a user security token to the system. The system uses the user security token for command authorization checking. In the case of the START command, the program that issues MGCR can pass 31 bits of information (in a field called a program token) to the program being started. An internal REPLY command is available to reply to a WTOR message.

You can also issue an internal START or REPLY command by using the MGCRE macro. MGCRE allows you to issue any operator command from an MCS or extended MCS console. MGCRE is the preferred programming interface. See Issuing operator commands from a program (MGCRE macro) for more information on using the MGCRE macro.

Before issuing the MGCR macro, set general register 0 to zero, and initialize a buffer as follows:

ieaa8iis

flags1
If bit 0 of the flags1 byte is one, the flags2 field must contain meaningful information. Bits 1-7 of flags1 must be zero.
length
The length field contains the length of the buffer in bytes, up to but not including the program token field.
flags2
Use this field to indicate whether a program token, a user security token, or both are present:
  • X'0000' - neither a program token nor a user security token is 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.
Note: Bit 0 of flags2 must be zero.
text
The text field contains the START or REPLY command followed by operands and, optionally, comments. The field may be up to 126 bytes long.
program token
This field contains information that you want to pass to the started program. You can pass any information depending upon the design of your program. For example, you might pass a parameter or a pointer to a parameter list. Program token is meaningful only for the START command.
user security token
Use this field to specify the user security token the system is to use for command authorization checking. To obtain the user security token, use the REQUEST=TOKENXTR form of the RACROUTE macro. For a description of the RACROUTE macro, see z/OS Security Server RACF Macros and Interfaces.
Figure 1 shows an example of how to setup the buffer. For a description of the MGCRPL data area (mapped by IEZMGCR), see z/OS MVS Data Areas in the z/OS Internet library.
Figure 1. Setting Up the Buffer for MGCR
           SR   REG0,REG0        INDICATE SYSTEM ISSUED
  *                                COMMAND
MGCRMAC    MGCR MGRCDATA
           .
           .
MGCRDATA   EQU  *
FLG1       DC   X'80'
LGTH       DC   AL1(PTOKEN-MGCRDATA)
FLG2       DC   X'0808'
TXT        DC   C'S IMS ***ANY COMMENTS***'
PTOKEN     DC   AL4(ECB)         ECB ADDR
UTOKEN     DC   CL80 '***YOUR SECURITY TOKEN***'
Parent topic: Communication