Monitoring fetch and unfetch processing

The CSVFETCH exit provides information about the fetching (or unfetching) of a module. The exit is primarily intended to be used as part of monitoring (whether for reporting or debugging). The exit will be called holding the local lock. The exit routine must not release the local lock.

For fetch events, the exit is called after the module has been fetched. For unfetch events, the exit is called before the module is unfetched.

The system takes no action as a result of exit routine processing.

These are the conditions under which the exit routine will be called and the ServiceID that will be specified on that call:

Fetch: Increment of module use count, not z/OS UNIX
ServiceID: x'00000001_00000000' if module storage is obtained, first copy of major name now in use, x'00000002_00000000' if module storage already existed on job pack queue and is being used)
Unfetch: Delete or Task Termination or RB Termination, decrement of module use count
ServiceID: x'0000000_00000001' if no copy still in use, module storage freed, x'00000000_00000002' if a copy is still in use, module storage not freed
Fork child processing, "creation" of child module
ServiceID: x'00000080_00000000'
z/OS UNIX fetch (using "load" or "xctl")
ServiceID: x'00000004_00000000' if module storage is obtained, first copy of major name now in use), x'00000008_00000000' if module storage already existed on job pack queue and is being used
Fetch of module from LPA
ServiceID: x'00000010_00000000'
Delete of module from LPA
ServiceID: x'0000000_00000010'
Fetch for Load with Address
ServiceID: x'00000020_00000000' The parameter area will identify that this was a load-with-address
z/OS UNIX fetch with address
ServiceID: x'00000040_00000000' The parameter list will identify that this was a load-with-address

Data presented to exit routine:

Fetch event:

Module name or Path name
UCB address plus CCHH of the fetch (when available)
Address of CDE (may be minor with address of major, or major with address of XTLST) so can locate the extents
DCB address or indication of LNKLST
Other options that might have been requested such as load with address, global=yes, global=(yes,fixed)

Unfetch (Delete) event:

Module name or Path name
Address of CDE (can be minor with address of major, or major with address of XTLST, as indicated by bit CDMIN)
Entry point address

Note:

For a load with address, there will be a "fetch" event but there will be no "unfetch" event
For a load from LPA, if there is no explicit delete, there will be no "unfetch" event
For a load into private storage, if there is no explicit delete, there could be a single unfetch event covering all the uses of the module

Termination considerations:

When the system implicitly deletes/unfetches at task termination, there may be a single unfetch event covering all the uses of the module. And that unfetch event could be done using the "major name" rather than for each individual "alias" that might have been loaded. You cannot necessarily "pair off" individual entries for "fetch" with entries for "unfetch". But you could pair off a fetch entry that obtained the storage for the module (according to the major name) and an unfetch entry that freed the storage (according to the major name).
For memory termination there will be no unfetch events (so no way to "pair off").
When a job has an LPA module loaded and terminates without deleting there is no event

Considerations regarding alias and major:

If you load an "alias", the system creates entries for the alias and the major name. You would get a fetch event for the alias, and the CDE for the alias would give you access to the CDE for the major which in turn would have the information about the module storage. If this was the load for which the module storage was obtained, the "fetch_GetStore" event would be indicated; otherwise the "fetch_JPQ" event would be indicated
If you load a reentrant usable "major" and then subsequently load an "alias" of that major, the alias would be considered to be found on the job pack queue (because the module was indeed already loaded) and the "fetch_JPQ" event would be indicated.
If you delete an "alias" and there are still uses of the "major" (or of another alias of that major), the CDE for the "alias" will remain in place. When there are no more uses of the module, the module storage is freed and the CDEs that are were built (both "major" and "alias") are freed.

CSVFETCH exit routine processing

The CSVFETCH exit routine, if defined, receives control on fetch and unfetch events. The CSVFETCH exit should be considered performance-sensitive, so the exit routine should do as little as possible.

Installing CSVFETCH

Use the CSVDYNEX macro to connect an exit routine to the dynamic exits processing. For example:

              CSVDYNEX REQUEST=ADD,                 X
                    EXITNAME=THEEXIT,               X 
                    MODNAME=THEMOD
       .
       .
       .
     THEEXIT  DC CL16'CSVFETCH'
     THEMOD   DC CL8'FTCHXRTN'

The exit routine must be reentrant and AMODE 31.

See Using dynamic exits services for a description of CSVDYNEX processing.

CSVFETCH exit routine environment

The exit routine receives control in the following environment:

In supervisor state with PSW key 0.
In dispatchable unit mode of task, running under the task and request block of the fetch or unfetch processing.
In cross memory mode of PASN=HASN=SASN.
In AMODE 31.
In primary ASC mode.
Enabled for I/O and external interrupts.
With the local lock held (the exit routine must not release the local lock)
With parameter areas in the primary address space. The parameter list is described below.
In the address space in which the fetch or unfetch was initiated
Under the task in which the fetch or unfetch was initiated

CSVFETCH exit routine recovery

The exit routine should provide its own recovery, using SETFRR. If the exit routine ends abnormally, its recovery routine will get control before the recovery routine established by the system.

You can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro to limit the number of times the exit routine abnormally ends before it becomes inactive. An abend is counted under the following conditions:

The exit routine does not provide recovery, or the exit routine does provide recovery but percolates the error.
The system allows a retry, that is, the recovery routine is entered with bit SDWACLUP off.

By default, the system disables the exit routine when it abends on two consecutive calls.

Programming considerations

Code the exit routine to be reentrant, and to have AMODE 31.
The exit routine should not modify the parameter areas other than the 1024-byte workarea.
Because the CSVFETCH exit is called with ServiceIDs, you can use ServiceMask to indicate for which events you want the exit routine to get control. For example, to get control only for non-UNIX non-LPA fetches and for unfetches, a service mask of C0000000C0000000 can be used (ORing together the values for each event)

Registers at entry to CSVFETCH exit routine: The contents of the registers on entry to a CSVFETCH exit routine are:

Register: Contents
0: Contains no information for use by the exit routine
1: Address of parameter area
2-12: Contains no information for use by the exit routine
13: Address of 144-byte standard save area
14: Return address
15: Entry point address

Registers at exit from CSVFETCH exit routine: Upon return from CSVFETCH processing, the register contents must be:

Register: Contents
0-1: Need not contain any particular value
2-13: Restored to contents at entry
14: Need not contain any particular value
15: 0

Parameter area at entry to CSVFETCH exit routine:

Word 0: Address of 1024-byte work area on a doubleword boundary. This area can be used as a dynamic area by the module, possibly allowing it to avoid doing GETMAIN/FREEMAIN on entry or exit.
Word 1: Address of an area mapped by macro CSVFTCHX

Disassociating CSVFETCH

Disassociate the exit routine from CSVFETCH when it should no longer receive control. Use the CSVDYNEX macro to disassociate the exit routines. You can DELETE the exit routine or you can MODIFY the exit routine to an inactive state. For example:

              CSVDYNEX REQUEST=DELETE,                                      X
                    EXITNAME=THEEXIT                                        X
                    MODNAME=THEMOD
       .
       .
       .
     THEEXIT  DC CL16'CSVFETCH'
     THEMOD   DC CL8'FTCHXRTN'