(TSO) ALTLIB = (ISPF) LIBDEF

Back on Novenber 2, I did a short introduction to ALTLIB, the TSO command that allows you to insert one or more datasets into a preferential position so that (in that case) REXX routines could be found for execution.  ISPF has an equivalent command that, if you write ISPF dialogs, and especially if you write them in REXX, can come in very handy.  Let's quickly review how ALTLIB works:

"ALTLIB   ACT APPLICATION(EXEC)  DA('........') "
if rc > 4 then do
   say "ALTLIB failed, RC="rc
   exit
   end

.... call one or more routines stored there ....

"ALTLIB DEACT APPLICATION(EXEC)"

This obviously takes place in 'address TSO'.  ALTLIB ACT names a dataset to be searched ahead of the normal search order for (in this case) SYSEXEC.  A non-zero return code indicates the ALTLIB didn't happen, and the process ends with either an 'exit' or a 'return'.  If the ALTLIB happened, the process can use the code stored there, and when the task is complete, an ALTLIB DEACT undoes the work of the earlier ALTLIB ACT.

ISPF has an almost-exactly-equal process called LIBDEF.

   "LIBDEF  ISPTLIB  DATASET  ID("isptlib")  STACK"
 .... use the contents of the ISPTLIB ....
   "LIBDEF  ISPTLIB"

This operation must take place in 'address ISPEXEC'.  The LIBDEF parms are (1) the DDName to be altered, (2) 'DATASET' or 'LIBRARY', and (3) the identity of that dataset or library.  There are other parameters which can be passed including, as shown here, 'STACK'.  Note that when using 'LIBRARY' the ID-portion is the DDName under which the library or libraries have been allocated;  that implies a prior ALLOC for those assets.  When using 'DATASET', no prior ALLOC need have been done.  Programmers who complain that some ISPF asset is tied up and can't be released are often referring to a 'LIBDEF ... LIBRARY' which has gotten tangled somehow.  Avoid entanglements;  use 'LIBDEF ... DATASET'.

When the asset is no longer needed, it is good practice (you should consider that required) to release the LIBDEF by specifying the active DDName alone (as shown).

Between the two LIBDEF operations, the asset is as much a part of the active DDName as if it had been part of the original DD during LOGON processing, and this is true whether the active DDName is ISPPLIB, ISPTLIB, ISPTABL, ISPMLIB, ISPSLIB, or any other.  Every ISPEXEC command will search the appropriate ISPxLIB allocations in reverse order, original allocations last, until it finds the asset it's looking for.

Now...  STACK.  If the original LIBDEF did not specify STACK, the following LIBDEF, the undoing LIBDEF, not only releases this LIBDEF, but all prior LIBDEFs whether done with STACK or not.  In other words, if process "A" LIBDEFs an ISPTLIB into place and then calls process "B" which LIBDEFs a further ISPTLIB into place before calling process "C" which LIBDEFs a third ISPTLIB into place, it is possible for process "C" to eliminate all three LIBDEFs before processes "A" and "B" can use them.  Processes "A" and "B" will likely fail because the proper asset is not present, although something worse could happen: they might find their data in the wrong asset libraries and use those, thus appearing to have operated correctly when, in fact, they did not.