RACROUTE (standard form)

The standard form of the RACROUTE macro is written as follows:

   
   name name: Symbol. Begin name in column 1.
 
␣ One or more blanks must precede RACROUTE.
 
RACROUTE  
 
␣ One or more blanks must follow RACROUTE.
 
REQUEST=type type: System macro request type
 
,WORKA=work area addr work area addr: A-type address or register (2) – (12)
 
   ,DECOUPL=YES
   ,DECOUPL=NO Default: DECOUPL=NO
 
   ,MSGRTRN=YES  
   ,MSGRTRN=NO Default: MSGRTRN=NO
 
   ,MSGSP=subpool number subpool number: Decimal digit 0–255; default is 0.
 
   ,MSGSUPP=YES
   ,MSGSUPP=NO Default: MSGSUPP=NO
 
   ,RELATED=value value: Any valid macro keyword specified
 
   ,RELEASE=number number: 77B0, 77A0, 7790, 7780, 7770, 7760, 7750, 7740, 7730, 7720, 7709, 7708, 7707, 7706, 7705, 7703, 2608, 2.6, 2.4, 2.3, 2.2, 2.1, 1.9.2, 1.9, 1.8.1, 1.8, 1.7 or 1.6
Note:
  1. Default: RELEASE=1.6
  2. Because the format of the FMID has changed, the release ID number for release 2.8 is 2608 and the release 10 number is 7703.
 
   ,REQSTOR=reqstor addr reqstor addr: A-type address or register (2) – (12)
 
   ,SUBSYS=subsys addr subsys addr: A-type address or register (2) – (12)
 
MF=S

For RACROUTE to work correctly, once you have chosen a REQUEST, you must also specify the parameters that belong to that request. See the RACROUTE REQUEST= macros for the necessary parameters.

This request requires a standard 18-word save area that is pointed to by register 13.

Data areas returned to the caller by RACF® are either above or below 16 MB, depending upon the caller's addressing mode and the data area in question.

The parameters are explained as follows:
,REQUEST=AUDIT
,REQUEST=AUTH
,REQUEST=DEFINE
,REQUEST=DIRAUTH
,REQUEST=EXTRACT
,REQUEST=FASTAUTH
,REQUEST=LIST
,REQUEST=SIGNON
,REQUEST=STAT
,REQUEST=TOKENBLD
,REQUEST=TOKENMAP
,REQUEST=TOKENXTR
,REQUEST=VERIFY
,REQUEST=VERIFYX
specifies the system macro request type.

To invoke a system macro request supported through the RACROUTE interface, you must also code the parameters associated with that particular request type on the RACROUTE macro instruction. See the extended description for the system macro-request type you wish to use for specific information about the keywords available for that particular request.

,WORKA=work area addr
specifies the address of a 512-byte work area for use by the router and the RACF front-end routine. This parameter is required for execution of the RACROUTE macro. Where it is specified can vary. For example, on MF=S it must be specified on the MF=S invocation. For MF=E, it can be specified on the MF=E invocation, on an earlier MF=M invocation that points to the same parameter list, or on the MF=L invocation that built the parameter list.
,DECOUPL=YES
,DECOUPL=NO
specifies whether or not REQSTOR and SUBSYS are to be used for caller identification or to determine whether RACF function is to be performed or bypassed. (See the SUBSYS keyword.)

DECOUPL=YES indicates that REQSTOR and SUBSYS parameters are used only for caller identification. Specifying DECOUPL=YES also indicates that all checking against the RACF router table is bypassed. (Checking for class entries is bypassed also.) Request processing will be performed unconditionally.

DECOUPL=NO indicates that there is checking against the RACF router table. RACF looks for a matching REQSTOR and SUBSYS parameter combination in the RACF router table; if none is found, request processing is performed just as if ACTION=RACF is specified in the router table.

DECOUPL=NO is the default.

,MSGRTRN=YES
,MSGRTRN=NO
MSGRTRN=YES indicates that messages will be returned in a buffer.
MSGRTRN=NO (default) indicates that messages will be issued via TPUT.

It specifies whether you want to use message return processing. You can use this parameter in conjunction with the other RACROUTE MSGxxxx parameters to store and forward messages resulting from this service.

Note: This parameter applies to REQUEST=AUTH, REQUEST=DEFINE, REQUEST=VERIFY, and REQUEST=VERIFYX.
,MSGSP=subpool number
specifies the storage subpool into which you want RACF messages returned. You can use ,MSGSP in conjunction with the other RACROUTE MSGxxxx parameters to store and forward RACF messages. If you do not specify a subpool, the default subpool is 0. An unauthorized caller can only specify subpools 0 through 127.
Note:
  1. While IBM® recommends that you specify a storage subpool, rather than allowing it to default, you should take some care in selecting a subpool, as MVS™ makes certain assumptions about subpool usage and characteristics. In particular, using subpool 0 or 250, or any subpool documented in z/OS MVS Programming: Assembler Services Guide as having a storage key of USER (for example, 227–231 and 241) might give unpredictable results.
  2. If a common-area subpool (for example 226–228, 231, 239, 241, 245, 247, or 248) is used and not freed before the job terminates, then the job might show up in the exception reports of RMF™ (or other monitoring tools that support the tracking of common-area storage utilization) as owning common storage. Before your job terminates, it should issue a FREEMAIN to free this common storage.
  3. This parameter applies to REQUEST=AUTH, REQUEST=DEFINE, REQUEST=VERIFY, and REQUEST=VERIFYX.
  4. IRR008I through IRR018I, ICH408I, ICH70001I, ICH70002I, ICH70003I, ICH70004I, ICH70005I, ICH70006I, and ICH70007I messages can be returned for RACF.
  5. When control returns from RACROUTE, the RACROUTE parameter-list field is mapped by SAFPMSAD in the ICHSAFP mapping macro. SAFPMSAD is nonzero if messages have been returned. This field contains the address of an area that consists of two fullwords followed by the message itself in write-to-operator (WTO) parameter-list format. The first word is the length of the area including the two-fullword header; the second word points to the next message area, if there is one, or contains zero if no more messages areas exist.

    You must issue the FREEMAIN macro to release the message area.

,MSGSUPP=YES
,MSGSUPP=NO
specifies whether you want to suppress messages from within RACF processing. You can use this parameter in conjunction with the other RACROUTE MSGxxxx parameters to store and forward messages resulting from this service.
Note:
  1. This parameter applies to REQUEST=AUTH, REQUEST=DEFINE, REQUEST=VERIFY, REQUEST=VERIFYX, REQUEST=FASTAUTH, and, for RACF only, message ICH408I and associated auditing support informational messages (IRR series), as well as ICH70001I, ICH70002I, ICH70003I, ICH70006I, and ICH70007I.
  2. LOG=NONE suppresses both messages and SMF records regardless of MSGSUPP=NO.
,RELATED=value
specifies information used to make notes to yourself to document macro instructions by relating functions or services to corresponding functions or services. You can use any format and put in any length and type of data you want.
,RELEASE=number
specifies the release level of the parameter list to be generated by this macro. Through RACF 2.2, it corresponds to the FMID of the RACF release. After that, when RACF became solely an element of OS/390® or z/OS®, it corresponds to the FMID of the RACF. For example:
  • 2.2 corresponds to FMID HRF2220 (RACF 2.2, OS/390 Security Server V1R1 or OS/390 Security Server V1R2)
  • 2.3 corresponds to FMID HRF2230 (OS/390 Security Server V1R3)
  • 2.4 corresponds to FMID HRF2240 (OS/390 Security Server V2R4)
  • 2.6 corresponds to FMID HRF2260 (OS/390 Security Server V2R6)
  • 2608 corresponds to FMID HRF2608 (OS/390 Security Server V2R8)
  • 7703 corresponds to FMID HRF7703 (OS/390 SecureWay Security Server V2R10)
  • 7705 corresponds to FMID HRF7705 (z/OS SecureWay Security Server V1R2)
  • 7706 corresponds to FMID HRF7706 (z/OS Security Server V1R3)
  • 7707 corresponds to FMID HRF7707 (z/OS Security Server V1R4)
  • 7708 corresponds to FMID HRF7708 (z/OS Security Server V1R5)
  • 7709 corresponds to FMID HRF7709 (z/OS Security Server V1R6)
  • 7720 corresponds to FMID HRF7720 (z/OS Security Server V1R7)
  • 7730 corresponds to FMID HRF7730 (z/OS Security Server V1R8)
  • 7740 corresponds to FMID HRF7740 (z/OS Security Server V1R9)
  • 7750 corresponds to FMID HRF7750 (z/OS Security Server V1R10)
  • 7760 corresponds to FMID HRF7760 (z/OS Security Server V1R11)
  • 7770 corresponds to FMID HRF7770 (z/OS Security Server V1R12)
  • 7780 corresponds to FMID HRF7780 (z/OS Security Server V1R13)
  • 7790 corresponds to FMID HRF7790 (z/OS Security Server V2R1)
  • 77A0 corresponds to FMID HRF77A0 (z/OS Security Server V2R2)
  • 77B0 corresponds to FMID HRF77B0 (z/OS Security Server V2R3)

To use the parameters associated with a release, you must specify the number of that release or a later release. If you specify an earlier release level, the parameter is not accepted by macro processing, and an error message is issued at assembly time. If parameters have a release dependency, the parameter descriptions with each request type identify the release number required.

The default release is 1.6.

,REQSTOR=reqstor addr
specifies the address of an 8-byte character field containing the name of the piece of code that is making the request. (This address identifies a unique piece of code within a set of code that exists in a subsystem.) If this operand is omitted, a string of eight blanks is assumed.

If DECOUPL=NO is specified and you specify this operand when RACF is installed, RACF looks for a matching REQSTOR and SUBSYS parameter combination in the RACF router table; if none is found, request processing is performed just as if ACTION=RACF is specified in the router table.

For a description of the RACF router table and the macro used to update it, see ICHRFRTB Macro in z/OS Security Server RACF Macros and Interfaces.

,SUBSYS=subsys addr
specifies the address of an 8-byte character field containing the calling subsystem's name, version, and release level. If this operand is omitted, a string of eight blanks is assumed.

If DECOUPL=NO is specified and you specify this operand when RACF is installed, RACF looks for a matching REQSTOR and SUBSYS parameter combination in the RACF router table; if none is found, request processing is performed just as if ACTION=RACF is specified in the router table.

For a description of the RACF router table and the macro used to update it, see ICHRFRTB Macro in z/OS Security Server RACF Macros and Interfaces.

Return codes

These return codes represent return codes from all invocations of the RACROUTE macro; for example, REQUEST=AUTH, REQUEST=VERIFY. For specific information on the success or failure of the invocation in question, see the topic of this information that describes that invocation.

When you execute the macro, space for RACF return codes and their respective reason codes is reserved in the first two words of the RACROUTE parameter list. You can access them using the ICHSAFP mapping by loading the ICHSAFP pointer with the label that you specified on the list form of the macro. When control is returned, register 15 contains one of the following SAF return codes.

Notes:
  • All return and reason codes are shown in hexadecimal. However, applications that call these services may convert a hex value in a register to decimal for display. Also, SAF return codes are presented as SAF RCs in the following topic.
  • The following SAF RC information only applies with RACF return/reason code combinations other than X'270F'/X'270F'. A RACF return/reason code of X'270F'/X'270F' indicates the system could not obtain enough storage to satisfy the request. This return/reason code combination may be displayed as a decimal 9999/9999. This RACF return/reason code may be accompanied by either SAF return code 4 or SAF return code 8.
SAF RC
Meaning
00
The requested security function completed successfully. For example, if the requested function was ‘AUTH’, the authorization request was accepted.
04
The requested function has not been processed. For example, if the request was ‘AUTH’, RACF or the SAF router could neither accept nor fail the request. The following are some possible reasons for a request not to be processed.
  • The SAF router is not active.
  • The combination of class, REQSTOR, and SUBSYS was found in the RACF router table, and ACTION=NONE was specified.
  • The RACROUTE issuer specified DECOUPL=YES and a RELEASE= keyword with a higher release than is supported by this level of z/OS.
  • RACF is not active on the system, and RACFIND=YES was not specified, and there is no RACROUTE installation exit routine (or an exit originated a return code of 4).
  • RACF is active on the system, but no profile exists for the specified resource.
  • The class is not defined to RACF.
08
The requested function was processed by RACF, the SAF router, or the router exit (ICHRTX00) and failed. If the requested function was AUTH, the authorization request has failed. For example, if RACF is inactive for an ‘AUTH’ request with RACFIND=YES, the SAF router fails the request. The RACF- or router-exit return code and reason codes are returned in the first two words of the RACROUTE input parameter list.

Example 1

Invoke the SAF router to perform authorization checking, using the standard form, for a non-VSAM data set residing on the volume pointed to by register 8. Register 7 points to the data set name and the RACF user is requesting the highest level of control over the data set. The RACF-indicated bit in the data set's DSCB is on. 
RACROUTE  REQUEST=AUTH,WORKA=RACWK,ENTITY=((R7)),        X
          VOLSER=(R8),CLASS='DATASET',ATTR=ALTER,        X
          RACFIND=YES
  ⋮
RACWK     DS  CL512

Example 2

Invoke the SAF router to perform authorization checking, using the standard form, for an IMS/VS transaction pointed to by register 5. The user requests only read access. 
RACROUTE  REQUEST=FASTAUTH,                             X
          WORKA=RACWK,ENTITY=(R5),                      X
          CLASS='TIMS',WKAREA=FRACWK,                   X
          ATTR=READ
  ⋮
FRACWK    DS  16F
RACWK     DS  CL512