SYSTEM BY EVAN GALEN STRATEGIES Applications of TSO CLIST Built-in Variables to System Data Set Names n the September 1996 issue of Technical Support I presented an article highlighting some applications of the MVS/ESA INCLUDE JCL state- ment. The INCLUDE statement was used to demonstrate an IPL recov- Iery mechanism for the primary JES2 cataloged procedure. It was also used as a technique for removing user dependence on system-level dataset This article presents the names through the use of JCL variables. The system-level INCLUDE groups application of the JCL described in the article used the JCL SET statement to define system dataset SET statement concept names as variables to be used in user JCL. This article presents the application to the TSO LOGON of the JCL SET statement concept to the TSO LOGON process and to pro- process and to program gram product execution through the use of TSO CLIST built-in variables. A product execution description of the variables used in one implementation is discussed. The vari- through the use of TSO ables are implemented in a locally written TSO/E exit IKJCT44B, one locally CLIST built-in variables. written TSO command called ISPDSNCP and two programs named ISPDSNLD and ISPISNLD. A local LOGON CLIST, which creates a user TSO environment, is constructed and appropriate installation exit points are indicated for possible customization. Any reference to “local” means local to the installation and not vendor-related. MVS/ESA Version 5 and TSO/E Version 2.5 were used for all programming samples and figures. DEFINITIONS TSO/E, an IBM module named IKJCT44B. A CLIST (Command LIST) built-in function The CLIST built-in function exit may is defined as an operation that can be performed be written by the systems programmer on a variable, an expression or a character and must be named IKJCT44B. When string. It consists of a name followed by an CLIST processing encounters a variable argument in parentheses. The argument can be with the &SYSX prefix that has not been a variable, an expression or a character string. defined in the executing CLIST, it passes Examples of a CLIST built-in function include control to the CLIST built-in function exit, &STR(string), &SUBSTR(expr[:expr],string), if one exists. It is within the exit processing and &LENGTH(expression). An example of a that a character string is substituted for the local CLIST built-in function is &SYSXPRE- built-in variable. When the CLIST execution EXEC(&PARMSFX). IKJCT44B is called to resumes, the appropriate data is presented process this built-in function. A TSO CLIST when the variable is referenced. For more built-in variable is a CLIST built-in function information on CLISTs, refer to IBM with no argument, such as &SYSXJCOBCM- TSO Extensions for MVS: CLISTs (SC28- PLIB. IKJCT44B is called to process this 1876). For more information on CLIST built-in variable. built-in functions and how to write one, CLIST built-in variables are implemented refer to IBM TSO Extensions for MVS: in the CLIST built-in function exit of Customization (SC28-1872). TECHNICAL SUPPORT JANUARY 1997 SYSTEM STRATEGIES CONSTRUCTING A LOCAL LOGON CLIST Figure 1: Sample TSO User Output Listing The first application of TSO CLIST built-in variables to system dataset names is in the 1 //userid1 JOB (0000,0000),’userid1 LOGON process. The user logs onto a system ‘,REGION=0K, with the LOGON command.The LOGON // TIME=NOLIMIT command invokes a LOGON cataloged proce- //* dure which was established by the installation 2 //LCLDSNS INCLUDE MEMBER=ISDSNS1S systems progra m m e r. With the va ry i n g 8 //$SYSTEMS EXEC $SYSTEMS requirements of different local user groups, XX********************************************************************* LOGON cata l o ged proc e d u r es may prol i fe r ate , XX* 08/07/96.220 * thus creating a systems programming mainte- XX* * nance problem. It is desirable to keep the XX* SYSTEMS LOGON PROCEDURE FOR TSO AND ISPF/PDF. * number of LOGON proc e d u r es to a minimum. XX* * XX********************************************************************* XX* 9 XX$SYSTEMS EXEC PGM=IKJEFT01, A CLIST (Command LIST) XX DYNAMNBR=200, XX PARM=’EX ‘’&CLISTSYS($LOGON)’’’ built-in function XX* is defined as an operation IEFC653I SUBSTITUTION JCL - PGM=IKJEFT01,DYNAMNBR=200,PARM=’EX ‘’SYS2.SYSTEM.CLIST($LOGON)’’’ 10 XXSYSPRINT DD TERM=TS,SYSOUT=* that can be performed 11 XXSYSTERM DD TERM=TS,SYSOUT=* on a variable, 12 XXSYSIN DD TERM=TS an expression STMT NO. MESSAGE or a character string. 2 IEFC002I INCLUDE GROUP ISDSNS1S WAS EXPANDED USING SYSTEM LIBRARY SYS1.JES2.V522.JOB. INCLLIB It consists of a name 8 IEFC001I PROCEDURE $SYSTEMS WAS EXPANDED USING SYSTEM LIBRARY followed by an argument SYS1.JES2.V522.TSU.PROCLIB IEF236I ALLOC. FOR userid1 $SYSTEMS $SYSTEMS in parentheses. IEF237I TRM ALLOCATED TO SYSPRINT IEF237I TRM ALLOCATED TO SYSTERM IEF237I TRM ALLOCATED TO SYSIN The local LOGON process must be engi- neered to be easily maintained.The LOGON Figure 2: Sample Local LOGON CLIST Segment cataloged procedure should have a minimum of dataset names to maintain. With a minimum . of dataset names, a very small set of LOGON . p ro c e d u res needs to be maintained. See . Figure 1 for a sample output listing from a %LOGONPRE &DEBUG FILE(NOALLOC) ISPF(&ISPF) + simplified TSO LOGON cataloged procedure. PARMLIB(&SYSCLIST) SYSID(&SYSID) USERLIBS(&USERLIBS) + The local LOGON CLIST provides a solu- MSGGEN(&MSGGEN) MSGLOG(&MSGLOG) TIME(&TIME) VER(‘&VER’) tion for the LOGON process that allows easy /* User PRE exit point */ maintenance.The purpose of a local LOGON %ISPALLOC &DEBUG FILE(NOALLOC) ISPF(&ISPF) + CLIST is to create a TSO user environment PARMLIB(&SYSCLIST) SYSID(&SYSID) USERLIBS(&USERLIBS) + within MVS with a minimum of effort on the MSGGEN(&MSGGEN) MSGLOG(&MSGLOG) TIME(&TIME) VER(‘&VER’) user’s part. A TSO user environment encom- /* Allocate ISPF environment */ passes the virtual storage region within which SET &ISPALLOCRC = &LASTCC /* Save return code */ to execute TSO commands, the dat a s e t s %LOGONPST &DEBUG FILE(NOALLOC) ISPF(&ISPF) + required to accomplish useful work, and the PARMLIB(&SYSCLIST) SYSID(&SYSID) USERLIBS(&USERLIBS) + terminal monitor program (TMP) or Session MSGGEN(&MSGGEN) MSGLOG(&MSGLOG) TIME(&TIME) VER(‘&VER’) M a n ager wh i ch establishes a conve rs at i o n /* User POST exit point */ between the user and the system. Each user . group may have specific requirements for . their particular TSO environment. The local . LOGON CLIST should be able to be cus- tomized by a particular user group to handle these requirements. The local LOGON CLIST built-in variables are used to maximize perfor- exit point is also defined.The local LOGON also promotes the use of a very small set of mance of the TSO session. A local LOGON CLIST also supports a pre- and post-set of LOGON pro c e d u res with no imbedd e d CLIST dataset pre a l l o c ation exit point is user-customizable dataset name tables. Refer dataset names. defined to allow the user group to customize to Figure 2 for a sample segment of a LOGON The local LOGON CLIST is designed to the LOGON process for their particular needs. CLIST which executes user requests and per- use a table of system dataset names. CLIST A local LOGON CLIST dataset post allocati o n forms dataset allocations. The %LOGONPRE TECHNICAL SUPPORT JANUARY 1997 SYSTEM STRATEGIES Figure 3: Sample System Dataset Name LOGON Source Table, ISPDSN20 and %LOGONPST CLISTs are user- c u stomizable CLISTs. If these CLISTs do not exist in any user SYSPROC datasets, the /*********************************************************************/ /* */ default system LOGONPRE and LOGONPST /* ISPF dataset names. */ CLISTs will execute.These system CLISTs /* */ are programming stubs. The %ISPALLOC /* This file contains the group level and common dataset names */ CLIST allocates the datasets required for the /* for use with the local ISPF. */ TSO environment and uses the table of system /* */ /* The positional parameters are as follows: */ dataset names as built-in variables. /* */ /* 1 - DDNAME of ISPF file. */ /* 2 - ACF UID string segment. An * indicates a common library. */ /* SCPLIST indicates a data security administrator. */ /* 3 - Dataset name. */ To complement the TSO /* */ /* The concatenation order is derived from the order in which */ CLIST built-in variables /* entries are defined in this table. */ /* */ used for system dataset /*********************************************************************/ names, a local command /* */ ISPMLIB * SYS1.ISP.V4R2M0.SISPMENU was introduced to handle ISPMLIB * SYS1.SBPXMENU ISPMLIB * SYS1.VSFORT.V260.VSF2MLIB execution of modules /* */ ISPPLIB * SYS1.ISP.V4R2M0.SISPPENU residing in the linklist. ISPPLIB * SYS1.SBPXPENU ISPPLIB * SYS1.VSFORT.V260.VSF2PLIB Called CALL@, this TSO /* */ ISPSLIB * SYS1.ISP.V4R2M0.SISPSENU command uses only the ISPSLIB * SYS1.ISP.V4R2M0.SISPSLIB /* */ linklisted module name ISPTLIB * SYS1.ISP.V4R2M0.SISPTENU to invoke the module. ISPTLIB * SYS1.SBPXTENU ISPTLIB * SYS1.VSFORT.V260.VSF2TLIB /* */ SYSEXEC * SYS1.ISP.V4R2M0.SISPEXEC The table of system dataset names contains SYSEXEC * SYS1.EUV.SEUVEXEC the basic set of datasets to allow the LOGON SYSEXEC * SYS1.SBPXEXEC process to complete. It also supports the invo- SYSEXEC * SYS1.SIOEEXEC ca tion of the ISPF/PDF app l i c a tion. The system /* */ source table is named ISPDSNss, where ss is SYSHELP * SYS1.HELP SYSHELP * SYS1.ISP.V4R2M0.SISPHELP the system suffix. User source tabl e s /* */ ISPPREss and ISPPSTss are also scanned if SYSPROC * SYS1.ISP.V4R2M0.SISPCLIB.VB they exist. The table is parsed by a subroutine SYSPROC * SYS1.COB2CLIB.VB in IKJCT44B and all dataset name objects are SYSPROC * SYS1.SERBCLS.VB SYSPROC * SYS1.VSFORT.V260.VSF2CLIB.VB assigned to an ap p ro p ri ate built-in va ri abl e. /* */ A table of these built-in vari a bles is maintained SYSINCLD * SYS1.JES2.V522.JOB.INCLLIB in virtual storage for maximum CLIST perfor- mance.