Overview
Corrections applied to step 4 under Implement User-Wide level on TK5 section.
Installation of third-party and/or in-house (home-grown) software is ‘normal business’ in computing platforms, regardless of technology stacks. Additionally, safekeeping of user software and/or customization after an OS upgrade is paramount. However, keeping this impact to ‘zero’ is nearly impossible!
Therefore, some form of exception is necessary by implementing system reinstatement task(s) to be executed after an OS upgrade is applied.
More specifically, reinstallation of user installed software should not be necessary, unless the OS upgrade calls for recompilation (e.g. remember the 24 to 32 bit days!!!???).
Purpose
The primary objective is to isolate and preserve any user installed software on a TK5 system (software not supplied by TK5 proper) by installing user software away from TK5 distribution volumes while accessing user installed software via augmented system library concatenation definitions.
Of course, without question, as with any OS upgrade, some minimal but expedient customization tasks must be performed (e.g. change of time zone in SYS1.PARMLIB(PARMTZ)) post-TK5 update.
The content of this post is based on the current TK5 distribution, update 3, dated 2024-04-04.
The approach presented in this post is implemented on my personal TK5 demo system. And, excited to share with the MVS 3.8J community.
I am certain more than one approach exists! Too many smart-minds in this community to only have one solution!
I hope you find this post helpful.
TK5 Distributions
TK5 update 3 specifies that only four volumes are distributed for release updates, containing TK5 OS and other supplied functionality (e.g. TSO commands and/or ISPF applications), thus, leaving other volumes untouched. The documented distribution volumes are shown below:
TK5RES - 3390, MVS sysres volume. TK5DLB - 3390, MVS distribution libraries. TK5001 - 3390, package volume 1. Contains user catalog SYS1.UCAT.TK5. TK5002 - 3390, package volume 2.
Therefore, one can easily infer or conclude –
Do NOT use the above listed volumes for any user installed software to prevent loss of such software!
Conversely, one can also conclude –
Use other non-system (e.g. JES2 SPOOL) volumes for user installed software to prevent loss of user installed software!
Sounds great!
Let’s explore specifics about TK5 library concatenations of interest and solutions for installing and preserving user installed software on TK5.
User software installation is limited to ISPF, TSO, BREXX and batch applications for the discussion purposes in this post.
More information on MVS 3.8J TK5 system including user guide at:
https://www.prince-webdesign.nl/tk5
ISPF Library Concatenation
System product libraries (from Wally Mclaughlin’s ISPF-like product), listed below, reside on volume TK5001 (one of the TK5 update distribution volumes):ISP.V2R2M0.CLIB ISP.V2R2M0.LLIB ISP.V2R2M0.MLIB ISP.V2R2M0.PLIB ISP.V2R2M0.SLIB ISP.V2R2M0.TLIBTK5-specific libraries, listed below, reside on volume TK5001 (one of the TK5 update distribution volumes):
SYS2.ISP.CLIB SYS2.ISP.LLIB SYS2.ISP.MLIB SYS2.ISP.PLIB SYS2.ISP.SLIB SYS2.ISP.TLIBUser-specific libraries typically reside on TSOxxx volumes (away from TK5 distribution updates) with naming convention of:
userid.ISP.CLIB userid.ISP.LLIB userid.ISP.MLIB userid.ISP.PLIB userid.ISP.SLIB userid.ISP.TLIBOut of the box, TK5 provides up to three ISPF library concatenation levels-
1. -- user-specific level (if data set exists)
2. -- TK5 software level
3. -- system software level
Note: TK5 automatically appends userid.ISPFLIB libraries, if defined, accordingly, for DDs ISPCLIB, ISPLLIB, ISPMLIB, ISPPLIB, ISPSLIB, and ISPTLIB. and ISPTABL.
nnn DDNAME S DSNAME 001 ISPCLIB _ SYS2.ISP.CLIB _ ISP.V2R2M0.CLIB 002 ISPLLIB _ SYS2.ISP.LLIB 003 ISPMLIB _ SYS2.ISP.MLIB <-- TK5 software level _ ISP.V2R2M0.MLIB <-- system software level 004 ISPSLIB _ SYS2.ISP.SLIB _ ISP.V2R2M0.SLIB 005 ISPTABL _ SYS2.ISP.TLIB 006 ISPTLIB _ SYS2.ISP.TLIB _ ISP.V2R2M0.TLIB 007 ISPPLIB _ HERC01.ISP.PLIB <-- user-specific level _ SYS2.ISP.PLIB <-- TK5 software level _ ISP.V2R2M0.PLIB <-- system software level _ SYS2.REVIEW.PLIB <-- system software level
In the above, HERC01.ISP.PLIB (contains user-specific panels) is automatically concatenated (due to existence) as depicted by item #7. However, no user-specific level is applied to DD ISPMLIB (item #3).
User HERC01 can install ISPF applications and preserve those components from overlay when a new TK5 update distribution is applied. This is great!
However, user HERC02 cannot use HERC01 application(s), if meant to be shared.
A potential solution is to add a new concatenation level, user-wide level, to facilitates a search order of up to four levels allowing application access across all ISPF users as shown below-1. -- user-specific level
2. -- user-wide level
3. -- TK5 software level
4. -- system software level
Some ISPF software may install components to other data sets such as SYS2.CMDPROC, SYS2.CMDLIB and/or SYS2.HELP, which will be overlaid by a TK5 distribution update. Therefore, a new user-wide access level is necessary.
TSO Library Concatenation
Typically, three library types are utilized by TSO native applications using secondary node names of CMDPROC, CMDLIB and HELP. CMDPROC libraries store TSO PROCs (procedures, CLISTS), CMDLIB libraries store load members for TSO executable software and HELP libraries store HELP members.
These libraries reside on volume TK5RES (one of the TK5 update distribution volumes):
DSN----------------------------------------- VOLUME
SYS1.CMDLIB TK5RES
SYS1.CMDPROC TK5RES
SYS2.CMDLIB TK5RES
SYS2.CMDPROC TK5RES
SYS1.HELP TK5RES
SYS2.HELP TK5RES
Each library type is discussed separately.
TSO CMDPROC (DD SYSPROC)
System libraries (used for system and TK5 software) typically reside on volume TK5RES volumes (one of the TK5 update distribution volumes):SYS1.CMDPROC SYS2.CMDPROCUser-specific libraries typically reside on TSOxxx volumes (away from TK5 distribution updates):
userid.CMDPROC
Out of the box, TK5 provides up to two TSO CMDPROC library concatenation levels-
1. -- user-specific level
2. -- TK5/system software level
Note: TK5 automatically appends userid.CMDPROC libraries, if defined, accordingly, for DD SYSPROC.
Therefore, the resulting TSO SYSPROC concatenation order for TK5 base system user session could be:nnn DDNAME S DSNAME 001 SYSPROC _ HERC01.CMDPROC <-- user-specific level _ SYS1.CMDPROC <-- TK5/system software level _ SYS2.CMDPROC <-- TK5/system software level
TSO CMDLIB (LINKLIST)
The TSO CMDLIB libraries are part of the IPL LINKLIST (similar to the PATH statement in Windows) static definition for MVS 3.8J global use and declared in SYS1.PARMLIB as shown below:
Out of the box, TK5 declares the following system-wide library concatenation (library search order)-SYS1.PARMLIB(LNKLST00)
000001 SYS1.LINKLIB,
000002 SYS1.PPLIB,
000003 SYS1.CMDLIB,
000004 SYS2.CMDLIB,
000005 NJE38.AUTHLIB(TK5001),
000006 SYS2.LINKLIB,
000007 SYS1.PL1LIB,
000008 SYS1.FORTLIB,
000009 SYS2.DSSLIB
No user-specific or user-wide access level is supported (purposely, in my opinion) by TK5 unless user (e.g. HERC01) installs a new TSO application using SYS2 libraries risking loss of software after a distribution update.
Understandably, the LINKLIST is a vital part of MVS 3.8J configuration and IPL definitions which could render an OS non-operational (cannot complete an IPL) due to missing or ill-defined data sets!!!
Given this ‘warning’ statement, this avenue must be traversed carefully and with no possibility of error!!
A potential solution set is to support user-wide libraries (similar to SYS2.LINKLIB and SYS2.CMDLIB datasets) as follows:
User-wide libraries typically reside on TSOxxx volumes (away from TK5 distribution updates):USER.LINKLIB USER.CMDLIBA potential solution is to add a new concatenation level in the LINKLIST, user-wide level, to augment the search order as shown below-
SYS1.PARMLIB(LNKLST00) 000001 SYS1.LINKLIB, 000002 SYS1.PPLIB, 000003 SYS1.CMDLIB, 000004 SYS2.CMDLIB, 000005 NJE38.AUTHLIB(TK5001), 000006 SYS2.LINKLIB, 000007 SYS1.PL1LIB, 000008 SYS1.FORTLIB, 000009 SYS2.DSSLIB, USER.LINKLIB, -- user-wide level USER.CMDLIB -- user-wide levelallowing for user installed applications and preservation of user installed software!
TSO HELP (DD SYSHELP)
System libraries (used for system and TK5 software)typically reside on volume TK5RES volumes (one of the TK5 update distribution volumes):SYS1.HELP SYS2.HELP
Note: TK5 does not support user-specific HELP libraries.
Out of the box, TK5 provides only one TSO HELP library concatenation level-1. -- TK5/system software level
Therefore, the resulting TSO SYSHELP concatenation order in theTK5 base system for a user session is:
nnn DDNAME S DSNAME 001 SYSPROC _ SYS1.CMDPROC <-- TK5/system software level _ SYS2.CMDPROC <-- TK5/system software level
A potential solution set is to support user-specific libraries and a new concatenation level, user-wide level as follows:
User-specific libraries typically reside on TSOxxx volumes (away from TK5 distribution updates):userid.HELP
New concatenation level, user-wide level, to facilitates a search order of up to three levels as shown below-
1. -- user-specific level 2. -- user-wide level 3. -- TK5/system software levelallowing for application access across all TSO/ISPF users and preservation of user installed software!
BREXX Library Concatenation
Some software may install components using BREXX scripts. BREXX is a supported component under TK5 using a sample script library and user-specific library. User-specific libraries provide user isolation and prevent overlays by a TK5 distribution update. Therefore, a new user-wide level BREXX library is necessary for shared scripts.
BREXX uses four DDs to resolve BREXX scripts, SYSUEXEC, SYSUPROC, SYSEXEC, and SYSPROC.
SYSUEXEC specifies a user-specific scripts library and SYSEXEC specifies non-user-specific scripts libraries.
For this post, only SYSEXEC is discussed for user-wide access.
User-specific libraries typically reside on TSOxxx volumes (away from TK5 distribution updates):userid.EXEC
Out of the box, TK5 provides for up to two library concatenation levels-
1. -- user-specific level
2. -- BREXX system software level (samples)
Note: TK5 automatically appends userid.EXEC libraries, if defined, accordingly, includes DDs SYSUEXEC and SYSEXEC.
Therefore, the resulting BREXX SYSEXEC concatenation orders in TK5 base system user session could be:nnn DDNAME S DSNAME 001 SYSEXEC _ HERC01.EXEC <-- user-specific level _ SYS2.EXEC <-- TK5/system software level _ BREXX.V2R5M3.SAMPLES <-- TK5/system software level
HERC01.EXEC (contains user-specific BREXX scripts) is automatically concatenated (due to existence) as depicted above by item #1.
User HERC01 can install BREXX scripts and preserve those components from overlay when a new TK5 update distribution is applied. This is great!
However, user HERC02 cannot use HERC01 script(s), if meant to be shared.
A potential solution is to add a new concatenation level, user-wide level, to facilitates a search order as shown below-1. -- user-specific level
2. -- user-wide level
3. -- TK5/system software level
allowing for shared BREXX script access by all TSO/ISPF users!
Batch Library Concatenation
Simple! Stay clear of volumes used for distribution updates.
LOAD libraries for batch applications can use any PDS library names defined on volumes not used by TK5 distribution update volumes.
Typically, batch applications use a STEPLIB for program resolution at execution time as depicted below:
.
.
//* -------------------------------------------------------*
//* * Batch Application Sample JCL Step *
//* -------------------------------------------------------*
//STEP001 EXEC PGM=BATCHPGM
//STEPLIB DD DSN=USER.LOADLIB,DISP=SHR
//SYSPRINT DD SYSOUT=*
.
.
Implement User-Wide level on TK5
1) Using IDCAMS, declare new ALIAS (e.g. USER, UWIDE, USERW, etc.) on user catalog SYS1.UCAT.TK5. Below is JCL using the USER HLQ:
//USERALS0 JOB (SYS),'DEF USER ALIAS', <-- REVIEW AND MODIFY
// CLASS=A,MSGCLASS=X, <-- REVIEW AND MODIFY
// MSGLEVEL=(1,1),NOTIFY=&SYSUID <-- REVIEW AND MODIFY
//DEFALIAS EXEC PGM=IDCAMS
//SYSPRINT DD SYSOUT=*
//SYSIN DD *
PARM GRAPHICS(CHAIN(SN))
LISTCAT ALIAS ENT(USER)
/* REVIEW AND MODIFY CATALOG NAME BELOW */
IF LASTCC NE 0 THEN -
DEFINE ALIAS(NAME(USER) RELATE(SYS1.UCAT.TSO))
/*
//
2) Define each PDS on a volume away from TK5 distribution update volumes with attributes as listed below (all datasets below are defined on a 3390 volume- TSO003):
DSN----------------------------------------- VOLUME DSO RFM LRECL BLKSZ
USER.ISP.CLIB TSO003 PO FB 80 3120
USER.ISP.LLIB TSO003 PO U 0 19069
USER.ISP.MLIB TSO003 PO FB 80 3120
USER.ISP.PLIB TSO003 PO FB 80 3120
USER.ISP.SLIB TSO003 PO FB 80 3120
USER.ISP.TLIB TSO003 PO FB 80 3120
USER.CMDLIB TSO003 PO U 0 32760
USER.CMDPROC TSO003 PO FB 80 27920
USER.HELP TSO003 PO FB 80 27920
USER.LINKLIB TSO003 PO U 0 32760
USER.EXEC TSO003 PO VB 255 15050
USER.LOAD TSO003 PO U 0 32760
3) Review and ensure all PDS data sets exist with the correct attributes.
4) Augment LOGON procedure (SYS1.CMDPROC(ISPLOGON)) for user-wide concatenation automation. Add lines 23-34 before existing RX $CONTCAT commands (line 35) as depicted in the below snippet:
SYS1.CMDPROC(ISPLOGON) 000001 /******************************************************************/ 000002 /* */ 000003 /* NAME: SYS1.CMDPROC(ISPLOGON) */ 000004 /* */ 000005 /* DESC: ALLOCATE USER DATASETS TO TSO ADDRESS SPACE */ 000006 /* THIS USES THE $CONCAT REXX EXEC WHICH TAKES 3 PARMS */ 000007 /* */ 000008 /******************************************************************/ 000009 PROC 0 000010 CONTROL NOMSG,NOLIST,NOSYMLIST,NOCONLIST,NOFLUSH 000011 /*----------------------------------------------------------------*/ 000012 /* IN ORDER TO RUN THE $CONCAT EXEC WE NEED THE RXLIB */ 000013 /* WHICH WILL BE ALLOCATE FIRST - IF IT EXISTS */ 000014 /*----------------------------------------------------------------*/ 000015 IF &SYSDSN('BREXX.V2R5M3.RXLIB') = OK THEN + 000016 DO 000017 FREE FILE(RXLIB) 000018 ALLOC FILE(RXLIB) DSN('BREXX.V2R5M3.RXLIB') SHR 000019 /*----------------------------------------------------------*/ 000020 /* The dataset names to be concatenated need to be */ 000021 /* given as unquoted fully qualified names */ 000022 /*----------------------------------------------------------*/ 000023 RX $CONCAT ISPPLIB USER.ISP.PLIB 000024 RX $CONCAT ISPCLIB USER.ISP.CLIB 000025 RX $CONCAT ISPLLIB USER.ISP.LLIB 000026 RX $CONCAT ISPMLIB USER.ISP.MLIB 000027 RX $CONCAT ISPSLIB USER.ISP.SLIB 000028 RX $CONCAT ISPTABL USER.ISP.TLIB000029 RX $CONCAT ISPTLIB USER.ISP.TLIB<-- correction: line deleted 000030 RX $CONCAT SYSEXEC USER.EXEC 000031 RX $CONCAT SYSPROC USER.CMDPROC 000032 RX $CONCAT SYSHELP USER.HELP 000033 RX $CONCAT SYSHELP &SYSUID..HELP <-- correction: line added 000034 000035 RX $CONCAT ISPPLIB &SYSUID..ISP.PLIB 000036 RX $CONCAT ISPCLIB &SYSUID..ISP.CLIB 000037 RX $CONCAT ISPLLIB &SYSUID..ISP.LLIB 000038 RX $CONCAT ISPMLIB &SYSUID..ISP.MLIB 000039 RX $CONCAT ISPSLIB &SYSUID..ISP.SLIB000040 RX $CONCAT ISPTABL &SYSUID..ISP.TLIB<-- correction: line deleted 000041 RX $CONCAT ISPTLIB &SYSUID..ISP.TLIB . . .
Note: This modification task is to be manually performed after a TK5 distribution update is applied to your TK5 installation. Add to your existing distribution upgrade task list.
5) Logoff TSO/ISPF and wait for TSO READY prompt.
6) Sign on to TSO/ISPF using RELOGON command
7) From the ISPF main menu, type =3.7.DD and press ENTER
8) Verify new user-level access. Below is a representative snippet for comparison purpose:
nnn DDNAME S DSNAME 001 STEPLIB _ ISP.V2R2M0.LLIB 002 ISPTRACE _ Terminal 003 SYS00002 _ SYS1.UCAT.TK5 004 RXLIB _ BREXX.V2R5M3.RXLIB 005 SYS00003 _ SYS1.UCAT.TSO 006 ISPCLIB _ USER.ISP.CLIB _ SYS2.ISP.CLIB _ ISP.V2R2M0.CLIB 007 ISPLLIB _ USER.ISP.LLIB _ SYS2.ISP.LLIB 008 ISPMLIB _ USER.ISP.MLIB _ SYS2.ISP.MLIB _ ISP.V2R2M0.MLIB 009 ISPSLIB _ USER.ISP.SLIB _ SYS2.ISP.SLIB _ ISP.V2R2M0.SLIB 010 ISPTABL _ USER.ISP.TLIB _ SYS2.ISP.TLIB 011 ISPTLIB _ USER.ISP.TLIB _ SYS2.ISP.TLIB _ ISP.V2R2M0.TLIB 012 SYSHELP _ USER.HELP _ SYS1.HELP _ SYS2.HELP 013 ISPPLIB _ HERC01.ISP.PLIB _ USER.ISP.PLIB _ SYS2.ISP.PLIB _ ISP.V2R2M0.PLIB _ SYS2.REVIEW.PLIB 014 SYSEXEC _ HERC01.EXEC _ USER.EXEC _ SYS2.EXEC _ BREXX.V2R5M3.SAMPLES 015 SYSPROC _ HERC01.CMDPROC _ USER.CMDPROC _ SYS1.CMDPROC _ SYS2.CMDPROC _ SYS2.REVIEW.CLIB 016 SYSUEXEC _ HERC01.EXEC 017 ISPPROF _ HERC01.ISP.PROF 019 LOGIT _ HERC01.LOGIT.D25044.T193900
9) Well Done!! Next…
10 Run the following JCL to add two dummy programs to new user PDS libraries being added to LINKLIST.
//HERC01A JOB (SYS),'Dummy Members', <-- Review and Modify
// CLASS=A,MSGCLASS=X, <-- Review and Modify
// MSGLEVEL=(1,1),NOTIFY=&SYSUID <-- Review and Modify
//* -------------------------------------------------------*
//* * Copy IEFBR14 as a dummy type member *
//* -------------------------------------------------------*
//STEP001 EXEC PGM=IEBCOPY
//SYSPRINT DD SYSOUT=*
//INLINKL DD DSN=SYS1.LINKLIB,DISP=SHR
//OUTLINKL DD DSN=USER.LINKLIB,DISP=SHR <-- Review and Modify
//OUTCMDL DD DSN=USER.CMDLIB,DISP=SHR <-- Review and Modify
//SYSIN DD *
COPY INDD=INLINKL,OUTDD=OUTLINKL
SELECT MEMBER=((IEFBR14,MYDMYUL$))
COPY INDD=INLINKL,OUTDD=OUTCMDL
SELECT MEMBER=((IEFBR14,MYDMYUC$))
/*
//
11) Depending on your host system, it suggested shutting down MVS 3.8J and backing up your MVS TK5 directory as a restore contingency. This will serve as the backup before modifying the LINKLIST.
After back up completes successfully, start up MVS 3.8J TK5 and logon to TSO/ISPF
12) Using 3.4 (DSLIST), ensure the candidate linklist datasets exist on your system.
13) Proceed with caution as this step, if not 100% correct, may render your system not re-startable! Augment LINKLIST declaration at procedure (SYS1.PARMLIB(LINKLIST)) to include user-wide PDS names and VOLUMEs in linklist concatenation as depicted below:
SYS1.PARMLIB(LNKLST00) 000001 SYS1.LINKLIB, 000002 SYS1.PPLIB, 000003 SYS1.CMDLIB, 000004 SYS2.CMDLIB, 000005 NJE38.AUTHLIB(TK5001), 000006 SYS2.LINKLIB, 000007 SYS1.PL1LIB, 000008 SYS1.FORTLIB, 000009 SYS2.DSSLIB, <-- add comma USER.LINKLIB(TSO003), <-- add PDS and VOL, do not forget comma USER.CMDLIB(TSO003) <-- add PDS and VOL, no commaallowing for user installed applications and preservation of user installed software!
Review above syntax in you edit session and SAVE changes.
14) Logoff ISPF
15) At the TSO READY prompt shutdown MVS 3.8J, type
SHUTDOWN and press ENTER.
16) Logoff TSO, at TSO READY prompt, type
LOGOFF and press ENTER.
17) Wait for shutdown to complete.
18) Start up your TK5 system.
19) LOGON to TK5, wait for ISPF main menu.
20) Check for dummy USER.LINKLIB load member MYDMYUL$.
On the ISPF main menu command line, type
TSO CHECKMOD MYDMYUL$ and press ENTER
MYDMYUL$ found in link list, size = 000008
***
21) Check for dummy USER.CMDLIB load member MYDMYUC$.
On the ISPF main menu command line, type
TSO CHECKMOD MYDMYUC$ and press ENTER
MYDMYUC$ found in link list, size = 000008
***
22) Congratulations!!! You successfully implemented a user-wide software access level for ISPF, TSO, BREXX, and Batch
Using User-Wide level for user-installed software
Installing user software, that is, software not distributed with TK5, is easy and persistent after a distribution update.
Simply, install software using USER HLQ libraries on volumes not used by TK5 distribution updates.
If any MVS 3.8J configuration is required as part of a new user-installed software, make note of those details as they will become part of your exception task list that is applied post TK5 distribution update to re-enable your user-installed software.
As of Update 3, volumes used for distribution updates include:
TK5RES - 3390, MVS sysres volume. TK5DLB - 3390, MVS distribution libraries. TK5001 - 3390, package volume 1. Contains user catalog SYS1.UCAT.TK5. TK5002 - 3390, package volume 2.
TK5 System does not IPL correctly
If TSO is not available, use ETPS to review linklist modification. Consult TK5 User Manual, p.25, for starting ETPS.
If TSO is available (READY prompt), use RPF or RFE to review and correct linklist modifications. Re-IPL TK5.
Software Disclaimer
No guarantee; No warranty; Install / Use at your own risk.
This post content is provided “AS IS” and without any expressed or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.
Submit any modifications, enhancements and/or suggestions to improve overall knowledge sharing with the MVS 3.8J hobbyist public domain community.
Closing
Please use the comment box below or the contact us link on the menu bar to communicate any suggestions, improvements, corrections or issues.
Enjoy TK5 with User-Wide access for all TSO/ISPF users!
Larry Belmontes