DLF Connect / Disconnect Exit

Topics for This Exit Appear as Follows:

Installing the Exit Routine
Exit Routine Environment
- Exit Recovery
Exit Routine Functions
- Initialization
- Query
- Connect
- Disconnect
Exit Routine Processing
Programming Considerations
- Macro Instructions and Restrictions
Entry Specifications
- Registers at Entry
- Parameter List Contents
Return Specifications
- Registers at Exit
Coded Example of the Exit Routine

This exit provides the control information that hiperbatch and the data lookaside facility (DLF) need.

Hiperbatch is a performance enhancement that can significantly reduce the execution time of certain batch job streams or multi-step batch jobs that access the same VSAM or QSAM data sets. Hiperbatch works with DLF to allow batch jobs to share access to a DLF object. A DLF object is a set of hiperspaces created by DLF that contains QSAM or VSAM data managed by hiperbatch. Storing data into, and retrieving data from, DLF objects is done transparently by the access method; an installation does not need to rewrite its application programs or the JCL needed to run them. The installation does, however, need to provide control information to DLF.

If your system includes RACF® 1.9 or higher, you can define RACF profiles in the DLFCLASS general resource class instead of using this exit routine. However, you must still code the exit; its decisions can override the information in the RACF profiles.

If your system does not include RACF 1.9 or higher, you must code a DLF Connect / Disconnect installation exit routine to provide the needed control information.

You can use the DLF Connect / Disconnect exit to:

Decide whether a job is eligible to connect to a DLF object. (The object will be created if this is the first connection.)
Specify whether or not to retain a DLF object even when no jobs are connected to it. The default is to delete the DLF object when there are no longer any connections to it.
Determine whether a particular data set is eligible for DLF processing, so that if the data set is updated while DLF is not running, DLF will process the updated form of the data set. (See Query.)

To make these decisions, the exit must have access to the DLF control information:

The names of all data sets that you want the system to process as DLF objects
The names of all DLF objects that are to be retained
The users and/or job names that are allowed to access each DLF object

You can store this control information in a data set or code the information in the exit routine. If you have a great deal of control information, or if you plan to update it often, you should consider storing the information in a data set.

Installing the Exit Routine

Before starting the Data Lookaside Facility:

You must include the exit in an authorized library in the LNKLST concatenation.
You must specify the exit name on the CONEXIT keyword in the COFDLFxx parmlib member.

If your installation runs jobs that perform random updates of VSAM or QSAM data sets while other jobs read the data sets, you must name your exit COFXDLF1. Hiperbatch calls this name when DLF is not running to request the exit to query VSAM or QSAM data sets. If your installation does not access VSAM or QSAM data sets when DLF is not running, you may choose any name for the exit. (See Query.)

If you name the exit routine COFXDLF1—specify CONEXIT(COFXDLF1) in the COFDLFxx member in the parmlib—the DLF initialization code will look for that routine in the LPA. If it is not there, it will load the exit routine into the CSA from the LNKLST. Then, as long as the DLF is active, the system will call the exit via a branch to the LPA or CSA address, avoiding a LINK or LOAD.

Note: If you haven't named your exit routine on the CONEXIT keyword in the COFDLFxx parmlib member, the system does a BLDL to the LNKLST for the exit; when BLDL finds the routine, the system issues a LINK with DE= without first searching the LPA. To avoid this overhead where your installation makes infrequent accesses to the same VSAM or QSAM data sets and thus does not need to use hiperbatch, simply don't start the DLF.

You cannot replace the exit while the DLF is active. The exit that is requested when the DLF is started remains in effect for the duration of the DLF address space. To replace the exit, you must stop the DLF, replace the exit (or change the parmlib CONEXIT parameter to point to a different exit), and then start the DLF again.

For general instructions on installing an exit routine, see Link editing an Installation Exit Routine into a Library. For information on how to start the DLF, see z/OS MVS System Commands.

Exit Routine Environment

The DLF exit receives control in the following environment:

Resides in an APF-authorized library in the LNKLST concatenation
Enabled for interrupts
In primary ASC mode
In AMODE 31 and RMODE ANY
In supervisor state with PSW key 0
When called to perform the initialization function, the exit is invoked in the DLF address space. On subsequent calls, in which the routine performs the query, connect, and disconnect functions, the exit routine runs in the address space of the task that issues the request

Exit Recovery

DLF recovery protects the exit.

If the exit abnormally terminates during DLF initialization, the DLF initialization is terminated.

If the exit abnormally terminates during a query call, DLF determines that the data set is not eligible for DLF processing. OPEN processing continues and the job reads the data set from DASD, instead of from a DLF object, and updates the data set on DASD.

If the exit abnormally terminates during a user's attempt to connect to a DLF object, the request is terminated and the user is not connected to the DLF object. OPEN processing continues and the job reads the data set from DASD, instead of from the DLF object.

If the exit abnormally terminates during a user's attempt to disconnect from the DLF object, the user is disconnected from the DLF object.

Exit Routine Functions

The exit is called to perform these functions: initialization, query, connect, and disconnect.

Initialization

When the DLF is started, the exit is invoked with a request from the DLF to perform initialization: the CXTFUN field in the CXT (the exit routine parameter list) is set to 0. If your installation places control information in a data set, use the initialization call to access the data set. On subsequent calls, the exit routine uses the control information in the data set to perform the query, connect, and disconnect functions.

In the CXT, the CXTUDAB field points to a 16-byte area in the CSA. The exit routine can acquire storage in the CSA (for example, by issuing a GETMAIN or STORAGE macro) and place the address of this storage in the first word of a 16-byte area pointed to by CXTUDAB. The exit can then open the data set that contains the DLF control information and read it into the CSA area. DLF passes the pointer to the address of the control information to the exit (in CXTUDAB) every time it is called. The exit now has access to the control information it will need on subsequent calls.

The exit must manage serialization of the 16-byte area in the CSA to prevent the address of the control information from being reset by the exit on a DLF restart while the area is being accessed for a query. An installation can serialize the 16-byte area by, for example, using the third word of the area as a serialization field and using compare-and-swap (CS) as a serialization method. If DLF is restarted, the 16-byte area is not reset to zero. It will contain the last values stored by the exit.

You do not need to code the exit to perform initialization if you code the control information within the exit routine itself. If you code the control information within the exit routine, your exit needs only to return control to DLF on an initialization call. The exit return code is ignored on an initialization call.

Query

If your installation runs jobs that perform random updates of VSAM or QSAM data sets while other jobs read the data sets, you must:

Code your exit routine to perform the query function.
Name your exit COFXDLF1.

If you do not code the exit routine to perform the query function, you can choose any name for the exit.

Hiperbatch calls the exit with a query request (the CXTFUN field in the CXT is set to 1) to determine whether or not a particular VSAM or QSAM data set that is being opened for update or output could be processed as a DLF object. The exit routine searches the installation's control information (its address is pointed to by CXTUDAB) for the name of the data set (in CXTDSN) and, optionally, its volume serial (in CXTVOL). If the data set is listed in the control information, the exit routine sets return code 0 to indicate that the data set is eligible for DLF processing. If the data set is not listed in the control information, the exit routine sets return code 8 to indicate that the data set is not eligible for DLF processing.

If the data set is listed in the control information, hiperbatch records the name of the data set to ensure that if a data set is opened while DLF is down, and DLF is started before the data set has been closed, subsequent jobs that open the data set will connect to its updated form.

It is strongly recommended that you start DLF before starting JES. This action is necessary to ensure that readers of VSAM and QSAM data sets read the latest level of the data sets.

Connect

DLF calls the exit when a job opens a VSAM or QSAM data set (the CXTFUN field in the CXT is set to 2). At this time, the exit routine must determine whether the user or job requesting the connection is eligible to connect to the DLF object. The exit also must specify whether the DLF object is to be retained. (If RACF profiles exist for the DLF objects, the exit routine might not need to make these decisions, but it can override the RACF information.) The exit sets a return code that indicates whether the connection is to be permitted, or whether RACF information to is to be used to make the decision.

If DLF is not active, connect processing always invokes exit COFXDLF1.

Disconnect

DLF calls the exit when it disconnects a user from a DLF object (the CXTFUN field in the CXT is set to 3). The exit return code is ignored on a disconnect call.

Exit Routine Processing

When a user attempts to open a VSAM or QSAM data set, and DLF is active, the system tries to connect the user to the DLF object corresponding to the data set.

The exit is only called after RACF or another security product has already granted the user access to the VSAM or QSAM data set. Then, on a system with RACF 1.9 or higher, DLF will check the job or user's eligibility to connect to the DLF object. If RACF approves the request, DLF updates CXTSFLGS in the CXT, the exit parameter list, with the connect information. Then DLF passes the CXT to the exit routine, which can override the RACF decision to connect to a DLF object.

On a system without RACF 1.9, the CXTSFLGS bits are set to zero, and the exit routine must determine whether the application is eligible to connect to a particular DLF object.

After exit routine processing, the exit returns a code specifying whether or not the user is allowed to connect to the DLF data object. The exit routine can override the eligibility of the DLF data object and inform DLF not to connect the DLF object to the user. The exit also sets bit CXTRTAIN in CXTUDATA to '1'B if the DLF object is to be retained when no jobs are connected to it. CXTRTAIN will be honored only if the data set is being opened for update (QSAM) or load (VSAM) mode.

For more information on the return codes the exit routine can set, see Registers at Exit.

Programming Considerations

If your installation does not include RACF 1.9 or higher (or if you are using the exit to override RACF decisions), the exit must determine which connections will be permitted. The exit must have access to the following:

The names of all data sets that you want the system to process as DLF objects
The names of all DLF objects that are to be retained
The users and/or job names that are allowed to connect to each DLF object.

The exit routine must be reentrant and must reside in an APF-authorized library in the LNKLST concatenation.

The installation determines the maximum number of VSAM/QSAM data sets for which DLF objects may exist, based on available extended storage, and places the value in the CXTDSMAX field. (The default is 50.) This value is read only on the first query or connect call to the exit. It is recommended that you code the exit to store the proper value in CXTDSMAX on all query and connect calls to the exit.

When the DLF is active, the exit is called for every OPEN (connect) and every CLOSE (disconnect) issued by a VSAM or QSAM application. If you plan to have the exit routine search very long lists of names, you should consider using a more efficient search technique than sequential (for example, a binary search).

Macro Instructions and Restrictions

With one exception, the exit routine cannot issue (or cause another program to issue) the OPEN macro, because the exit is already running under OPEN processing. The exception is the initialization function; during this call, the exit routine can issue the OPEN macro.

Entry Specifications

DLF passes to the exit the address of a fullword that points to the CXT, the exit parameter list.

Registers at Entry

The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Not applicable
1: Address of a fullword that points to the CXT, which is mapped by COFZCXIT
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of the exit routine

Parameter List Contents

Register 1 contains the pointer to the fullword that contains the address of the CXT, the exit parameter list. The CXT is described in z/OS MVS Data Areas in z/OS Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/.

There is no field in the CXT that indicates whether or not a particular connection is allowed. The exit must set a return code on the connect exit call to communicate this information to DLF.

Note:

The exit routine indicates whether or not an object is to be retained by setting the CXTRTAIN bit on the connect exit call.
To include the CXT mapping in your exit routine, you must code 'COPY COFZCXIT' in the routine.

Return Specifications

A return code from the exit indicates whether the DLF object is eligible to be connected to the user (query), or whether the DLF object should be connected to the user (connect).

The exit routine indicates whether or not an object is to be retained by setting the CXTRTAIN bit on the connect exit call.

Registers at Exit

Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0-1

Irrelevant

2-14

Same as at entry

15

One of the following return codes:

Query Return Code: Explanation
0: The data set is eligible for DLF processing.
4: DLF is to use information from the security product (e.g., RACF) to determine whether the data set is eligible for DLF processing.
8: The data set is not eligible for DLF processing.

Connect Return Code: Explanation
0: DLF is to permit the user to connect to the DLF object.
4: DLF is to use information from the security product (e.g., RACF) to determine whether the user is authorized to connect to the DLF object. If RACF 1.9 or higher is not included in the system, DLF is not to permit the user to connect to the DLF object.
8: DLF is not to permit the user to connect to the object.

Coded Example of the Exit Routine

IBM® provides two coded examples of the DLF Connect / Disconnect installation exit routine in SYS1.SAMPLIB. These are COFXDLF1 and COFXDLF2.

COFXDLF2 requires the use of two routines, COFXUPDT and COFXMACS, both of which are also provided in SYS1.SAMPLIB.