Managing dynamic LPA content

Use the SETPROG LPA command anytime after IPL to specify:

Modules to add to the LPA
Modules to delete from the LPA
The minimum amount of CSA storage that must remain available after an ADD operation.

You can also initiate a change to the LPA from a program via the CSVDYLPA macro, or by an operator using the SET PROG command. You can use the PROG system parameter to specify CSA threshold values, but not to request ADD or DELETE operations.

You can exercise certain controls over the modules to be loaded:

You specify a data set from which the system is to load the modules. You must be authorized to make the request.
You can request that the modules be placed into fixed common storage.
You can request that only the full pages within a load module be page-protected. This does leave the likelihood of the beginning and/or end of a load module not being page protected. By default, each module is individually page-protected. This is, however, wasteful of common storage, as each module needs then to occupy a whole number of 4096-byte pages. In all cases the module will be in key 0 storage.
You can specify that the module being replaced is the routine for a specific SVC. The system then updates the SVC table with the new entry point address.
You can specify that the system must process aliases of the specified modules even if the aliases are not explicitly specified.

The system considers LPA modules as coming from an authorized library. As part of its LPA search, the system will find modules that had been added dynamically. It will find a module that had been added dynamically before it finds one of the same name that had been added during IPL.

Use the SETPROG LPA command to replace modules only where the owning product verifies the replacement. Otherwise, replacement could result in partial updates. If the owning product has already saved the module address, the system will not conduct an LPA search and will not find the updated module. Also, the addresses of all modules that are accessed via a program call (PC) instruction are stored in the PC table. That table is not updated by the SETPROG LPA command. Therefore, these modules cannot be replaced using the SETPROG LPA command. You must IPL for the updates to take effect.

Note: If you specify the SVCNUMDEC keyword, dynamic LPA can update the SVC table. Specifying SVCNUMDEC can be used to replace an SVC routine. To add an SVC routine however, the user of the SETPROG LPA command, or the owner of the SVC, must write a program that gets control as the CSVDYLPA exit routine, looks for a given routine name, and then issues the appropriate SVCUPDTE service call to update the SVC table. For more information about the CSVDYLPA exit routine, see "Monitoring Dynamic LPA Processing" in z/OS MVS Programming: Authorized Assembler Services Guide.

It is sometimes necessary to re-IPL the system to replace LPA modules. For example, many service updates of LPA modules will require a re-IPL.

The complete syntax for the SETPROG LPA command is:

 
SETPROG LPA,{ADD,MODNAME=(modname...,modname) | MASK=mask}
                [,DSNAME=dsname | LNKLST]                
                [,PAGEABLE | FIXED] 
                [,PAGEPROTALL | PAGEPROTPAGE]
                [,SVCNUMDEC=svcnum | ,SVCNUMDEC=(svcnum,routcode)] 
                [,ADDALIAS | ,NOADDALIAS]                 
                                                         
            {DELETE,MODNAME=(modname...,modname)          }
                 FORCE=YES [CURRENT | OLDEST]             
                                                         
            {CSAMIN=(below,above)                         }

Note:

You may alternatively express the parameters associated with the keywords MASK, DSNAME, and FORCE in the preceding syntax diagram using parentheses rather than equals signs, as shown in the descriptions below.
This command requires a /* */ around comments. See System command formats for further information.

LPA

Statement type indicating that an action may be performed on the LPA.

ADD

Specifies that one or more modules be added to the LPA.

Default value: None

Attention: Modules added to the system by dynamic LPA processing are placed into CSA or ECSA storage. Therefore, it is important to ensure that the system CSA and ECSA sizes are adequately defined to handle the additional consumption of CSA storage resulting from the issuance of the dynamic LPA request. Further protection can be gained through the use of the CSAMIN parameter described below.

DELETE

Specifies that one or more modules be deleted from the LPA. Only modules added to the LPA after an IPL are eligible for dynamic deletion.

Default value: None

CSAMIN

Specifies the minimum amount of CSA and ECSA that must remain after a module is added to the LPA. If the requested ADD operation would reduce the CSA or ECSA below the defined minimum, the system rejects the operation.

Default value: (0,0)

below

The minimum amount of below-16M CSA storage that must remain after the ADD operation. The value can be expressed as n, nK, and nM.

above

The minimum amount of above-16M CSA storage that must remain after the ADD operation. The value can be expressed as n, nK, and nM.

MODNAME(modname,...,modname) | MODNAME=(modname,...,modname)

modname is the 1-8 character LPA module name or alias. If a modname has aliases, you must specify the module name and all of its aliases. If the last character of the modname is an asterisk (*), it will be treated as X'C0' — which lets you specify the name of a load module that ends with that non-printable character. You cannot use wildcard characters within modname. You can submit up to 128 module names, and you can use MOD or MODULE as synonyms of MODNAME.

Default value: None

MASK(mask) | MASK=mask

mask is the 1-8 character mask that is to be applied to all the members of the specified data set. It can contain wildcard characters * and ?, and all members that match will be processed.

Default value: None

DSNAME(dsname) | DSNAME=dsname

dsname is the 1-44 character data set name that contains the module(s) or alias(es). When MODNAME is specified, you can specify DSNAME(LNKLST) if you want the system to search the lnklst instead of a particular data set. The data set must be cataloged. It may be allocated as a PDS or PDSE program library.

The attribute of the CSA for each module is assigned as OWNER=SYSTEM. DSN, LIB, and LIBRARY can be used as synonyms of DSNAME.

Default value: None

PAGEABLE | FIXED

Indicates whether the modules are to be placed in pageable or fixed storage. PAGE can be used as a synonym for PAGEABLE.

Default value: PAGEABLE

PAGEPROTALL | PAGEPROTPAGE

Indicates whether or not to page protect entire modules. The default is to page protect the entire module (PAGEPROTALL). Be aware that when this default is taken, storage utilization for the modules increases because each module is allocated a number of whole pages (so that they can be page protected) rather than just the amount of storage that is necessary to load the module. PPALL and PPA can be used as synonyms for PAGEPROTALL.

When PAGEPROTPAGE is requested, only the whole pages within each load module are page protected, which minimizes storage use but also allows the possibility that a storage overlay of the beginning or end of the load module can occur. PPPAGE and PPP can be used as synonyms for PAGEPROTPAGE.

Default value: PAGEPROTALL

SVCNUMDEC=svcnum | SVCNUMDEC=(svcnum,routcode)

Identifies the entry to update within the SVC table. The SVC number, svcnum, must be in the range 0 - 255. For an extended SVC (109, 116, 122, 137), you must also specify routcode, which is the extended SVC routing code. The routing code must be within the range that is supported by the SVC. The routing code for SVC 109 must be in the range 0 - 255. The routing code for other extended SVCs depends on the z/OS® release. Use the SVCNUMDEC function to update already-defined SVC table entries. Do not use it to create new entries because you might not get all of the attributes that you need. SVCDEC can be used as a synonym for SVCNUMDEC.

Default value: This is not an SVC routine. The SVC table is not updated.

ADDALIAS | NOADDALIAS

ADDALIAS (or ALIAS) indicates to process provided names and aliases of the provided names. NOADDALIAS (or NOALIAS) indicates to process only the names provided. You can use NOADDALIAS to override the default values set by DEFAULTS LPA ADDALIAS.

Default value: NOADDALIAS, or the value set by DEFAULTS LPA ADDALIAS | NOADDALIAS.

FORCE(YES) | FORCE=YES

Confirms that the delete requestor understands the ramifications of deleting a module from the LPA, when the system can have no knowledge of whether any code is currently executing within the specified module.

Default value: None. This is a required parameter.

CURRENT | OLDEST

CURRENT specifies to delete the current copy. OLDEST specifies to delete the oldest dynamic copy. You can use CUR as a synonym of CURRENT, and OLD as a synonym of OLDEST.

Default value: CURRENT