How To

Summary

This document describes the intent of the dynamic LNKLST facility, discusses the risks associated with the LNKLST UPDATE parameter, and provides examples of the use of dynamic LNKLST processing.

Steps

References

Information about dynamic LNKLST processing can be found in:

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 these risks.

These risks are documented in IBM z/OS publications where dynamic LNKLST parameters are described.

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.
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 issue STOP LLA 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.

In our example, LLA was stopped before making changes to MY.LNKLST.DATASET. If no system programmer action is being taken which requires removal of LLA's ENQ, then a STOP LLA before the dynamic LNKLST activity and a START LLA,SUB=MSTR after the dynamic LNKLST activity are not required. Instead, a MODIFY LLA,REFRESH command can be issued after the dynamic LNKLST activity is complete.

Document Location

Worldwide

[{"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG90","label":"z\/OS"},"Component":"Contents Supervisor;LLA;PDSE","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"All Versions","Edition":"","Line of Business":{"code":"LOB56","label":"Z HW"}}]

Tips

Using the dynamic LNKLST facility safely and properly