BSEX: Build Security Environment user exit (DFSBSEX0 and other BSEX exits)

The Build Security Environment user exit provides users with a mechanism to tell IMS whether or not to build the RACF® or equivalent security environment in an IMS dependent region for an application that has received its input message from neither OTMA nor an LU 6.2 device.

Use the Build Security Environment user exit to tell IMS™ whether to build the RACF® or equivalent security environment in an IMS dependent region for an application that has not received its input message from OTMA or from an LU 6.2 device.

You can also use this user exit to request that IMS bypass some part of the security processing in the dependent region when one of the following events occurs for a message that did not originate from an OTMA or LU6.2 device:

CHNG call.
AUTH call.
Deferred conversational program switch on the local system where the inputting terminal is active. Security authorization for the deferred conversational program switch occurs only on the local system.

Subsections:

About this routine
Communicating with IMS

About this routine

The Build Security Environment user exit receives control before the first or next input message is given to an IMS application program and the input message is from neither OTMA nor an LU 6.2 device.

This routine executes in key 7, non-cross-memory mode under the dependent region TCB.

The following table shows the attributes of the Build Security Environment user exit.

Table 1. Build security environment user exit attributes
Attribute	Description
IMS environments	DB/DC, DCCTL. Note: Also supported in a DBCTL environment for non-message driven BMPs.
Naming convention	You can name this exit routine DFSBSEX0 and link it into a library that is included in the STEPLIB concatenation. If DFSBSEX0 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. DFSBSEX0 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 DFSDF`xxx` member of the IMS.PROCLIB data set. The routines are called in the order they are listed in the parameter.
Binding	You must write this user exit using reentrant coding techniques. You must link your user exit into the IMS.SDFSRESL library. If you use IMS callable services, you must link DFSCSI00 with your user exit. The following is an example of the bind JCL statements needed: `INCLUDE LOAD(DFSBSEX0) INCLUDE LOAD(DFSCSI00) ENTRY DFSBSEX0 NAME DFSBSEX0(R)`
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 DFSBSEX0. If you use multiple exit routines, specify EXITDEF=(TYPE= BSEX,EXIT=(exit_names)) in the EXITDEF parameter of the USER_EXITS section of the DFSDF`xxx` member of the IMS.PROCLIB data set.
IMS callable services	To use IMS callable services with this user exit, examine the value of the SXPLATOK field in the IMS standard user exit parameter list: If SXPLATOK is zero, you cannot use IMS callable services with this user exit. If SXPLATOK is non-zero, the value is the callable services token for this user exit. You can use the 256-byte work area addressed by the SXPLAWRK field to call DFSCSIF0.
Sample routine location	No sample exit routine is provided.

Communicating with IMS

IMS uses the entry registers, the Standard User exit parameter list (SXPL), and the Build Security Environment user exit (BSEX) parameter list to communicate with this routine.

This routine uses register 15 to communicate with IMS.

Contents of registers on entry

The contents of the registers on entry are as follows:

Register	Contents
Register	Contents
1	Address of the IMS Standard User exit parameter list (SXPL).
13	Address of a single standard z/OS® save area.
14	Return address to IMS.
15	Address of BSEX.

All other registers are undefined.

Contents of registers on exit

The contents of the registers on exit are as follows:

Register	Contents
15	Return code indicating requested action: Return Code (decimal) Meaning 00 IMS is not to build the security environment during the scheduling phase of the transaction. The security environment can be built later if needed for processing a CHNG call, AUTH call, or a deferred conversational program switch. 04 IMS is to build the security environment during the scheduling phase of the transaction. If the security environment is needed later by a CHNG call, AUTH call, or a deferred conversational program switch, this same security environment is used. If the application program does not ever need the security environment, the build of the security environment is unnecessary. 08 Invoke the SAF interface (RACF, or equivalent product) on a CHNG call, an AUTH call, and a deferred conversational program switch, but bypass the dynamic creation of the security environment. If the transaction is running in the local system, and the user who entered the transaction is still signed on, the security environment created by SIGNON is used. Otherwise, the default security environment of the IMS control region or the IMS dependent region is used for the SAF call. Normally, the security environment of the dependent region is used. However, if the dependent region is running with LSO=Y or is a BMP with PARDLI=1 specified, then the security environment of the Control Region is used. 12 Bypass invoking the SAF interface on a CHNG call, an AUTH call, and a deferred conversational program switch. 16 Bypass invoking the SAF interface on a CHNG call, an AUTH call, and a deferred conversational program switch, and bypass the calls to the DFSCTRN0 and DFSCTSE0 user exits. 20 Invoke the SAF interface on a CHNG call, an AUTH call, and deferred conversational program switch, and bypass the calls to the DFSCTRN0 and DFSCTSE0 user exits.

Contents

Return code indicating requested action:

Return Code (decimal): Meaning
00: IMS is not to build the security environment during the scheduling phase of the transaction. The security environment can be built later if needed for processing a CHNG call, AUTH call, or a deferred conversational program switch.
04: IMS is to build the security environment during the scheduling phase of the transaction. If the security environment is needed later by a CHNG call, AUTH call, or a deferred conversational program switch, this same security environment is used. If the application program does not ever need the security environment, the build of the security environment is unnecessary.
08: Invoke the SAF interface (RACF, or equivalent product) on a CHNG call, an AUTH call, and a deferred conversational program switch, but bypass the dynamic creation of the security environment. If the transaction is running in the local system, and the user who entered the transaction is still signed on, the security environment created by SIGNON is used. Otherwise, the default security environment of the IMS control region or the IMS dependent region is used for the SAF call. Normally, the security environment of the dependent region is used. However, if the dependent region is running with LSO=Y or is a BMP with PARDLI=1 specified, then the security environment of the Control Region is used.
12: Bypass invoking the SAF interface on a CHNG call, an AUTH call, and a deferred conversational program switch.
16: Bypass invoking the SAF interface on a CHNG call, an AUTH call, and a deferred conversational program switch, and bypass the calls to the DFSCTRN0 and DFSCTSE0 user exits.
20: Invoke the SAF interface on a CHNG call, an AUTH call, and deferred conversational program switch, and bypass the calls to the DFSCTRN0 and DFSCTSE0 user exits.

Note:

For return codes 08, 12 and 16, IMS does not dynamically build the security environment during transaction scheduling, or later for a CHNG call, an AUTH call, or a deferred conversational program switch.
When return code 16 is used, the application gets a status code in the IOPCB of blanks. For the AUTH call, the status field in the I/O area has the value 24 (X'18'): transaction authorization not active.

All other registers are to be restored by this routine.

IMS standard user exit parameter list

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 BSEX user exit can be called in an enhanced user exit environment, additional user exit routines might 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.

Build Security Environment user exit (BSEX) parameter list

The address of the BSEX parameter list (mapped by DFSBSEXP) on entry to this routine is contained in field SXPLFSPL of the IMS Standard User Exit parameter list. The following table describes the BSEX parameter list.

Table 2. BSEX parameter list (mapped by DFSBSEX0)
Offset	Field length	Description
X'00'	4 bytes	Transaction scheduling class.
X'04'	8 bytes	Transaction code of the input transaction.
X'0C'	8 bytes	PSB name.
X'14'	8 bytes	Program name.
X'1C'	8 bytes	User ID. Specifies one of the following: Actual user ID of the user who entered the transaction. LTERM name of the terminal from which the transaction was entered. Blanks. This is the user ID for which the security environment will be built if requested by this exit routine.
X'24'	8 bytes	Group name.
X'2C'	32 bytes	Application parameter (APARM= on dependent region JCL).
X'4C'	64 bytes	First 64 bytes of the input message or zeros if the input transaction is conversational.
X'8C'	8 bytes	User ID of the dependent region address space.
X'94'	1 byte	Indicator for contents of user ID field: U User ID L LTERM P PSB name O Other name
X'95'	3 bytes	Reserved.