CSVLLIX2 — LLA Module Staging Exit

Topics for This Exit Appear as Follows:

Controlling The Exit Routine Through the Dynamic Exits Facility
Exit Routine Environment
- Exit Recovery
Exit Routine Processing
Programming Considerations
Entry Specifications
- Registers at Entry
- Parameter List Contents
Return Specifications
- Registers at Exit
Coded Example of the Exit Routine

Library lookaside (LLA) improves the performance of fetching modules from both LNKLST and non-LNKLST data sets, and is a control point in managing updates to these modules on DASD. LLA collects statistics such as fetch rates and fetch durations to allow LLA module staging to determine the value of staging each module. LLA module staging runs periodically to perform this evaluation and stages, or places, copies of the most frequently used modules into a virtual lookaside facility (VLF) data space. LLA can then fetch these selected modules from virtual storage without I/O and with a reduced number of processor instructions.

LLA combines four independent components of staging value to determine the net value of staging a module into processor storage (see Exit Routine Processing). LLA multiplies each component of staging value by its weighting factor, adds the products, and determines the net LLA staging value for the module. LLA stages modules that have the highest LLA staging value. Modules with a low LLA value are provided to users through program fetch from DASD.

Before applying the weighting factors to determine whether a module should be staged, LLA calls CSVLLIX2 and passes it the address of a parameter list that contains the weighting factors. CSVLLIX2 can modify the weighting factor values or specify an installation-defined value and thus determine which modules are staged.

You can use CSVLLIX2 to:

Analyze fetch statistics provided in the LLA module staging parameter list (LLP2).
Influence the calculation of the LLA value (which determines if a module should be staged) by altering the weighting factors in the LLP2 parameter list.
Force LLA to stage the module by setting the appropriate return and reason codes.

Controlling The Exit Routine Through the Dynamic Exits Facility

IBM® has defined the CSVLLIX2 installation exit to the dynamic exits facility. You can refer to the exit by the name CSVLLIX2. You can use the EXIT statement of the PROGxx parmlib member, the SETPROG EXIT operator command, or the CSVDYNEX macro to control this exit and the exit routines of the exit.

When you start LLA, if the EXIT2(OFF) statement is not present in the CSVLLAxx parmlib member being used by LLA, the system attempts to add exit routine CSVLLIX2 in the following situations:

no exit routines have been associated with CSVLLIX2 by PROGxx
no exits have been associated using SETPROG
there are no exit routines from a previous LLA start

If you have associated exit routines with CSVLLIX2 the system does not use the default exit routine. In this case, if you require an exit routine of the default name, you must explicitly add the default exit routine to PROGxx.

A change from EXIT2(ON) to EXIT2(OFF) has no effect. If you want to deactivate the CSVLLIX2 exit routine (or any other exit routine for the CSVLLIX2 exit), you can use the PROGxx EXIT statement with SET PROG=xx or you can use SETPROG EXIT.

To limit the number of times the exit routine ends with an abend, before the exit routine becomes inactive, you can use the ADDABENDNUM and ABENDCONSEC parameters on the CSVDYNEX REQUEST=ADD macro, or the ABENDNUM parameter of the SETPROG EXIT operator command. The system disables the exit routine if the exit routine ends with an abend on two successive calls. An abend is encountered when both of the following conditions exist:

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

The system disables the exit routine if the exit routine ends with an abend, as defined above, on two successive calls.

Exit Routine Environment

CSVLLIX2 receives control in the following environment:

Enabled for interrupts.
In supervisor state and in primary ASC mode with the primary ASID equal to the home ASID.
In AMODE 31 and RMODE ANY.
With no locks or ENQs held.
In task mode under a non-jobstep TCB attached by LLA's jobstep program in LLA's address space.
With TCB and PSW keys of zero.

Exit Recovery: The LLA recovery routine protects the exit routines of CSVLLIX2. The recovery routine records diagnostic information in the system diagnostic work area (SDWA), requests recording of the error in the logrec data set, and takes an SVC dump. LLA then retries to a point within LLA staging to call the next exit routine.

Exit Routine Processing

CSVLLIX2 receives control from the LLA staging function before it applies the weighting factors to determine a module's total staged value. LLA staging combines 4 independent staging values to determine the net value of staging a module into processor storage. The 4 values, which are contained in field LLP2VALU of the parameter list, relate to response time, processor storage, contention, and an optional, installation-defined cost. Each staging value is in the range -10,000 to +10,000 and indicates the relative value to the system of LLA staging the module. Each value has a corresponding weighting factor (LLP2WGTS) in the range 0 to 100, used to indicate the relative importance of the value. LLA staging multiplies each factor of staging value by its weighting factor, adds the products, and determines the net LLA staging value for the module.

CSVLLIX2 receives control from LLA staging before it applies the weighting factors to determine whether a module should be staged. CSVLLIX2 can influence the calculation of the module's LLA staging value by altering the appropriate weighting factors. For example, if response time is more important to your installation than processor storage use, you can use CSVLLIX2 to set the response time weighting factor to a high value (70-100) and set the processor storage weighting factor to a low value (0-30).

CSVLLIX2 can introduce its own installation-defined value (LLP2VUSR). The value must be in the specific range (-10,000 to +10,000), and the corresponding weighting factor must be changed from its initial value of zero.

CSVLLIX2 can also force a module to be staged by setting the appropriate return and reason codes. This is a less desirable solution because LLA can then change the staging only at the direction of CSVLLIX2; for example, it could never deactivate the staged module even if it was so infrequently used that it was stolen to auxiliary storage.

The LLP2X1US field in LLP2, the exit parameter list, contains a 31-bit address that points to a 4-byte user data area in the CSA. The user data area is aligned on a fullword boundary and is initialized to 0. The user data area is also pointed to by the LLP1USER field in the CSVLLIX1 (LLA module fetch exit) parameter list. An installation can use the user data area as a means of allowing CSVLLIX1 and CSVLLIX2 to share information. For example, CSVLLIX1 or CSVLLIX2 can acquire storage in the CSA (by issuing a GETMAIN or STORAGE macro) and place the address of this storage in the 4-byte user data area. CSVLLIX1 could then write records to this common storage area during fetch time and CSVLLIX2, when it gets control, could then write the records to DASD. This action could reduce the time CSVLLIX1 needs for processing and thus shorten LLA's path length for fetching a module.

If your installation plans to have both CSVLLIX1 and CSVLLIX2 access the 4-byte user data area (pointed to by LLP1USER and LLP2X1US), both exits must manage the serialization of the area. If only CSVLLIX1 is going to use the area, then CSVLLIX1 must manage the serialization of the user data area. Compare-and-swap (CS) is a potential serialization method. The 4-byte user data area is initialized to 0. If LLA is restarted, the user data area is not reset to 0. It will contain the last value stored in it by either CSVLLIX1 or CSVLLIX2. When using this field as a counter, you must reset it when the condition you are testing for is met.

The LLP2USER field in LLP2, the exit parameter list, points to a 4-byte user data area that is aligned on a fullword boundary and is reserved for CSVLLIX2 to use. CSVLLIX2 can use the 4-byte user data area as a work area to pass information to itself during subsequent invocations. The 4-byte user data area is initialized to zero and subsequently contains any value stored in it by CSVLLIX2. When using this field as a counter, you must reset it when the condition you are testing for is met.

Start of change In most cases LLA does apply the same algorithm to program objects, however in a few situations LLA finds staging in VLF unacceptable due to certain attributes of program objects. For example, if LLA discovers that the number of deferred classes in the header of the program object is not 0 or the program object is a split RMODE module, then LLA cancels the staging algorithm, making a particular program object ineligible for staging. End of change

Programming Considerations

Code the exit routine to be reentrant. There are no restrictions on external routines that CSVLLIX2 can invoke while it has control.

If your installation wants to limit its use of CSVLLIX2, perhaps to improve performance by shortening path length, you can deactivate the exit. CSVLLIX2 is ON by default.

Changing Weighting Factors: The default weighting factors that CSVLLIX2 can change are set to response time=75, contention=50, storage=25, and installation=0. You should not need to change these settings. However, if an adjustment is necessary, consider the following:

Response time (LLP2WRSP)
Keep this weighting factor higher than the others if you have sufficient central storage to hold all the staged modules. Decrease this slightly relative to the storage weighting factor if LLA quickly fills the VLF data space and the data space cannot be enlarged. (To enlarge the data space, increase the value specified by the MAXVIRT keyword for class CSVLLA in the COFVLFxx parmlib member.) Processor time might increase if many staged modules age out to expanded storage because of central storage contention. In general, for the modules that remain backed by central storage, LLA uses slightly less processor time than program fetch for all module sizes.
Contention (LLP2WCTN)
Increase this factor relative to response time if data sets that LLA is managing incur I/O activity that causes disruptive contention. Such data sets are likely to be on volumes shared between systems or on volumes that contain other performance-sensitive data sets. You can use storage isolation to control contention for LLA's VLF data space.
Storage (LLP2WSTO)
Increase this factor if you do not have enough processor storage to hold all the modules. The storage value should always be weighted lower than the response time value because the storage value usually is negative.

The values that LLA calculates using these weighting factors are derived as follows:

Response time (LLP2VRSP)
This value is defined as the time that would be saved per sample if the module were to be fetched from VLF divided by the total time that would have been saved during the previous sample if all modules had been fetched from VLF.
Contention time (LLP2VCTN)
This value is defined as the average difference between the minimum fetch for the module from LLA or DASD, and the duration of the fetch. The average LLA difference is then subtracted from the average DASD difference. The result is multiplied by the number of fetches, and is normalized by dividing by the sum of all the contention deltas from the previous sample.

Contention value helps LLA to compensate dynamically for unbalanced storage and I/O resources in a system.
Storage (LLP2VSTO)
This value is defined as the number of processor storage bytes that would be saved minus the number of bytes that would be spent if the module were to be kept in VLF, normalized by dividing the sum of all the storage deltas accumulated in the previous sample. Storage is saved because users occupy storage for less time while they wait for fetches. Storage is spent because the staged module requires processor storage to back it in the VLF data space. With the exception of some very small and highly used modules, storage value is a negative number.

Changing the Staging Threshold: If your installation has a steady state workload, you should notice a consistency in the modules being staged and in the ranking of the modules. If the same modules are not being staged, or if the ranking of the modules staged fluctuates often, the reason could be that your installation has a large number of modules in its working set and therefore, LLA needs to have a larger sampling of modules on which to base its staging decisions.

Increase the staging threshold (the default is 2000) to provide LLA with a more meaningful sampling on which to base its decisions, so that LLA will consistently stage the most often used modules. It is suggested that the staging threshold be at least 3 times the total number of modules in your installation's working set.

Using the Exit to Influence Module Staging: If you use CSVLLIX2 to force LLA to stage a particular module, the change applies only to the current staging analysis of the module. That is, LLA does not maintain the changed staging status of the module across subsequent exit invocations. In addition, if the exit is deactivated or the code of the exit routine changed, the outcome of staging analysis might be affected.

Depending on your installation's workload, the staging analysis for a given module might be different each time CSVLLIX2 is invoked. If you use CSVLLIX2 to determine whether a particular module should be staged, the exit routine should continue to check the module's staging statistics during subsequent invocations.

If you plan to use CSVLLIX2 to force LLA to stage a particular module regardless of the module's staging statistics, the exit routine should maintain this status each time the exit is invoked. Do this by setting the appropriate return and reason codes. Otherwise, excessive LLA overhead can occur.

For example, avoid using program logic that indicates that a module, if not staged, should be staged, but fails to indicate an action if the module is already staged. In this case, when the exit fails to indicate an action, LLA staging analysis will make its own determination and might deactivate staging for the module. The next invocation of the exit for this module would cause LLA to restage the module, and so on. Excessive LLA overhead results as LLA alternately stages and deactivates the same module repeatedly.

Entry Specifications

LLA passes to CSVLLIX2 the address of the LLP2 parameter list.

Registers at Entry: The contents of the registers on entry to the exit are as follows.

Register: Contents
0: Zero
1: Address of the LLA staging installation exit parameter list (LLP2)
2-12: Not applicable
13: Register save area
14: Return address
15: Entry point address of CSVLLIX2

Parameter List Contents: Register 1 contains the address of LLP2, the LLA staging exit parameter list. The macro IHALLP2 maps data area LLP2. See z/OS MVS™ Data Areas in z/OS® Internet Library at http://www.ibm.com/systems/z/os/zos/bkserv/ for a mapping of the LLP2 data area.

Return Specifications

CSVLLIX2 passes back to LLA both a return code and a reason code to determine the need for LLA module staging.

Registers at Exit: Upon return from the exit processing, the register contents must be as follows.

Register

Contents

0

One of the following reason codes (the reason code in register 0 is dependent upon the return code in register 15):

Reason Code: Explanation
0: Indicates that LLA should use the weighting factors to determine whether the module should be staged. (Set register 15 to 0.)
1: Indicates that LLA is to stage this module. If the module is already staged, it remains staged. (Set register 15 to 4.)
2: Indicates that LLA is not to stage this module. If the module is already staged, LLA stops using the staged copy of the module. (Set register 15 to 4.)

1-14

Restored to contents at entry

15

One of the following return codes:

Return Code: Explanation
0: Indicates that LLA module staging should use the weighting factors to determine whether the module should be staged.
4: Indicates that LLA module staging should not use the weighting factors. The decision to stage or not stage the module is specified by the reason code in register 0.

Coded Example of the Exit Routine

IBM provides a sample CSVLLIX2 exit routine in SAMPLIB for your reference. This routine contains the code for entry to the exit routine (a standard BR14 branch).