MVS TOOLS AND TRICKS OF THE TRADE November 1990 Sam Golob MVS Systems Programmer sbgolob@cbttape.org BILL GODFREY'S CONTRIBUTIONS; THE NEW REVIEW COMMAND This month, before our regular business, I'd like to thank a big contributor to public software in the MVS world. Bill Godfrey, who works for Planning Research Corp. near Washington D.C., has written many programs and TSO commands in current use by programmers all over the world. Bill has also extended the life of some older IBM-distributed tools which would have gone by the wayside with the arrival of XA and ESA. Many of us probably do not realize that we are using some of Bill's programs ourselves. Much of Bill's work was sent into the CBT MVS Tape while he was working together with Jim Marshall of the Air Force. Bill wrote the stuff, and Jim would send it into Arnie Casinghino, who administers the CBT tape. A lot of Bill's pioneering work was done in the late 70's and early 80's. Just SOME examples of Bill Godfrey's work are: the CDSCB program for changing Format 1 VTOC entries (CDSCB was featured in my JULY 1990 column). The $$MACROX modifications are source patches to the IFOX00 assembler, which allow all macro names and their originating libraries to be reported in an assembly listing. (The SLAC Mods to Assembler H supply a similar report for the IEV90 assembler.) Other TSO tools are his LPSCB and CPSCB programs (for listing and modifying TSO session attributes) and his many extensions to TSO EDIT and TSO TEST (some of these were described in "TSO TEST Enhancements" by Alan Field - August 1990). Bill Godfrey has also contributed important disassemblies of the IBM utilities INCORZAP and DELINK0 from the object code only versions, making these programs available in readable assembler source. Bill's disassembly of INCORZAP into assembler source code is especially noteworthy. INCORZAP is a program which zaps IN-STORAGE copies of NUCLEUS or LPALIB modules. It was originally written in the PL/S language by Robert Budge when he worked for IBM. Later, after Budge had left IBM and didn't have access to PL/S, he saw a copy of Bill Godfrey's assembler source on a CBT tape. The assembler language version of INCORZAP allowed Budge to fix the code so that it could modify protected storage under XA. Here's how INCORZAP works. INCORZAP can look at the CSECT structure of a module in SYS1.LPALIB or in the disk copy of the NUCLEUS. It then goes to the module's load point in core, doing AMASPZAP-type VER and REP zaps on the IN-STORAGE versions of these modules (plus a page fix). Under old MVS/370, the PLPA and NUCLEUS in-core storage had been accessible. Under XA, some of that storage is "protected". Robert Budge's new version, called XACORZAP, can turn off the protection, and change the storage anyway. Bill Godfrey is also the ORIGINAL author of "TSSO" (Time Sharing Subsystem Option) which allows the execution of TSO commands on an MVS system console. Bill's original version of TSSO is on CBT Tape File 306. Although the preferred version of TSSO is Version 4.3 from Marc Schare (File 401), Bill Godfrey started bringing the TSO environment to the domain of the operator console, paving the way for what followed. Much of Bill Godfrey's code can still be found in Jim Marshall's two large collections of tools. TSO tools are on File 300 of the CBT tape. Batch programs are on File 316. These collections are very much worth exploring. Robert Budge's XACORZAP code is found on File 421, with full documentation included. * * * * * * * * * * * * * * * * * * * * * * * THE WONDERS OF THE NEW "REVIEW" COMMAND. Our regular topic concerns a neglected but useful GENERAL BROWSING TOOL, the REVIEW command, which works under TSO. REVIEW was originally written by Bruce Leland. Bruce's version appears on the CBT Tape, File 296. The extension of REVIEW which sparks our current interest was written by Greg Price of Melbourne, Australia. There is about DOUBLE the amount of code in Greg's version of REVIEW. Greg's code appears in source on File 134 of the CBT tape, and in load module form on File 135. Greg Price jokes about his version of REVIEW that "it is a case of creeping featurism". I myself feel that featurism is generally useful for us sysprogs, who are always scrapping to acquire any power or utility services that might be available. Greg's REVIEW is FULL of powers that await to be tapped. Greg Price's REVIEW contains an awful lot of function. Greg claims that his REVIEW will allow browsing of most files that have a VTOC entry, including VSAM files; REVIEW will format individual records within control intervals. REVIEW will also allow browsing of TAPE files, as well as disk files of up to 32760 bytes record length. You can browse the active VSAM SMF file, as well as SMF history files that have been written to tape. REVIEW (in "SMF mode") will format the SMF records by type, and will interpret much of the recorded data on the TSO screen. REVIEW will often allow you to look at files that are currently OPEN. REVIEW can also be told to bypass I/O error spots and EOF markers, both on disk and on tape. Many extremely large files can be quickly REVIEWed FROM THE BOTTOM. That's a feature which even ISPF BROWSE doesn't have! Greg's REVIEW (unlike Bruce's earlier version) can handle an entire partitioned dataset. REVIEW has some special features that are tailored for pds'es, notably its OFFLOAD of selected (or all) members to a sequential dataset in IEBUPDTE format (preserving ISPF stats if they are present). If you REVIEW a dataset name that is a pds, you are presented with a sortable and flexible member list display (see Figure One). Much useful work can be done from this display. This member list also makes possible the OFFLOAD feature of REVIEW. The rest of our column will detail some of REVIEW's special capabilities, so you can imagine some of the mileage that you might get from it. REVIEW AS A TSO COMMAND. Using REVIEW is very simple. At a TSO terminal, one merely types: REVIEW dataset.name (where the dataset.name refers to either a sequential dataset, a pds, or the VTOC name of a VSAM file. It may also be a cataloged tape file.) or REVIEW filename FILE (where the filename is a ddname allocated to the TSO session.) If dataset.name is a partitioned dataset, a complete member list appears (see Figure One). In the member list, one may enter a LINE COMMAND of "S" (for REVIEW), "B" (for ISPF BROWSE if available) or "E" (for ISPF EDIT if available). An eight-byte "locate" field for positioning to a given member, is the only input field on the member list, besides the one-byte code input field on each line next to the member name. PFKEYS can be used as input to member list mode. Their meanings are listed in the prompt area at the top of the member list. Some PFKEYS are devoted to sorting the member list in different ways. Figure One shows various member list sorts, and gives other information on using the member lists. If a sequential file or a VSAM file is being REVIEWed, the data appears immediately. See Figure Two for the sample REVIEWing of some data. When actually looking at data, we say we are in "REVIEW-data mode". All command descriptions which follow (except for the case of member offloading) apply to being in REVIEW-data mode. When REVIEWing a member or a single dataset, the user has a lot of flexibility. PF1 is the HELP key. A question mark "?" on the command line or the "KEYS" command will have the same effect as PF1. This will cause a second panel to be shown, which displays the current use of the other PFKEYS. See Figure Three. It pays to install Bruce Leland's fullscreen TSO help program that is called "HEL". HEL is found on CBT tape File 296 or on File 134. The HEL load module is on File 135. If the REVIEW "TSO help" member has been put into the TSO SYSHELP concatenation, then a second hit of PF1 will make detailed help available in fullscreen mode. Some general commands are available from the REVIEW-data mode command line. From the data mode command line, the "TSO" subcommand will allow us to execute any TSO command from within REVIEW. If we are looking at a pds member, the "DIR" command, entered on the command line, will get us into the member list mode. From within any member, the "MEM newmembr" command will switch us to REVIEWing another member. ASCII data may be displayed on an EBCDIC terminal with the "ASCII" command, which toggles ASCII mode on and off. If SMF data ("live" from the VSAM file, or from a backup tape) is being displayed, the "SMF" command toggles SMF record interpretation on and off. Almost all types of SMF records are partially or completely interpreted by the "SMF mode" of REVIEW. HEX data is displayed by the "HEX" command, which toggles "HEX mode" on and off. Newer color terminals may benefit from "COLOR mode", which may be toggled on or off using the "COLOR" command. Let's talk about actually looking at a dataset. There are various "FIND" commands which can help you. "FIND" is an ordinary string find command, but with the argument translated to uppercase. This is similar to the action of the "FIND" subcommand in ISPF edit or browse. To achieve an "asis" effect, the "FINDCHR" command is used. Under "FINDCHR", no uppercase translation is done. "FINDHEX" helps locate hex strings. If SMF data is being looked at in SMF mode, the "FINDSMF" command will locate the next occurrence of a given SMF record type. The "LIST" command will position you to a particular logical record number. For example, "LIST 340" will position you to the 340th record of the file. The usual "UP nnn" and "DOWN nnn", "RIGHT nnn" and "LEFT nnn" commands are available. "+" and "-" are aliases for DOWN and UP. "<" and ">" are aliases for LEFT and RIGHT. TOP and BOTTOM have their usual meanings. REVIEW has some conveniences built in, for looking at large files. Suppose we're trying to look at the BOTTOM of a file that has 200,000 records. Let's say we've entered the "BOTTOM" command. If the records are FIXED BLOCKED, and REVIEW can calculate TTR data for the bottom of the file, then REVIEW positions itself at the bottom immediately. No time-consuming block scanning has to be done. For variable-blocked data or for "find" searches where this technique cannot be used, REVIEW has another feature that is good for the user. Suppose you have entered the BOTTOM command on a large variable-blocked file and the computer is cranking away. A press of "attention" will stop REVIEW in its tracks at the point where it currently is. You will see the point that it has gotten to thus far. That relieves the suspense of waiting--you can follow REVIEW's progress as it is moving along. At any point, you may resume the progress, by reentering BOTTOM or the particular "FIND" commmand you were using. One of the neat features of REVIEW is the "NEWTOP" command that can be used in REVIEW-data mode. NEWTOP is issued with an operand of a relative-TTR address to the beginning of the dataset, as in: NEWTOP 0010A When this is entered, REVIEW assumes that relative-TTR location 0010A within the dataset is the real top-of-data. NEWTOP can thus be used to position past I/O error spots and end-of-file markers in the dataset. Deleted PDS members and data past the "DS1LSTAR" high-water mark of "valid data" can be browsed using this tool. For tape files, the operand of NEWTOP is interpreted as a relative block number. One can look at "inaccessible data" on tapes, too. To reset REVIEW so that it will again look at the real top of the data, simply enter "NEWTOP" without any operands, or "NEWTOP 0". OFFLOADING MEMBERS TO SEQUENTIAL DATASETS. REVIEW has the capability of "sequentializing" selected members of partitioned datasets and preserving their ISPF statistics in that process. This facility depends on two things: the REVIEW member list for partitioned datasets, and pre-allocation of a SYSUT2 ddname to a sequential output dataset that will receive the offloaded members. To use the OFFLOAD capability of REVIEW, simply REVIEW a pds and get into member-list mode. You should have previously allocated a sequential dataset with compatible DCB attributes to the current dataset, using the file name of SYSUT2. Then you do the following: If you want to OFFLOAD all of the members, sort the member list (using PFKEYS) into a desired order. Then in the 8-byte "LOCATE" field of the member list, type the word "=OFFLOAD". REVIEW will signal when it has finished the offloading process and has closed the SYSUT2 output dataset. If you want to offload only SOME of the members, do the following: Sort the member list in the most convenient way, or in any desired order. Then type "O" as a line command next to some of the names you want to offload. Press enter. Doing this will highlight the desired members in the member list. Go down the member list and choose all the members you want by typing "O" next to them and pressing enter. When you've finished, type "=OFFLOAD" in the locate field as before. REVIEW will offload the selected members in the member list order, and will announce when it has closed the SYSUT2 dataset. The command "=REFRESH" in the locate field of the member list will clear all members previously selected for offloading. A line command of "R" (which stands for REFRESH) next to a member chosen for offload will cancel its selection. You can see that OFFLOAD is a useful facility. You'll realize this even more when you've used it yourself. REVIEWING TAPES. Any cataloged tape file may be REVIEWed by entering its name as the operand of the REVIEW command under TSO. The tape file might be described either as a dataset name or as a ddname (TSO file name). If you are pointing to a ddname, the keyword "FILE" must follow the name. A mount message will be issued to the MVS system console, and the operators will be instructed to mount the tape. Once mounted, the tape is positioned to the beginning of the data in the cataloged file. Entering successive REVIEW subcommands will cause the tape to be appropriately positioned, and REVIEW behaves similarly to the way it did for a disk file. Uncataloged standard-labeled tape files can be REVIEWed by a TSO user who has the MOUNT attribute, if the UNIT and VOLUME parameters are used in the ALLOCATE command for the tape file. This is OK as long as the file sequence number is 1. Greg Price supplies a CLIST for the purpose of REVIEWing tape files whose file sequence number is not 1. This CLIST comes on Greg's CBT Tape File 134 under the name REVTAPE. The idea of the CLIST is to exploit the POSITION parameter of the ALLOCATE TSO command for tape files. Please see Figure Four for a copy of Greg's REVTAPE CLIST, and notice his comments there. Greg Price's REVIEW has more power than we have described, and it is very much worth a good look from every MVS sysprog. I hope that our introduction will stimulate your creativity, and that this useful program will help your shop. Good luck. See you next month. * * * * * * * * * * * * * * * * * * * * * * * * FIGURE ONE. MECHANICS OF THE REVIEW MEMBER LIST. Illustration of REVIEW partitioned dataset member list, sorted in various ways. Note that the "LOCATE" field has 8 characters for positioning the list, and for command input. Command input in the LOCATE field must be preceded by an equal sign. Only currently supported commands from the LOCATE field are =OFFLOAD and =REFRESH. An "S" LINE COMMAND next to a member name will REVIEW the member. If ISPF is active, then "B" will BROWSE the member, and "E" will EDIT it. "O" next to a member will flag it after enter is pressed, for offloading using =OFFLOAD. Member list PFKEY instructions are shown on the second line. TSTBSSG.A.DATA ------------------------------------------ 818 MEMBERS ON TSO001 LOCATE ===> 1-TOP 2-BOT 3-END 4-SD 6-SN 7-UP 8-DN 9-SSZ 10-STTR 11-SID NAME TTR VV.MM CREATED LAST MODIFIED SIZE INIT MOD ID A 008F08 01.00 88/10/27 88/10/27 09:00 347 347 0 TSTBSSG AA 008E0F 01.13 89/02/30 89/05/08 10:57 363 363 15 TSTBSSG s ABEDOC 009E03 01.00 89/06/12 89/06/12 16:46 20 20 0 TSTBSSG ABENDAI1 005912 01.02 90/01/07 90/02/03 13:32 44 44 3 TSTBSSG ACNTLPW 001B09 01.01 87/02/04 89/07/16 19:08 61 60 1 TSTBSSG ACTRT 008B17 01.00 90/03/05 90/03/05 11:26 721 721 0 TSTBSSG ADSOXREF 008B01 01.00 89/11/03 89/11/03 07:43 265 265 0 TSTBSSG - - - - - - - - - - - - - - CONTINUED - - - - - - - - - - - - - - - - ZFMANUAL 001708 01.01 88/01/24 88/01/24 11:40 2933 2925 0 TSTBSSG **END** MOD 019505 1990/02/06-TSO001 185460 IBMOSVS2 SORTED BY MODIFICATION DATE/TIME ------------------------ 818 MEMBERS ON TSO001 LOCATE ===> 1-TOP 2-BOT 3-END 4-SD 6-SN 7-UP 8-DN 9-SSZ 10-STTR 11-SID NAME TTR VV.MM CREATED LAST MODIFIED SIZE INIT MOD ID DLOG 01940A 01.99 89/12/01 90/08/01 22:23 320 194 0 TSTBSSG b SHB 01910B 01.99 88/08/22 90/08/01 22:08 1471 41 0 TSTBSSG PDSJUST 01900D 01.01 90/07/25 90/07/26 00:54 451 436 0 TSTBSSG TSOFILES 01900A 01.00 90/07/25 90/07/25 12:47 63 63 0 TSTBSSG PDS84F 018F0A 01.01 90/07/23 90/07/23 18:14 495 495 0 TSTBSSG - - - - - - - - - - - - - - CONTINUED - - - - - - - - - - - - - - - - SORTED BY TTR ------------------------------------------- 818 MEMBERS ON TSO001 LOCATE ===> =offload 1-TOP 2-BOT 3-END 4-SD 6-SN 7-UP 8-DN 9-SSZ 10-STTR 11-SID NAME TTR VV.MM CREATED LAST MODIFIED SIZE INIT MOD ID XYZZ 00050F 01.03 85/07/18 85/07/23 11:37 8 1 0 TSTBSSG CP248INV 000511 01.00 88/10/27 88/10/27 09:00 1 1 0 TSTBSSG e DLOG8507 000513 01.00 85/08/09 85/08/09 17:46 217 217 0 TSTBSSG USREXT2 00051A 01.00 87/08/17 87/08/17 18:10 28 28 0 TSTBSSG USREXT2N 00060C 01.00 87/08/17 87/08/17 18:10 29 29 0 TSTBSSG - - - - - - - - - - - - - - CONTINUED - - - - - - - - - - - - - - - - SHB 01910B 01.99 88/08/22 90/08/01 22:08 1471 41 0 TSTBSSG DLOG 01940A 01.99 89/12/01 90/08/01 22:23 320 194 0 TSTBSSG **END** MOD 019505 1990/02/06-TSO001 185460 IBMOSVS2 (Note: DS1LSTAR. Create date. Vol. Total of size. ) SORTED BY SIZE ------------------------------------------ 818 MEMBERS ON TSO001 LOCATE ===> 1-TOP 2-BOT 3-END 4-SD 6-SN 7-UP 8-DN 9-SSZ 10-STTR 11-SID NAME TTR VV.MM CREATED LAST MODIFIED SIZE INIT MOD ID NAS 00E10A 01.00 89/05/23 89/05/23 08:27 23682 23682 0 NASPA NASMSGA 00AA02 01.00 89/01/10 89/01/10 14:21 12665 12665 0 NASPA PROCOMM1 005B03 01.00 87/12/20 87/12/20 12:07 6825 6825 0 TSTBSSG PZAPPIT 01400C 01.00 89/10/13 89/10/13 08:56 4047 4047 0 TSTBSSG CT515 008203 01.00 88/10/27 88/10/27 09:06 4017 4017 0 TSTBSSG - - - - - - - - - - - - - - CONTINUED - - - - - - - - - - - - - - - - * * * * * * * * * * * * * * * * * * * * * * * * FIGURE TWO. ILLUSTRATION OF REVIEW-DATA MODE. This shows the REVIEW of some data. The actual data is unrelated to REVIEW (but it may be instructive to veteran PDS users). Our purpose is to show the REVIEW HEADER. Note the COMMAND area where most subcommands will be entered. Also notice the SCROLL amount. TSTBSSG.A.DATA(OLDPTFS) - 01.00 ----------------------- LINE 000001 COL 001 080 COMMAND ===> SCROLL ===> CS 1 10 20 30 40 50 60 70 80 +---+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+ ISPMODE table follows: PDS -- VERSION 8.4 DISP UNIT RECFM LRECL BLKSIZE ALLOCTRK FREETRK SECONDARY FREEDIR SHR 3380 FB 80 3120 3X 4200 89 300 TRK 1224 ENTER OPTION -- DSN=TSY2.SMPPTS,VOL=SER=SMP001 MEM=UZ60:UZ69999 >outcopy COPY OUTDD=OUTPUT,INDD=SMPPTS S M=UZ65005, UZ65005)) S M=UZ65007, UZ65007)) S M=UZ65008, UZ65008)) S M=UZ65034, UZ65034)) S M=UZ65039, UZ65039)) - - - - - - - - - - - - DATA CONTINUED - - - - - - - - - - - - * * * * * * * * * * * * * * * * * * * * * * * * FIGURE THREE. REVIEW HELP SCREEN FOR PFKEYS. This screen may be entered any time the user is looking at a dataset. The "KEYS" command or a question mark "?" will invoke this panel. An invalid command, such as "U", will return the user to REVIEWing the dataset. TSTBSSG.A.DATA(OLDPTFS) - 01.00 ----------------------- LINE 000001 COL 001 080 COMMAND ===> SCROLL ===> CS 1 10 20 30 40 50 60 70 80 +---+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+ CURRENT PF KEY VALUES --------------------- PFK01 HEL PFK02 ASCII PFK03 END PFK04 SMF PFK05 FIND PFK06 FULL PFK07 UP PFK08 DOWN PFK09 HEX PFK10 LEFT PFK11 RIGHT PFK12 RECALL USE 'HEL' COMMAND OR PF-KEY FOR FULL-SCREEN TSO HELP * * * * * * * * * * * * * * * * * * * * * * * * FIGURE FOUR. GREG PRICE'S CLIST FOR REVIEWING DATA ON TAPES. This CLIST is needed for looking at tape files that do not have a file sequence number of 1. One can see from Greg's comments that the REVIEW command can open new horizons to the programmer. PROC 1 DSN VOLSER(REVIEW) UNIT(TAPE) LBL(BLP) FSN(1) PTF CONTROL NOFLUSH /* /* CLIST TO SEE WHAT IS ON A TAPE VOLUME. /* /* UNLESS AUTOMATIC VOLUME RECOGNITION IS EXPLOITED, USERS WITHOUT THE /* MOUNT ATTRIBUTE WILL NOT GET VERY FAR. CATALOGUED TAPE DATA SETS /* CAN BE REVIEWED DIRECTLY WITHOUT THIS CLIST. UNCATALOGUED /* STANDARD LABELLED DATA SETS CAN ALSO BE REVIEWED DIRECTLY WITHOUT /* THIS CLIST BY SPECIFYING UNIT AND VOLUME ON THE COMMAND, ONLY AS /* LONG AS THE FILE SEQUENCE NUMBER IS ONE (1). THIS CLIST CAN BE /* USED TO REVIEW TAPE LABELS AS WELL AS TAPE DATA FILES. /* /* IN THE EVENT OF ANY ABNORMAL TERMINATION WHICH FLUSHES THE CLIST, /* REVFILE WILL NOT BE FREED, SO PLEASE ENSURE THAT YOU DO NOT /* UNNECESSARILY HOG A TAPE DRIVE. /* IF '&LBL' = 'SL' OR '&LBL' = 'AL' THEN GOTO NOATTR IF &PTF = THEN ATTR REVATTR DSORG(PS) BLKSIZE(32760) RECFM(U) ELSE ATTR REVATTR DSORG(PS) BLKSIZE(7200) RECFM(F B) LRECL(80) ALLOC FILE(REVFILE) DA(&DSN) USING(REVATTR) UNIT(&UNIT) LABEL(&LBL) - VOLUME(&VOLSER) POSITION(&FSN) SHR REUSE FREE ATTR(REVATTR) GOTO REVIT /* USE DCB INFORMATION FROM TAPE LABELS. */ NOATTR: - ALLOC FILE(REVFILE) DA(&DSN) UNIT(&UNIT) LABEL(&LBL) - VOLUME(&VOLSER) POSITION(&FSN) SHR REUSE REVIT: REVIEW REVFILE FILE FREE FILE(REVFILE) END