RASE: Resource Access Security user exit (DFSRAS00 and other RASE exits)

The Resource Access Security user exit (RASE) authorizes IMS resources such as transactions, PSBs, or output LTERM names. This user exit is called after the SAF interface is called.

Subsections:

About this routine
Communicating with IMS

About this routine

Start of change This user exit is called during IMS dependent region initialization, or during CCTL, ODBA, or ODBM connection, to allow the user to instruct IMS to perform one of the functions described in the return codes section. For example, this user exit can terminate a connection with a user abend code 437. End of change

This user exit is called to perform pre-authorization processing and can instruct IMS to skip PSB or transaction authorization processing for any of the following thread instances:

IMS dependent regions, CCTL connections
The pre-authorization process is performed only if the exit returns with return code 4 or 24 from initialization or connection processing, and ISIS=R or ISIS=A is specified.
ODBA connections
The pre-authorization process is performed only if the exit returns with return code 4 or 24 from connection processing, and one of the following conditions is true:
- ODBASE=Y is specified.
- ODBASE=N and either ISIS=R or ISIS=A is specified.
ODBM connections
The pre-authorization process is performed only if the exit returns with return code 4 or 24 from connection processing, and one of the following conditions is true:
- ODBMSECURE=R or ODBMSECURE=A is specified.
- ODBMSECURE=I or ODBMSECURE is not specified. ODBM runs without RRS (RRS=N). Either ISIS=R or ISIS=A is specified.
- ODBMSECURE=I or ODBMSECURE is not specified. ODBM runs with RRS (RRS=Y). ODBASE=Y is specified.
- ODBMSECURE=I or ODBMSECURE is not specified. ODBM runs with RRS (RRS=Y). ODBASE=N is specified. Either ISIS=R or ISIS=A is specified.

Start of change If ISIS=A, ISIS=C, ODBMSECURE=A, or ODBMSECURE=E is specified, the RASE user exit is required at IMS initialization. If the exit is not available during IMS initialization, IMS terminates with a user abend code 107, subcode x'04'. The RASE user exit is optional if none of ISIS=A, ISIS=C, ODBMSECURE=A, and ODBMSECURE=E is specified. End of change

The RASE user exit can be added or deleted using the REFRESH USEREXIT command. If you delete the RASE user exit with the REFRESH USEREXIT command, DFS4585W message is issued. The ISIS and ODBASE values are included in the message text.

Start of change Specify the requirement to call the SAF interface and user exit for ODBM threads using the ODBMSECURE parameter at system initialization. End of change

This user exit does not support callable services.

The following table shows the attributes for the Resource Access Security user exit.

Table 1. Resource Access Security user exit attributes
Attribute	Description
IMS environments	DB/DC, DBCTL, DCCTL
Naming convention	You can name this exit routine DFSRAS00 and link it into a library that is included in the STEPLIB concatenation. If DFSRAS00 is linked into a library in the STEPLIB concatenation and the USER_EXITS section of the DFSDFxxx member defines exit routines, the exit routines defined in the DFSDFxxx member will be loaded. DFSRAS00 is only loaded if it is listed as one of the exit routines in the DFSDFxxx member. Alternatively, you can define one or more exit routine modules with the EXITDEF parameter of the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set. The routines are called in the order that they are listed in the parameter.
Binding	You must write the exit routine as reentrant.
Including the routine	The module or modules must be included in an authorized library in the JOBLIB, STEPLIB, or LINKLIST concatenation. No additional steps are necessary to use a single exit routine that is named DFSRAS00. If you use multiple exit routines, specify EXITDEF=(TYPE=RASE,EXIT=(exit_names)) in the EXITDEF parameter of the USER_EXITS section of the DFSDFxxx member of the IMS.PROCLIB data set.
IMS callable services	This routine is not eligible for IMS callable services.
Sample routine location	IMS.ADFSSMPL

Communicating with IMS

IMS uses the entry and exit registers, as well as parameter lists, to communicate with the user exit.

Contents of registers on entry

On entry, the user exit must save all registers using the provided save area. The registers contain the following:

Register	Contents
1	Address of the IMS standard user exit parameter list
13	Address of the save area.
14	Return address of IMS.
15	Entry point address of user exit.

IMS standard user exit parameter list (SXPL)

This user exit uses the Version 6 standard exit parameter list. The address of the work area passed to this user exit in SXPLAWRK can be different each time that this user exit is called.

If your RASE user exit can be called in an enhanced user exit environment, additional user exit routines can be called after your routine. When your user exit routine finds a transaction upon which to act, it can set SXPL_CALLNXTN in the byte that SXPLCNXT points to. This tells IMS to not call additional exit routines.

Resource Access Security exit routine parameter list

The following table shows the function-specific parameter list that is mapped by DFSRASL.

Table 2. Function-specific parameter list mapped by DFSRASL
Field	Offset	Length	Content
RASLVER	0	4	Version number for DFSRASL
RASLFUNC	4	1	Reason for entering the RASE user exit: X'01' Initialization X'02' Authorize transaction (MPP, JMP) X'03' Authorize PSB (IFP, non-message-driven BMP, JBP, DRA/CCTL\|ODBA) X'04' Authorize transaction and PSB (message-driven BMP) X'05' Authorize PSB and output LTERM (non-message-driven BMP, JBP) X'06' Authorize PSB and output transaction (non-message-driven BMP, JBP) X'07' Dependent region initialization X'08' AER/ODBA thread initialization or connection X'09' CCTL/DBCTL thread initialization or connection X'0A' Pre-authorize PSB or transaction for dependent region or CCTL/AER thread. This function skips normal PSB or transaction authorization for functions X'02' to X'06' that would normally be invoked after the pre-authorization processing. X'0B' ODBM connection initialization X'0C' ODBM thread APSB PSB authorization
RASLENVR	5	1	Type of dependent region for which exit was called: X'01' MPP X'02' IFP X'03' Message-driven BMP X'04' Non-message-driven BMP X'05' JMP X'06' JBP X'07' DRA thread from a CCTL task X'08' DRA thread from an ODBA task X'09' CPI-C MPP X'0A' ODBM thread
RASFLG1	6	1	Flag byte: X'01' ODBASE=Y specified X'02' ISIS=C specified X'04' ISIS=R specified X'08' ODBMSECURE=R X'10' ODBMSECURE=E Note: If bit X'04' and bit X'02' are both on, ISIS=A is specified for the IMS system. Note: If bit X'08' and bit X'10' are both on, ODBMSECURE=A is specified for the IMS system.
RASLESV	7	1	Reserved
RASLTRAN	8	8	Transaction code (for BMPs, from IN= if message driven, and from OUT= if non-message-driven)
RASLTSRC	16	4	SAF return code for transaction
RASLTRRC	20	4	RACF® (or equivalent) return code for transaction
RASLTRRS	24	4	RACF (or equivalent) reason code for transaction
RASLPSB	28	8	PSB name
RASLPSRC	36	4	SAF return code for PSB
RASLPRRC	40	4	RACF (or equivalent) return code for PSB
RASLPRRS	44	4	RACF (or equivalent) reason code for PSB
RASLLTRM	48	8	Output LTERM name
RASLLSRC	56	4	SAF return code for LTERM
RASLLRRC	60	4	RACF (or equivalent) return code for LTERM
RASLLRRS	64	4	RACF (or equivalent) reason code for LTERM
RASLECB	68	4	ECB address
RASLTCDE	72	8	Input transaction code
RASLPGM	80	8	Program name
RASLUSID	88	8	User ID of dependent region
RASLGRPN	96	8	Group name
RASLSSTY	104	1	IMS environment flag: X'01' DB/DC system X'02' DCCTL system X'03' DBCTL system
RASLROLE	105	1	XRF role flag: X'01' XRF active IMS X'02' XRF alternate IMS
RASLMVSL	106	1	z/OS® version and release on which IMS was generated
RASLUIDI	107	1	User ID indicator: RASLUIDU User ID in RASLUSID field RASLUIDL LTERM in RASLUSID field RASLUIDP PSB name in RASLUSID field RASLUIDO Other in RASLUSID field
RASLIMSI	108	8	IMS subsystem identifier
RASLIMSL	116	4	IMS version and release
RASLJOBN	144	8	Job name for the dependent region or CCTL/AER address space
RASLSSNM	152	8	Subsystem name for the CCTL/AER thread

Notes:

When the RASE user exit is used to authorize two resources, the exit routine is called twice: once for each resource. On the first call, one resource field (RASLTRAN, RASLPSB, or RASLLTRM) contains the resource name and the other resource field contains binary zeros. If the first call is successful, on the second call, the resource field that contained zeros in the first call contains the resource name and the other resource field that contained the resource name contains binary zeros.
For example, to authorize a PSB and output LTERM, the first call is made with the RASLPSB containing the PSB name and RASLLTRM containing binary zeros. On the second call, RASLPSB contains zeros and RASLLTRM contains the LTERM name.

Contents of registers on exit

Before returning to IMS, the exit routine must restore all registers except for register 15, which contains one of the following return codes:

Return code	Meaning
0	Resources valid for this user
4	IMS must perform pre-authorization processing for PSB or transaction authorization. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'07', X'08', or X'09'.
8	Resources invalid for this user. For function codes X'07', X'08', and X'09' in the RASLFUNC field, this return code instructs IMS to issue a DFS2854A message and terminate the dependent region or CCTL/AER thread with ABENDU0437.
12	IMS must skip the subsequent PSB or transaction authorization processing for this instance of this thread. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'0A'.
16	IMS must skip all subsequent PSB or transaction authorization processing for all instances of this thread. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'07', X'08', or X'09'.
20	IMS must skip the subsequent user authorization processing of the IMS APPL ID during dependent region initialization or CCTL/AER thread connection. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'07', X'08', or X'09'. If this return code is specified, IMS will skip the SAF FASTAUTH call that is normally performed for PSB or transaction authorization when ISIS=A or R is specified for the IMS system.
24	IMS must perform authorization processing as indicated in both return code 4 and return code 20. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'07', X'08', or X'09'.
28	IMS must perform authorization processing as indicated in both return code 16 and return code 20. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'07', X'08', or X'09'.
32	IMS must perform the subsequent PSB authorization processing for this instance of this thread, but must skip the subsequent transaction or LTERM authorization processing that is normally performed. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'0A' for a message-driven BMP or for a BMP/JBP with the OUT= parameter specified.
36	IMS must perform the subsequent transaction or LTERM authorization processing for this instance of this thread, but must skip the subsequent PSB authorization processing that is normally performed. IMS honors this return code instruction only when the function code in the RASLFUNC field is X'0A' for a message-driven BMP or for a BMP/JBP with the OUT= parameter specified.