Many of the values passed to the RACHECK preprocessing and postprocessing exit are derived from the parameters specified on the RACHECK macro instruction. For details on the RACHECK macro instruction, see SP L:
Supervisor or SP L: System Macros and Facilities.
On entry to the RACHECK preprocessing (lCHRCXOl) and postprocessing (ICHRCX02) exit routines, register 1 contains the address of the following area:
Offset Length
Length address: points to a fullword containing the number of fullwords in this parameter list.
Flag byte 1 address: points to a I-byte area of the following format:
00.. RACFIND was not specified.
10.. RACFIND =NO was specified.
Flag byte 2 address: points to a I-byte area of the following format:
1000 0000 ATTR=ALTER was specified.
0000 1000 ATTR=CONTROL was specified.
0000 0100 ATTR=UPDATE was specified.
0000 0010 ATTR = READ was specified (or assumed).
This value is derived from the ATTR parameter on the RACHECK macro instruction. Note that bit mapping for ATTR differs from bit mapping for the access code (pointed to from offset 48 in the parameter list), which matches the mapping in the RACF data set.
Flag byte 3 address: points to a I-byte area of the following format:
0... DSTYPE=T
.1.. DSTYPE = M was specified .
.. 0. ENTITY = dsname; tape volser or DASD volser addr was specified .
.. 1. PROFILE = profile addr was specified . ... 0 0... Reserved .
. 1.. GENERIC = YES was specified . .. 1. Private area profile requested . ... 0 Reserved.
INSTLN address: points to an area containing the installation parameters. This address is zero if INSTLN was not specified. None of the system modules specify the INSTLN parameter. It is intended for use by installation-written routines that invoke RACHECK to communicate with the RACHECK preprocessing and postprocessing exit routines. Do not confuse this value with the DATA address (pointed to from offset 32 in the parameter list) that comes from a field in the RACF profile for the resource being checked.
ENTITY or PROFILE address: points to an area containing the resource name (for ENTITY) or an area containing the profile (for PROFILE). If ENTITY is used, this area is 44 bytes long for the DATASET class. For general resource classes, the length is taken from the class descriptor table. The name or number is left-justified and padded on the right with blanks. If the exit changes this value, the RACF profile affected is changed but RACF does not communicate the change to the invoker of RACHECK. For example,if a user's authority to a dataset is being checked and the exit changes the entity value, the RACF profile checked is the one named by the changed value, but the data set itself is unchanged. Similar processing applies to the OLDVOL, VOLSER, OWNER, and CLASS parameters.
Note: If you change the entity name, also change the qualifier, whose address is at offset 32 in the ICHCNXOO parameter list, to reflect this change.
Chapter 7. RACF Installation Exits
7 -19
24 4
CLASS address: points to an area containing a I-byte length field containing the classname length followed by a field containing the entity class name.
VOLSER address: points to a 6-byte area containing the volume serial number.
This address points to an area containing blanks if the class is not DATASET.
DATA address: points to a I-byte length field followed by the installation data for the entity specified on RACHECK. This address is zero for the
preprocessing routine. This address is zero for the postprocessing routine if (1) no data is present, (2) the profile could not be retrieved, or (3) the preprocessing routine indicated bypassing of RACHECK.
Work area address: points to a fullword of zeroes on the initial entry to the preprocessing routine. An installation can use this field for any purpose.
Because this field is set to zeroes before entry to the preprocessing exit, the preprocessing and postprocessing exits can use this work area to communicate with each other.
ABEND code address: points to a 4-byte field containing the ABEND code that RACHECK is going to issue. The ABEND code is contained in the low-order 12 bits of the field. The address points to an area containing zeroes if RACHECK is not going to issue an ABEND. (If ABEND processing is to be bypassed by RACHECK, the exit routine can zero the ABEND code. In this case, the eXit routine should also set the return code to zero; otherwise, the ABEND reason code will be passed to the RACHECK caller as a return code.) Do not confuse an ABEND issued by RACHECK with one issued by an invoker of RACHECK. If a user is not authorized to a resource, RACHECK will not issue an ABEND, but the invoker of RACHECK might. For example, OPEN mig!!t issue a 913 ABEND in this case, although RACHECK completed without any ABEND.
Return code address: points to a 4-byte field containing either the return code to be passed back to the RACHECK caller in response to the access request (for the meanings of these return codes, see SPL: Supervisor or SPL: System Macros and Facilities) or the reason code used to cause the ABEND to be issued (for the meanings of these ABEND reason codes, see RACF Messages and Codes). Do not confuse this code with the return code from the RACHECK preprocessing or postprocessing exit routines described in this chapter.
Access code address: points to a I-byte field containing" the user's authorization to the resource that is being checked:
X'80' - ALTER
Resource level number address: points to a I-byte field containing the LEVEL value from the resource profile. This address is zero for the preprocessing routine. This address is zero for the postprocessing routine if (1) the profile could not be retrieved, or (2) the preprocessing routine indicated bypassing of RACHECK.
OLDVOL address: points to a 6-byte area containing the volume se~ial number of a previously defined volume of a multivolume data set or tape v()iume set.
This is blank if OLD VOL was not specified.
Naming conventions address: points to the parameter list of the ICHCNXOO exit.
The ICHCNXOO exit invoked by RACF commands and the ICHUTlOO utility allows an installation to modify or eliminate the RACF DASD data set naming convention. Corresponding processing might be required in the RACHECK preprocessing exit, so a parameter list with similar structure and content is passed to it to allow the use of common routines.
APPL name address: points to an eight-byte field containing the application name (if supplied on the RACHECK macro instruction). The name is left-justified and padded with blanks. If the APPL parameter was not specified, the field contains blanks. RACHECK processing does not reference this field;
this field is intended to provide additional information for the exit routines.
ACEE address: points to a fullword containing ,the address of the ACEE that is used for Rt\CHECK proCe!\sing. If the ACEE parameter was not specified on the RACHECK macro instruction, the fullword pointed to by this value contains zeroes, and the ACEE pointed to byTCBSENV in the current task control block
", (TCB) or ASXBSENV in the address space extension block (ASXB) is used for authority checking.
72 4
OWNER address: points to an eight-byte area containing an identifier that is to be compared with the OWNER field in the resource profile whose access is being checked. If the OWNER parameter was not specified on the RACHECK macro instruction, the area pointed to by this address contains blanks. Note that use of the owner field causes RACHECK to bypass checking of the OPERATIONS attribute during authority checking.
Logging control address: points to a fullword that. the postprocessing exit can use to control auditing. On entry, the fullword is set to zero. The exit may change this value to 4 to unconditionally request logging or to 8 to unconditionally suppress logging. (Note that you can never override the GLOBALAUDIT option.)
ACCLVL value address: points to a I-byte length field followed by 0 to 8 bytes of data from the first subparameter in the ACCLVL keyword on the RACHECK macro.
ACCLVL parameter list address: points to the parameter list passed as the second subparameter in the ACCLVL keyword on the RACHECK macro.
address of fIle sequence number points to a two-byte field containing the file sequence number for a tape data set.
address of tape flag byte: points to a I-byte area of the following format:
10.. TAPELBL=BLP was specified.
01.. TAPELBL = NL was specified.
00.. TAPELBL=SL was speCified . .. 00 0000 Reserved.
address of fourth flag byte: points to a I-byte area of the following format:
1... STATUS = ERASE was specified . . 000 0000 Reserved.
RACHECK reason code address: points to a 4-byte field containing the reason code to be used with the return code pointed to by offset 44. See SPL System Macros and Facilities for the meanings of the RACHECK reason codes. Do not confuse this reason code with the ABEND reason code.
address of NOTIFY userid an 8-byte area containing the userid of the user to be notified when RACF detects an unauthorized attempt to access a resource protected by this profile. This field is valid only for the postprocessing exit and only if the PROFILE specified NOTIFY.
Return Codes - RACHECK Preprocessing Exit
When the RACHECK preprocessing exit routine returns control, register 15 should contain one of the following return codes. Do not confuse these return codes with the return codes from the RACHECK SVC, the meanings of which are documented in SPL: Supervisor and SPL: System Macros and Facilities.
Hex (Decimal)
Exit routine processing is complete. Normal SVC processing is to continue.
The request is not accepted and is to be failed; however, the postprocessing exit is still invoked.
The request is accepted. No more SVC processing is performed; however, the postprocessing exit is still invoked.
Exit routine processing is complete and the request is to be granted.
RACHECK is not to perform any authorization checking on the access list, but other normal RACHECK processing (for example, logging) is to continue.
Note: If register 15 contains any other value, RACHECK issues an ABEND code (382) that indicates an invalid exit return code.
Chapter 7. RACF Installation Exits
7-21
RACF uses resident profiles for three purposes:
• As model profiles, as specified by the MENTITY and MVOLSER parameters on RACDEF. These profiles are built by RACDEF when an MENTITY and MVOLSER value are supplied (either by a caller or by an exit routine) and the exit routine requests that the profile be retrieved and added to a chain of profiles pointed to by the ACEEAMP field. RACINIT delete processing releases the storage used by these profiles.
• As installation-supplied profiles, as specified by an exit routine.
The ICHRRPF macro maps the resident profile. See the RRPF mapping in Chapter 12.
If a profile is created that does not conform to the standard format, it is the responsibility of the RACHECK preprocessing exit routine to ensure that the RACHECK SVC does not refer to that profile (that is, does not return a code of
o
to RACHECK when the PROFILE option is specified).For more information on the format, see the RRPF data area in Chapter 12.
Return Codes - RACHECK Postprocessing Exit
When the RACHECK preprocessing exit routine returns a return code of 4 or 8, and when the RACHECK macro instruction request specified ENTITY = (entity address, CSA) or a private area profile was requested (see flag byte 3), the exit routine ~ust create a profile and return the address of the profile in register 1.
The first word in the profile must contain the subpool number and the length of the profile.
Do not confuse these return codes with the return code from the RACHECK SVC, the meanings of which are documented in SP L: Supervisor and SP L:
System Macros and Facilities
When the RACHECK postprocessing exit routine returns control, register 15 should contain one of the following return codes:
Code
o
4
Meaning
Continue with RACHECK processing. (If the exit routihe changes the return or ABEND code values, RACHECK will use these codes.)
Try the RACHECK SVC again; invoke the RACHECK preprocessing exit routine. (Any values in the return or ABEND code fields are ignored, and the fields are reset to zero. Other fields are not affected. In particular, the INSTLN value is not reinitialized; this preserves any information placed in it by the preprocessing or postprocessing exit routine.)
Note: If register 15 contains any other value, RACHECK issues an ABEND code (382) that indicates an invalid exit return code.