Dynamic LPA services allow modules to be added to or deleted from
LPA after IPL. Because any product can own LPA modules and have an
interest in updating their control structures, an exit (CSVDYLPA)
is provided from dynamic LPA services. Providing lists of modules
added to or deleted from LPA, the exit is intended to be used as a
notification mechanism so that products can update internal control
structures with the new module addresses.
The system takes no action as a result of exit routine processing.
CSVDYLPA routine processing. The CSVDYLPA
routine, if defined, receives control when the system processes a
dynamic LPA services request, either via
- the CSVDYLPA macro,
- the SETPROG LPA operator command, or
- an LPA statement within PROGxx referenced by the SET PROG=xx operator
command.
Dynamic LPA services are documented in
z/OS MVS Programming: Authorized Assembler Services Reference ALE-DYN. The CSVDYLPA exit routine can be used to update control structures
that had captured the addresses of particular LPA modules, upon replacement
of a module within LPA.
Installing CSVDYLPA. Use the CSVDYNEX
macro to connect a routine to the dynamic LPA processing. For example:
CSVDYNEX REQUEST=ADD, X
EXITNAME=THEEXIT, X
MODNAME=THEMOD
.
.
.
THEEXIT DC CL16'CSVDYLPA'
THEMOD DC CL8'DYLPARTN'
The exit routine must be reentrant and AMODE 31.
See Using dynamic exits services for a description of CSVDYNEX processing.
CSVDYLPA routine environment. The
routine receives control in the following environment:
- In supervisor state with PSW key 0.
- In dispatchable unit mode of task, running under the address space,
task and request block of the caller of CSVDYLPA.
- In cross memory mode of PASN=HASN=SASN.
- In AMODE 31.
- In primary ASC mode.
- Enabled for I/O and external interrupts.
- With no locks held.
- With parameter areas in the primary address space. The parameter
list is described below. The module information area pointed to by
the parameter list is mapped by the CSVLPRET macro.
- In the address space in which CSVDYLPA REQUEST=ADD was issued,
or the master scheduler address space for the SETPROG or SET PROG
operator commands.
- The exit uses fastpath=yes for CSVDYNEX REQUEST=CALL, and will
retry (continue calling) on an exit routine error.
- With ENQ resource SYSZCSV.CSVDYLPA held exclusive.
- The programmer should not use CSVDYLPA REQUEST=ADD or CSVDYLPA
REQUEST=DELETE within the exit routine.
CSVDYLPA routine recovery. The routine
should provide its own recovery, using ESTAE, ESTAEX, or SETFRR EUT=YES.
If the exit routine ends abnormally, its recovery routine will get
control before the recovery routine established by the CSVDYLPA service.
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. The programmer
should include the CSVLPRET macro which maps one of the input parameters
and provides equate symbols for use by the exit routine.
Code the exit routine to be reentrant, and to have AMODE 31.
The exit routine should not modify the parameter areas.
Registers at entry to CSVDYLPA routine. The
contents of the registers on entry to a CSVDYLPA 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 72-byte standard save area
- 14
- Return address
- 15
- Entry point address
Parameter area at entry to CSVDYLPA routine. - Word 1
- Address of fullword containing 0 (symbol CsvdylpaFunctionAdd)
if processing an ADD request or 1 (symbol CsvdylpaFunctionDelete)
if processing a DELETE request.
- Word 2
- Address of fullword containing the number of module entries
in the area pointed to by parameter list word 3.
- Word 3
- Address of module information entries. The entries
are contiguous, each mapped by DSECT LPMEA in macro CSVLPRET. The
entries are not sorted. Only entries with bit LpmeaSuccess on should
be processed; others should be skipped. When processing a delete request,
the information presented for a deleted entry indicates information
about the now-current copy of the entry. If, after the deletion, the
entry still exists in LPA, the LpmeaEntryPointAddr, LpmeaLoadPointAddr,
and LpmeaModlen fields are provided, if available. If no entry still
exists in LPA, then a value of X'7FFFFFFF' is presented in
the LpmeaEntryPointAddr field, and the LpmeaLoadPointAddr and LpmeaModlen
fields do not contain valid data The exit routine must not modify
this area, as doing so would compromise the information provided to
subsequent exit routines called for the same event.
- Word 4
- Address of 512-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/exit.
- Word 5
- Address of 12-byte area that is the DDNAME (bytes 0-7) and DCB
(bytes 8-11) address used for the ADD request. The DDNAME will be
0s for the following cases:
- a DELETE request;
- an ADD request that specified BYADDR=YES; or
- an ADD request that specified DCB, DCBPTR, MASKDCB, or MASKDCBPTR.
The DCB address will be 0s for the following cases: - a DELETE request or
- an ADD request that specified BYADDR=YES.
The DDNAME and/or DCB address could be used to locate the name
of the data set from which the module was fetched, using field LpmeaSuccessConcatNum
to identify the number of the data set within the allocated concatenation. At
the time the exit routine is called, the DDNAME will still be allocated
and the DCB will still be open.
Registers at exit from CSVDYLPA routine. Upon
return from CSVDYLPA 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
Disassociating CSVDYLPA. Disassociate
the routines from CSVDYLPA when they should no longer receive control.
Use the CSVDYNEX macro to disassociate the routines. For example:
CSVDYNEX REQUEST=DELETE, X
EXITNAME=THEEXIT X
MODNAME=THEMOD
.
.
.
THEEXIT DC CL16'CSVDYLPA'
THEMOD DC CL8'DYLPARTN'
Coded example EXITRTN CSECT
EXITRTN AMODE 31
EXITRTN RMODE ANY
*
* entry linkage
*
STM R14,R12,12(R13)
LR R12,R15
USING EXITRTN,R12
*
* Processing
*
L R2,0(R1) Get address of function code
CLC 0(4,R2),FUNCDEL Is this DELETE?
BE DONE Yes, Done
L R2,4(R1) Get address of number of entries
ICM R2,15,0(R2) Get number of entries
BZ DONE No entries, done
L R3,8(R1) Address of module information area
USING LPMEA,R3 Establish using
TOP DS 0H TOP of loop
TM LPMEAOUTPUTFLAGS0,LPMEASUCCESS Is this entry valid?
BZ NEXT No, move on to next
CLC LPMEANAME,MYMODULE Is this my module?
BNE NEXT No, move on to next
*
* Put code here possibly to move field LpmeaEntryPointAddr to
* your own data area
*
NEXT DS 0H Continue loop
LA R3,LPMEA_LEN(R3) Point to next entry
DROP R3 Release using
BCT R2,TOP Decrement, see if done
DONE DS 0H
*
* exit linkage
*
LM R14,R12,12(R13)
SLR R15,R15
BR R14
MYMODULE DC CL8'MODULEA'
FUNCDEL DC A(CSVDYLPAFUNCTIONDELETE)
R1 EQU 1
R2 EQU 2
R3 EQU 3
R4 EQU 4
R12 EQU 12
R13 EQU 13
R14 EQU 14
R15 EQU 15
CSVLPRET
END