|
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: 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: - Default: RELEASE=1.6
- 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
- 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: - 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.
- 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.
- This parameter applies to REQUEST=AUTH, REQUEST=DEFINE, REQUEST=VERIFY,
and REQUEST=VERIFYX.
- IRR008I through IRR018I, ICH408I, ICH70001I, ICH70002I, ICH70003I,
ICH70004I, ICH70005I, ICH70006I, and ICH70007I messages can be returned
for RACF.
- 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: - 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.
- 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)
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.
Note to reader
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, note that
SAF return code is presented as SAF RC in the following topic.
- 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.
- 270F
- The system could not obtain enough storage to satisfy the request.
This return code may be displayed as a decimal 9999.
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
|