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:
- 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***'