MVS TOOLS AND TRICKS OF THE TRADE February 1993 Sam Golob MVS Systems Programmer sbgolob@cbttape.org Sam Golob is a Senior Systems Programmer PUTTING YOUR TOOLS TOGETHER - PART III. This month we are concluding a series that I hope is helpful to all of you. The idea is to present ways of getting more of your tools into easier reach. The first part of this series dealt with customizing your ISPF command tables, which has the effect of making numerous applications instantly and recursively available for your use. I think that the ISPF command table presents the greatest single opportunity for bringing tools closer together. Last month we presented the second installment, which dealt with tool packages. These are integrated tool kit software packages that combine a large number of utility functions in one place. With the use of one or more tool packages, a great number of your tools are already consolidated, making it easy to bring many different utility functions to bear on your current single problem. This month, in concluding the series, we'll briefly talk about three areas: ISPF edit macros, handy TSO commands, and obtaining "private" APF authorization for your TSO commands. Being able to run certain commands "authorized" can often be a big time saver. Your own "personal" APF authorization will definitely be useful if you are the system doctor in your shop. ISPF EDIT MACROS. Most of us spent much of our day using the ISPF/PDF editor. We edit JCL, data files, and program source. The editor as supplied by IBM contains numerous primary commands as well as line commands. Because most of us have spent a lot of time with the editor, we have become familiar with a large number of its commands and we use them often. Starting with ISPF Version 2 and continuing with Version 3, IBM has supplied an add-on to the editor which assists the user enormously. This is the edit macro feature. Edit macros are a programmable interface to the commands of the ISPF editor. By invoking an edit macro with one command (or a pfkey), complicated and repeatable manipulations can be instantly accomplished. You just have to take the time to write the macro, or to learn to use somebody else's macro. Edit macros can be either clists, REXX execs, or programs. Most of the edit macros you'll come across are clists or REXX execs. Program macros can be written in any of several languages; assembler, COBOL, and PL/I are among them. Edit macros that are clists or REXX execs are invoked the same way that clists are, except that they only work while you're editing a file or a pds member. Program macros aren't invoked that way. If you want to run a program macro, you have to precede its name with an exclamation point. For example, if you have a program macro called JCLFLOW, which makes the ddnames in your JCL more orderly, you invoke the macro by typing the command !JCLFLOW while editing your JCL. JCLFLOW, which I've aliased as JF, can be found on the CBT MVS Tape on File 047. It comes from Jim Lane, a system programmer from Toronto. See Figure 1 for "before" and "after" pictures of JCLFLOW invocation. I use JCLFLOW to assist me while I'm writing or fixing JCL for jobs or procs. It's quick and very helpful to create room when I'm adding new DD card parameters. A nice collection of clist edit macros comes from Paul Davis, formerly of Houston, Texas, who now lives in Colorado. This collection is found on File 095 of the CBT MVS Tape. You can order the CBT Tape either from NaSPA (414-423-2420) or from SPLA (305-284-6257) at the University of Miami in Florida. Many of the NaSPA chapters give tapes out for free at their meetings (mine does). It pays to go to chapter meetings if you're fortunate enough to have a chapter nearby. There isn't enough space to show in detail how these edit macros can help you, but I've included Paul's table of contents in Figure 2. From Figure 2, you can get a good idea of the kind of jobs edit macros will do, and how powerful they can be. Of course, the possibilites inherent in the edit macro facility are almost limitless, and they offer an excellent opportunity for study and exploitation. The rest is up to you. IBM's edit macro manual is called "ISPF/PDF Edit and Edit Macros", number SC34-4138 in ISPF Version 3. TSO COMMANDS. TSO commands are your one-stroke servants. If you've made a collection of good commands accessible to your TSO session, you've shortened your daily work considerably. Many files on the CBT Tape contain big collections of useful TSO commands. You might start with Files 300, 270, and 134. I recommend allocating one pfkey in ISPF for the name "TSO". This may be done in ISPF option 0.3. The reason is that TSO commands may be executed from the ISPF command line by prefixing them with the word, TSO. When you type a TSO command on an ISPF command line and you have a "TSO" pfkey, pressing that key will prefix the typed command with the name "TSO" and will execute it as though you typed the word "TSO" before it. If you execute TSO commands often while in ISPF, it saves a lot of time to have such a designated pfkey. AUTHORIZING TSO COMMANDS FOR YOUR PERSONAL USE. Some of the TSO commands which you, as a system specialist, may need to use, have to run APF authorized under TSO. It will save you much time and grief to use commands such as CDSCB (change the DSCB) in doing dataset management, for example. CDSCB was written by Bill Godfrey, and is found on File 300 of the CBT Tape along with hundreds of other useful TSO commands that you can learn. As the system doctor of your installation, you will want to authorize some commands for your own use, without granting that ability to the general public. There are three requisites for APF authorization of a program under TSO. These are: The program has to reside in an APF authorized load library. Load library authorization is controlled by a table whose virtual address is found in the CVT at label CVTAUTHL. This table is loaded at IPL time from an IEAAPFnn member of SYS1.PARMLIB. Next, the program itself has to be linkedited with the authorization attribute set on in its directory entry. That is done by the linkage editor if the control statement "SETCODE AC(1)" was coded at linkedit time. Finally, if the program is to be run from TSO, its name must appear in one of several tables designated for permitting authorized programs to be run under TSO. Older versions of TSO and TSO/E contained these tables in one of the terminal monitor load modules, IKJEFT02. The CSECT containing the list of authorized TSO commands is called IKJEFTE2, and the CSECT of authorized called programs is called IKJEFTE8. IKJEFT02 and its numerous aliases reside normally in SYS1.LPALIB. The later versions of TSO/E have split these tables off into a separate module called IKJTABLS. IKJTABLS is still in SYS1.LPALIB. At those levels of TSO/E, IKJEFTE2 and IKJEFTE8 are not a part of IKJEFT02 any more, but are part of IKJTABLS. IKJTABLS at these levels does not contain any executable code, it only contains four different tables of program names under four separate CSECTS. Each table of names serves a different purpose. See IBM's "TSO/E Customization" manual for more details. See Figure 3 for a CSECT map of IKJTABLS. Most installations now put their authorized TSO commands and programs called from TSO into a SYS1.PARMLIB member called IKJTSOnn. These entries in the PARMLIB member allow authorization of programs and commands under TSO for the entire installation. Most installations do not bother using IKJTABLS any more. However, the designers of TSO/E have kept the module IKJTABLS available and usable. For our purposes, we can take great advantage of this fact. An authorized library run as a STEPLIB in the TSO logon procedure will allow the system doctor to get all the power he or she needs. The particular installation will not want to allow this for ordinary TSO users. Our trick is to make a copy of the IKJTABLS module with all its aliases, expand the number of its entries greatly through reassembly and re-linkediting, copy all the entries found in IKJTSOnn to these tables, add all the additional program names you want, and put the resulting IKJTABLS load module and aliases into your authorized STEPLIB. That will override the installation's PARMLIB member IKJTSOnn, just for you. This works because the STEPLIB programs are executed ahead of programs in the LPA list, and ahead of the incore tables created from IKJTSOnn. If you set this up, you'll never again complain of not being able to run a program authorized under TSO. Of course, having a general TSO user doing that is not to be taken lightly. Your installation's security procedures will probably want to disallow it for most people. But the facility is there if you yourself, and the MVS group, need it. I have left out much detail from this installment because of space requirements. But there is gold and riches in what I have said. The jewels have to be mined. That must be done through your own personal effort. Good luck and much success. See you next month. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. Illustration of the workings of the JCLFLOW program edit macro. Source for the program can be found on File 047 of the CBT MVS Tape. Notice that the macro reads the JCL above and only affects DD cards. The result of the macro is the JCL below. Execution time of JCLFLOW is "almost instantaneous", even for big JCL. -- JCL BEFORE USING THE JCLFLOW PROGRAM EDIT MACRO. //SBGCTCZ JOB (A006,SYTM,99,99),'SAM-GOLOB',CLASS=S,MSGCLASS=K, // NOTIFY=&SYSUID //* //COMPRESS EXEC PGM=IEBCOPY //SYSPRINT DD SYSOUT=* //I DD DSN=SBGCTC.A.DATA,DISP=SHR,UNIT=SYSDA,VOL=SER=ESAPAK //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,10) //SYSUT4 DD UNIT=SYSDA,SPACE=(CYL,10) //SYSABEND DD SYSOUT=* //SYSIN DD * COPY O=I,I=I /* -- JCL AFTER USING THE JCLFLOW PROGRAM EDIT MACRO. //SBGCTCZ JOB (A006,SYTM,99,99),'SAM-GOLOB',CLASS=S,MSGCLASS=K, // NOTIFY=&SYSUID //* //COMPRESS EXEC PGM=IEBCOPY //SYSPRINT DD SYSOUT=* //I DD DSN=SBGCTC.A.DATA, DISP=SHR, UNIT=SYSDA, VOL=SER=ESAPAK //SYSUT3 DD UNIT=SYSDA, SPACE=(CYL,10) //SYSUT4 DD UNIT=SYSDA, SPACE=(CYL,10) //SYSABEND DD SYSOUT=* //SYSIN DD * COPY O=I,I=I /* * * * * * * * * * * * * * * * * * * * * * * * FIGURE 2. Contents of a collection of edit macros from Paul Davis. This collection is found on File 095 of the CBT MVS Tape. You can get a good idea of the power of edit macros in shortening your work, by looking through this list. This is a collection of various edit macros that may be somewhat useful at your installation. Some of them are my original, and others are from other SHARE users. All of them work at this site. Some may need to be modified to work at your site. To use them you will need to have ISPF 2.2 or later and TSO/E Rel 3 or later. THIS FILE CONTAINS THE FOLLOWING: COBLCAS COBOL SOURCE FOR LCASE (LOWER CASE) EDIT MACRO COBSEPL COBOL SOURCE FOR SEPLINE EDIT MACRO COBUCAS COBOL SOURCE FOR UCASE (UPPER CASE) EDIT MACRO $MACROS ADDCMDS CLIST TO ADD ASSIST IN ADDING COMMANDS TO ISPF COMMAND TABLE ASMBOX DRAW A BOX AROUND ASSEMBLY CODE LINES (COMMENT THEM OUT) B BROWSE A MEMBER IN SAME PDS WHEN IN EDIT BIG CREATE BIG LETTERS IN YOUR TEXT BIGS CREATE BIG SLANTED LETTERS IN YOUR TEXT BLDCOPY BUILD IEBCOPY SYSIN STATEMENTS TO COPY MEMBER OF A PDS BRODUPDT NEATLY UPDATE SYS1.BRODCAST MESSAGES CENTER CENTER TEXT IN YOUR TEXT CHGALL QUICK CHANGE ALL COMMAND CLISTBOX DRAW A BOX AROUND CLIST LINES (COMMENT THEM OUT) CLONE CLIST TO INVOKE CLONES AND CLONEP FROM ISPF (3.4 ALSO) CLONEP BUILD JCL TO CLONE A PDS CLONES BUILD JCL TO CLONE A SEQUENTIAL FILE CMDS DISPLAY COMMAND TABLE ENTRIES CMDUPDT1 EDIT MACRO CALLED BY ADDCMDS CLIST COBBOX DRAW A BOX AROUND COBOL CODE LINES (COMMENT THEM OUT) COMMENTS FIND ALL THE COMMENTS IN YOUR DATASET COMPRESS COMPRESS CURRENT PDS IN PLACE CONLY CHANGE "ONLY" COMMAND WITH SUB PARAMETERS CONT PUT CONTINUATION CHARACTER IN COL 72 CUSTBOX DRAW A CUSTOM BOX TO SPECIFICATION LENGTH X WIDTH IN YOUR CODE CUT CUT TEXT LINES FROM DATASET TO BE PASTED LATER CUTTO CUT TEXT LINES FROM DATASET TO ANOTHER DATASET D DELETE A MEMBER OF THE CURRENT PDS DELCUT REMOVE A LEVEL OF CUT FROM PROFILE DSIGENP CREATE IEBCOPY JCL FOR A PDS DSIGENS CREATE IEBGENER JCL FOR A SEQUENTIAL DATASET E EDIT ANOTHER MEMBER OF THE CURRENT PDS EDITPDS CLIST: PERFORM A COMMAND ON ALL MEMBERS OF A CLIST EMACS LIST TABLE SHOWING EDIT MACRO DESCRIPTIONS FC FIND PENDING LINE COMMANDS FIXJCL TIDY UP YOUR JCL INIT INITIAL MACRO FOR EDIT MACRO PURPOSES INITIAL INITIALIZE DATASET HEADERS FILL IN THE BLANK INFO JC CREATE A JOBCARD JCLBOX DRAW A BOX AROUND JCL LINES (COMMENT THEM OUT) JC2 CREATE A SPECIALIZED JOBCARD JC3 CREATE A JOBCARD WITH REFER INFO JOBCARD CREATE A JOBCARD LCASE CHANGE ENTIRE DATASET TO LOWER CASE LCASEC CLIST MACRO TO CONVERT A DATASET TO LOWER CASE LJUST CHANGE AN ENTIRE DATASET TO UPPER CASE MACHELP GET HELP FOR INDIVIDUAL MACROS MACLIST DISPLAY A TABLE OF CURRENT ISPF EDIT MACROS MEMLIST SHOW THE MEMBERS IN THE CURRENT PDS MOVECOLS MOVE COLUMS OF DATA WITHIN DATASET MRCLEAN WIPE THE DATA OUT OF MEMBER BUT PRESERVE THE BLANK LINES MSTATS PROVIDE ISPF STATS ON MEMBER WITHOUT LEAVING EDIT ONLY FIND ONLY THE DATA WANTED OTHER SAMPLE MACRO TO USE WITH PFSET (CHANGE TO SUIT NEEDS) PARA WORD PROCESSING POWER FOR ISPF EDIT PARADOC DOCUMENTATION FOR PARA MACRO PASTE PASTE DATASET LINE THAT WERE CUT EARLIER PBOX DRAW A FLOWCHART BOX PFCAN RESET PFKEYS BACK TO NORMAL PFSET SET PFKEYS TO SPECIAL PURPOSE PRTIT VPSPRINT CURRENT DATASET QCREATE QUICK CREATE TO CURRENT DATASET QREP QUICK REPLACE TO CURRENT DATASET RCOLDEL DEL RULE LINES RCOLS FANCY RULE REPOTHER QUICK REPLACE TO OTHER DATASET RJUST RIGHT JUSTIFY TEXT RNAME RENAME A MEMBER WHILE IN EDIT S EDIT A MEMBER OF CURRENT PDS SEPLINE ADD SEPARATION LINES IN YOUR TEXT SHOWCUT SHOW TEXT PREVIOUSLY CUT SHOWCUT2 SHOW ONE LINE OF EACH CUT LEVEL SHOWDCB SHOW CURRENT DATSET DCB SHOWFLOW SHOW THE LOGIC FLOW OF CLIST OR PL/1 PROGRAM SHOWMACS SEE HELP FOR ALL EDITMACS ONE AT A TIME SLINE PLACE A SINGLE SEPARATION LINE WHERE NEEDED IN TEXT SORTDUPS SORT CURRENT EDIT DATASET AND FIND DUPES ST SUPERTYPE, TYPE A STRING OF BLOCK LETTERS NICE.... STAMP STAMP DATA INTO YOUR TEXT STEDITY EDIT MACRO CALLED BY WHERMEM2 STEDIT2 EDIT MACRO CALLED BY WHEREMEM SUM SUM COLUMNS OF NUMBERS T WHAT TIME IS IT TABLBLD CLIST: CREATE ISPF TABLE FROM $DESCRPT MEMBER USED BY EMACS TYPE TYPE BLOCK CHARACTERS WITH EASE AND AUTO SPACING TYPESET EDIT MACRO TO USE WITH PFSET TO SET UP FOR "TYPE" UCASE CHANGE ENTIRE TEXT TO UPPER CASE UCASEC CLIST MACRO TO CONVERT A DATASET TO UPPER CASE UNSEP REMOVE SEPARATION LINES CREATED BY SEPLINE WHEREMEM CLIST: SHOW OCCURENCE OF MEMBER IN DD CONCATENATION -- USEFUL WHERMEM2 CLIST: SAME AS WHEREMEM MORE COMMANDS AND INFO -- USEFUL WIPEIT ERASE ALL LINES IN DATASET BUT MAINTAIN BLANK LINES XCOPY COPY A DATASET OTHER THAN THE PDS YOU ARE WORKING IN * * * * * * * * * * * * * * * * * * * * * * * Figure 3: Here's the structure of the IKJTABLS load module. This module controls which programs can be executed authorized under TSO. The outputs shown are courtesy of the MAP and ATTRIB subcommands of the PDSTOOLS product from Serena. PDSTOOLS was convenient for me to use. You can get comparable information from running IBM's AMBLIST program. See the MVS Service Aids manual for information about AMBLIST. Please note that my copy of IKJTABLS is probably much larger than yours. I've expanded mine a lot. That's the point. - DSN=SYS1.USERAUTH,VOL=SER=MVSCAP MEM=IKJTABLS ** MAP IKJTABLS IKJEFTE2 00000000 000480 APFCTABL 00000010 IKJEFTE8 00000000 000130 APFPTABL 00000490 IKJEFTNS 00000000 00009E NSCPTABL 000005C0 IKJEFTAP 00000000 0000E8 APFTTABL 00000660 PDS103I Entry point at 00000000 -- IKJEFTE2 PDS104I Module length 000738 -- 2K >attrib ikjtabls PDS020I IKJTABLS Attributes are: RENT, REUS PDS024I Page alignment is required PDS103I Entry point at 000000 -- IKJEFTE2 PDS104I Module length 000738 -- 2K PDS064I Last link-edited on 92/11/24 by LKED 566528408 V03 M02 PDS160I Aliases for this member are: IKJEFTAP, IKJEFTE2, IKJEFTE8, IKJEFTNS