References

 Information about dynamic LNKLST processing can be found in:

• z/OS MVS Initialization and Tuning Reference  (PROGxx)
• z/OS MVS System Commands (SETPROG)
• MVS Programming: Authorized Assembler Services Guide (Changing the LNKLST Concatenation)

Background

Dynamic LNKLST processing was introduced in the 1990's as a vehicle for allowing the dynamic addition of a new product that required new data sets in the LNKLST.  Dynamic LNKLST processing provides the capability to define a new LNKLST concatenation (referred to as a "LNKLST set") and to activate that LNKLST set such that it becomes the "current" LNKLST set on the system.  As the current LNKLST set, any newly starting jobs use that LNKLST set; jobs that existed before the dynamic activation of this new current LNKLST set are unaffected.  A LNKLST set that is in use by at least one job is said to be "active".  

Simple Example

Following is an example of a simple application of dynamic LNKLST processing that uses the SETPROG system command:

SETPROG LNKLST,DEFINE,NAME=MYLNKLST,COPYFROM=CURRENT
SETPROG LNKLST,ADD,NAME=MYLNKLST,DSN=MY.NEW.DATASET
SETPROG LNKLST,ACTIVATE,NAME=MYLNKLST

• The first SETPROG LNKLST statement defines the name of a new LNKLST set, MYLNKLST, and indicates that this new LNKLST set's data set concatenation is identical to that of the current LNKLST.  This statement only defines a new LNKLST set.  It does not activate that LNKLST set.
• The second SETPROG LNKLST statement adds a data set, MY.NEW.DATASET, to the data set concatenation in the new LNKLST set, MYLNKLST. 
• The third SETPROG LNKLST statement activates the new LNKLST set, MYLNKLST, making it the new current LNKLST.  Any new jobs started on the system will use LNKLST set MYLNKLST.  All jobs active on the system before the activation of LNKLST set MYLNKLST remain unaffected. 

Use of system ENQ by Dynamic LNKLST processing

Dynamic LNKLST processing does an allocation for each LNKLST data set, resulting in a SYSDSN (data set) ENQ on each data set.  (These ENQs are maintained from the XCFAS address space.)  The ENQ has the benefit of preventing modification to a data set in an active LNKLST set, providing the data set was allocated with attribute DISP=OLD.  This protection is important since modification of a LNKLST data set carries risk and should be avoided.  However, the ENQ has the side effect of preventing normal system maintenance activity from occurring on an uncataloged data set with the same data set name but residing on a different volume.  For this reason, dynamic LNKLST processing provides the UNALLOCATE parameter to give the ability to temporarily remove the ENQs and the ALLOCATE parameter to reinstate the ENQs.  For example:

SETPROG LNKLST,UNALLOCATE
[Perform activities on identically named, uncataloged, non-LNKLST data sets on other volumes.]
SETPROG LNKLST,ALLOCATE   

For more information about ENQs on LNKLST data sets, see the section on Using the LNKLST statement in the z/OS MVS Initialization and Tuning Reference. 

Risk in manipulating the LNKLST

The capability to UNALLOCATE the LNKLST set for the purposes described is sometimes misused by those looking to perform activity against an active, dynamically defined LNKLST set, an action that carries risk.  IBM strongly advises against using the UNALLOCATE parameter for this purpose.

For emergency purposes only, dynamic LNKLST processing provides an UPDATE,JOB= parameter, which causes the specified job to switch from the LNKLST set that it has been using to the current LNKLST set.  It is possible to specify UPDATE,JOB=* to indicate that all jobs on the system be switched.  It is critical to understand that any such "in-flight" change to a job's LNKLST set carries with it an inherent and unpreventable risk.  The jobs whose LNKLST sets are being changed could suffer serious fetch errors as a result of the change.  Such errors could result in a need to re-IPL.  Do not use the UPDATE parameter unless you are willing to accept this risk.

This risk is documented in IBM z/OS publications where dynamic LNKLST parameters are described.  You may also want to consider including the DELAY parameter on the LNKLST UPDATE statement to potentially reduce (but not eliminate) the risk.

Changing a job's LNKLST set

Customers operating in a test environment might find themselves in a position where they need to use the dynamic LNKLST UPDATE capability and are willing to assume the risk.  Following are appropriate steps for making such a change for a single job, MYJOB:

SETPROG LNKLST,DEFINE,NAME=MYLNKLST,COPYFROM=CURRENT
SETPROG LNKLST,ADD,NAME=MYLNKLST,DSN=MY.NEW.DATASET
SETPROG LNKLST,ACTIVATE,NAME=MYLNKLST
SETPROG LNKLST,UPDATE,JOB=MYJOB
 
Following are the steps for making such a change to all jobs on the system:
 
SETPROG LNKLST,DEFINE,NAME=MYLNKLST,COPYFROM=CURRENT
SETPROG LNKLST,ADD,NAME=MYLNKLST,DSN=MY.NEW.DATASET
SETPROG LNKLST,ACTIVATE,NAME=MYLNKLST
SETPROG LNKLST,UPDATE,JOB=*
 
Even when willing to assume the documented risks, it is important to understand what is acceptable practice and what is not acceptable when it comes to managing the LNKLST dynamically.  There is sometimes a need on test systems to swap a LNKLST data set, replacing an older version of a LNKLST data set with a newer one of the same name.  Following is an example of how NOT to do such a data set swap:  
 
SETPROG LNKLST,UNALLOCATE
STOP LLA
Rename MY.LNKLST.DATASET            to   MY.LNKLST.DATASET.OLD
Rename MY.LNKLST.DATASET.NEW  to   MY.LNKLST.DATASET
SETPROG LNKLST,ALLOCATE     
START LLA,SUB=MSTR    

 
As a result of this command sequence, the following actions occurred:
 

• The current LNKLST set was unallocated in order to remove its ENQ against LNKLST data set MY.LNKLST.DATASET.
• The MVS™ Library Lookaside facility (LLA), which by default maintains a cache of directory information for LNKLST data sets, was stopped in order to remove its ENQ against LNKLST data set MY.LNKLST.DATASET.   (Note that a “selective refresh” can be done instead of stopping all of LLA.  This option will be discussed later under the section entitled “Is a STOP and START of LLA really necessary?”)
• Once the data set ENQs were removed, the user was able to rename data sets, effectively swapping out the old for the new. 
• Once this activity was complete, the LNKLST,ALLOCATE command reinstated the LNKLST ENQ on data set MY.LNKLST.DATASET, and LLA was restarted to reinstate its ENQ. 

Unfortunately, after these actions were taken, errors such as ABEND106 and ABEND0F4 occurred in module fetch processing.  These errors occurred because the LLA view of the LNKLST concatenation no longer matched the LNKLST view.  To understand why this was the case, consider what processing occurred as a result of the sequence of actions. 
 

• First note that, when a LNKLST set is activated, the "LNKLST view" is captured in that LNKLST's DEB.  For each data set in the LNKLST set, the DEB indicates the volume on which that data set lives, and its location on that volume. 
• None of the listed actions results in a change to the LNKLST DEB.  In particular, the renaming of the data set causes no update to the LNKLST DEB.  Therefore, after all of these actions take place, the LNKLST DEB still indicates the volume and position on the volume of the old MY.LNKLST.DATASET. 
• In contrast, the START LLA command causes LLA to rebuild its cache of directory entries for the data sets in the LNKLST set.  When LLA initialization processes data set MY.LNKLST.DATASET, LLA uses the current directory entry for that data set.  This entry points to the new MY.LNKLST.DATASET. 
• As a result of the command sequence, LNKLST processing and LLA processing become out of step.  LNKLST processing is using the old MY.LNKLST.DATASET, while LLA is using the new MY.LNKLST.DATASET.  

 
The way to correctly make a LNKLST data set swap is to use dynamic LNKLST commands.  Doing so notifies LNKLST processing that changes are being made and that LNKLST control blocks need to be updated.  The following three-step sequence of commands accomplishes this, although it requires use of the LNKLST UPDATE,JOB= parameter.  All previously documented risks still apply.

1) Remove a data set from the current LNKLST:

STOP LLA
SETPROG LNKLST,DEFINE,NAME=LNKLST2,COPYFROM=CURRENT
SETPROG LNKLST,DELETE,NAME=LNKLST2,DSNAME=MY.LNKLST.DATASET
SETPROG LNKLST,ACTIVATE,NAME=LNKLST2
SETPROG LNKLST,UPDATE,JOB=* 

2) Perform action against the removed data set.  In order to perform this action, you will need to ensure that the LLA ENQ and the dynamic LNKLST ENQ on the data set have been removed. If you have performed the commands in Step 1, both the LLA ENQ and LNKLST ENQ should already be removed.  To display ENQ status on a data set, issue: D GRS,RES=(SYSDSN,datasetname).
 

Removing a dynamic LNKLST ENQ

• If the data set is no longer in any active LNKLST, which would be the case after doing a SETPROG LNKLST,UPDATE,JOB=* command as described in Step 1, then dynamic LNKLST processing will no longer hold the XCFAS ENQ on this data set.   
• If the data set is still in at least one active LNKLST, which could be the case if you did not specify SETPROG LNKLST,UPDATE,JOB=*, you will find that the XCFAS ENQ is still held for this data set.  You should identify which active LNKLST is still using the data set, and then use additional dynamic LNKLST commands similar to those described in Step 1 to address this.  Never use the SETPROG LNKLST,UNALLOCATE command to bypass dynamic LNKLST protection of a data set in an active LNKLST.  

Removing the LLA ENQ
If the data set in question is still being managed by LLA, as part of either an active or inactive LNKLST, LLA will have an ENQ on the data set.  Issuing MODIFY LLA,REFRESH is not sufficient to remove LLA's ENQ on the removed data set.  Instead, you must either stop LLA or use LLA’s selective refresh capability (described later) to remove the LLA ENQ on the data set.  In our example, STOP LLA was issued at the beginning of Step 1 prior to the dynamic LNKLST changes, but alternatively you can STOP LLA during Step 2.

Reinstating the LLA ENQ

Once activity against the data set is complete, proceed to Step 3.  At the end of Step 3, a START LLA,SUB=MSTR is performed, which will reinstate the LLA ENQ.

3) Add the data set back to the current LNKLST

SETPROG LNKLST,DEFINE,NAME=LNKLST3,COPYFROM=CURRENT  
SETPROG LNKLST,ADD,NAME=LNKLST3,DSNAME=MY.LNKLST.DATASET
SETPROG LNKLST,ACTIVATE,NAME=LNKLST3
SETPROG LNKLST,UPDATE,JOB=*
START LLA,SUB=MSTR

To summarize, after the commands in Step 1 are complete, all jobs on the system will be using LNKLST set LNKLST2, which is identical to the previous current LNKLST set except that data set MY.LNKLST.DATASET is now removed.  LLA was stopped in order to remove the LLA ENQ on MY.LNKLST.DATASET in anticipation of the changes to be made in Step 2.

Once actions against the data set are complete, the commands in Step 3 can be used to add the data set back to the current LNKLST.  Following completion of Step 3, all jobs on the system are using LNKLST set LNKLST3, which contains the new version of MY.LNKLST.DATASET.  A START LLA,SUB=MSTR is done once the dynamic LNKLST changes are complete.  
 

Is a STOP and START of LLA really necessary?

If you are comfortable using LLA’s “selective refresh” capability (MODIFY LLA,UPDATE=xx) to manage individual data sets that LLA is managing, this is an alternative to stopping and starting LLA that will offer some performance advantage.  

In our example, LLA was stopped before making changes to MY.LNKLST.DATASET.  The subsequent START of LLA results in a new OPEN being done against MY.LNKLST.DATASET.  This OPEN causes a new DEB to be built, ensuring that LLA is using current data set information, consistent with that being used by the LNKLST.  Performing a STOP and START of LLA is the simplest and safest option.  For an occasional short STOP of LLA, most customers do not experience performance concerns;  however, there is an alternative method that avoids the STOP and START of LLA. 

When manipulating LLA-managed data sets, ensuring LLA is working with the correct DEB is critical.   LLA performs an OPEN anytime it begins managing a new data set.  LLA does NOT do an OPEN if it is simply performing an update to a data set that it is already managing.  The following LLA commands result in an OPEN and thus a newly initialized DEB:

START LLA,SUB=MSTR
F LLA,UPDATE=xx          where the LIBRARY(s) indicated in CSVLLAxx is not presently being managed by LLA

The following LLA commands do NOT result in an OPEN and so do not create a new DEB for the LLA-managed data set:

F LLA,REFRESH
F LLA,UPDATE=xx     where the LIBRARY(s) indicated in CSVLLAxx is presently being managed by LLA

For those comfortable with using F LLA,UPDATE=xx to REMOVE a data set from LLA and to re-add a data set to LLA, the following is an alternative approach that does not require a STOP and START of LLA:

1. F LLA,UPDATE=xx   to remove the desired data set from LLA management
2. Make the desired dynamic LNKLST changes
3. F LLA,UPDATE=yy  to add back the desired dataset to LLA management

where LLA parmlib member CSVLLAxx contains a REMOVE statement such as:

REMOVE(MY.LNKLST.DATASET)

and LLA parmlib member CSVLLAyy contains a statement such as:

LIBRARIES(MY.LNKLST.DATASET)

Note that a REMOVE of a LNKLST data set from LLA management can lead to detectable performance impact for the duration of time that the data set is removed.  Re-establishing LLA’s management of the LNKLST data set will restore full performance benefit. 

Conclusion

Never rename (especially for the purpose of swapping), recatalog, delete, move, or compress a data set that is part of an active LNKLST.  Prior to taking any such action, you should:

1. Remove the data set from LLA management.  This can be done by issuing STOP  LLA, or by issuing a MODIFY LLA,UPDATE=xx command (known as a “selective refresh”) to select a CSVLLAxx member that lists the library on the REMOVE keyword.
2. Use Dynamic LNKLST commands as described previously to remove the data set from all active LNKLSTs.

Once these actions have been taken, you can perform the desired change activity against the data set.  After completing the necessary activity, add the data set back to the LNKLST:

1. Use Dynamic LNKLST commands as described previously to activate a LNKLST with that data set included.
2. Indicate to LLA to resume managing the data set.  This can be done by issuing:
   
       START LLA,SUB=MSTR
   
   if LLA had been stopped.  Alternatively, if the data set had been removed from LLA management via a selective refresh, it can be added back by issuing a MODIFY LLA,UPDATE=xx command to select a CSVLLAxx member that lists the library on the LIBRARIES statement.  

Even when following the steps in this document, use of the SETPROG LNKLST,UPDATE,JOB= command or its SET PROG= equivalent carries inherent risk that can impact the entire system.  Use of this LNKLST UPDATE capability in production environments should be avoided if at all possible.