CMDAUTH - Execute form

CMDAUTH - Execute form

z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN
SA23-1372-00

The execute form of the CMDAUTH macro can refer to and modify the parameter list constructed by the list form of the macro.

Syntax

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

Syntax	Description

`name`	`name`: Symbol. Begin `name` in column 1.

␢	One or more blanks must precede CMDAUTH.

CMDAUTH

␢	One or more blanks must follow CMDAUTH.

ENTITY = `entity name addr`	`entity name addr`: RX-type address or register (2) - (12).

,ATTR = `access level addr`	`access level addr`: RX-type address or register (2) - (12).

,LOGSTR=`log string addr`	`log string addr`: RX-type address or register (2) - (12).
	Note: See usage note (following) for usage information.

,UTOKEN=`utoken addr`	`utoken addr`: RX-type address or register (2) - (12).
	Note: See usage note (following) for usage information.

,CNTLBLK=`cntl blk addr`	`cntl blk addr`: RX-type address or register (2) - (12).
	Note: See usage note (following) for usage information.

,CBLKTYPE=CIB	Note: See usage note (following) for usage information.
,CBLKTYPE=CMDX	(For use of CMDAUTH in command installation exit)
,CBLKTYPE=SSCM

,REQSTOR = `reqstor addr`	`reqstor addr`: RX-type address or register (2) - (12).

,SUBSYS = `subsys addr`	`subsys addr`: RX-type address or register (2) - (12).

,MSGSUPP=YES	Default: NO
,MSGSUPP=NO

,MSGRTN=YES	Default: NO
,MSGRTN=NO

,MSGSP=`subpool number`	Default: 229.

,MF=(E, `cntl addr`)	`cntl addr`: RX-type address or register (2) - (12).

Usage Note: You must specify one of the following parameter combinations:

UTOKEN and LOGSTR
CNTLBLK and CBLKTYPE

You cannot specify both of the preceding combinations. Also note that:

UTOKEN is not valid with CNTLBLK and CBLKTYPE
LOGSTR is optional with CNTLBLK and CBLKTYPE
CNTLBLK is not valid with UTOKEN and LOGSTR
CBLKTYPE is not valid with UTOKEN and LOGSTR

You can use CNTLBLK and CBLKTYPE to obtain authorization information without having to specify the UTOKEN and LOGSTR for the command. See the description of the CBLKTYPE parameter for further information.

Parameters

The parameters are explained as follows:

ENTITY=entity name addr

Specifies the address of a required 39-byte input field containing the resource name for the command whose authority you are checking. If the entity name is less than 39 bytes, left-justify it and pad it on the right with blanks.

ENTITY corresponds to the RACROUTE REQUEST=AUTH parameter, ENTITY.

,ATTR=access level addr

Specifies the SAF access level for the command whose authority you are checking. The bits set in the 1-byte field indicate the access level. The following settings apply:

02 - READ
04 - UPDATE
08 - CONTROL.

ATTR corresponds to the RACROUTE REQUEST=AUTH parameter, ATTR.

LOGSTR=log string addr

Specifies the address of a required input field containing the command text of the command whose authority you are checking. The first byte of the input field must contain the length of the command text.

LOGSTR corresponds to the RACROUTE REQUEST=AUTH parameter, LOGSTR.

UTOKEN=utoken addr

Specifies the address of the UTOKEN that RACROUTE will use for command authorization.

UTOKEN corresponds to the RACROUTE REQUEST=AUTH parameter, UTOKEN.

CNTLBLK=cntl blk addr

Specifies the address of the control block the system passes as input to CMDAUTH.

CBLKTYPE=CIB

CBLKTYPE=SSCM

Specifies the type of control block whose address you specify on the CNTLBLK parameter.

You can use the CIB as input when you need authorization information for START, STOP, or MODIFY commands.

Use the SSCM as the control block input for any subsystems that use the CMDAUTH macro during SSI command exit (function code 10) processing.

,REQSTOR=reqstor addr

Specifies the address of an 8-byte character field containing the control point name. (This address identifies a unique control point within a set of control points that exists in a subsystem.) If the control point name is less than eight bytes, left-justify it and pad it on the right with blanks.

If you code this operand and RACF® is installed, change the RACF router table to match the operand.

,SUBSYS=subsys addr

Specifies the address of an 8-byte character field containing the calling subsystem's name, version, and release level. If the subsystem's name is less than eight bytes, left-justify it and pad it on the right with blanks.

If you code this operand and RACF is installed, change the RACF router table to match the operand.

,MSGSUPP=YES

,MSGSUPP=NO

Indicates whether you want to suppress write-to-operator (WTO) messages from SAF and RACF. The default is NO.

,MSGRTN=YES

,MSGRTN=NO

Indicates whether you want CMDAUTH to return error messages to the caller. If you specify YES, CMDAUTH returns the address of the messages to register 1. The default is NO.

Note: The caller must release the storage obtained when MSGRTN = YES. The address of the message in register 1 points to the following structure. For example:

 ST        R1,MSGPT        SAVE THE ADDRESS OF MESSAGE POINTER
 USING     MSGMAP,R1       OBTAIN ADDRESSABILITY TO THE MESSAGE
 ...

           TITLE 'MESSAGE MAP'
 MSGMAP    DSECT
           DS    0CL13
 MSGHEADR  DS    0CL12     MESSAGE HEADER
 MSGLEN    DS    F         LENGTH OF MESSAGE
 MSGNEXTP  DS    A         ADDRESS OF NEXT MESSAGE
 MSGWPL    DS    A         START OF MESSAGE WPL
 MSGTXT    DS    0CL1      START OF MESSAGE TEXT

,MSGSP=subpool number

Specifies the number of the subpool into which you want error messages returned. The default is 229.

,MF=(E,cntl addr)

Specifies the execute form of CMDAUTH. This form generates the code to store the parameters into the parameter list and execute the CMDAUTH macro. cntl addr defines the area into which the system stores the parameter list.

Return codes

When CMDAUTH macro returns control to your program, GPR 15 contains a return code.

Table 1. Return Codes for the CMDAUTH Macro
Hexadecimal Return Code	Meaning
00	Meaning: Command issuer is authorized to issue the command.
04	Meaning: No authorization decision was made.
08	Meaning: Command issuer is not authorized to issue the command.

Example

Verify the authorization of a command. Register 4 points to the data set name and register 3 points to the access level setting.

DO_CMDAUTH    CMDAUTH ENTITY=(R4),ATTR=(R3),SUBSYS=SUB_NAME,
                      REQSTOR=REQ_NAME,UTOKEN=UTOKEN_ADDR,
                      LOGSTR=LOG_STR,MF=(E,CMDAUTH_LIST)