MVS TOOLS AND TRICKS OF THE TRADE October 1994 Sam Golob MVS Systems Programmer Sam Golob is a Senior Systems Programmer. Sam can be reached at sbgolob@cbttape.org. Documentation about the CBT MVS Tapes can be found on the web, at http://www.cbttape.org THE "REVIEW" COMMAND REVISITED Several weeks ago, our operations manager Roman Panczyszyn asked me to install the QUEUE program, which is a "free" JES2 spool browser. When I asked him why he specifically wanted QUEUE, even though we also own SDSF, he replied that QUEUE has a "find all" command (called FALL) that only displays "found" lines without showing the others. When you're searching for the history of one specific job while looking through the whole SYSLOG, this is a useful thing to have. After I installed QUEUE for him, he asked me another thing. That's fine for the current SYSLOG, but what about our old SYSLOGs that are archived on datasets and on tape. Can't I have a facility to just display "found" lines for them too? I thought for a moment, and asked: "How do I look at old SYSLOGs on disk and on tape? I use the REVIEW command, a generalized file browsing program that is ideally suited for the task. REVIEW is privately maintained by Greg Price in Australia. I wouldn't have to call IBM and try to get them to change any of their programs. Let me call Greg and see what he has to say." That day, I called Greg in Melbourne. I asked him to try and install a "FIND ALL" facility in REVIEW that is akin to the FALL command in QUEUE. Greg rang me back a week later, telling me that the coding was installed in REVIEW and he would be sending me a tape immediately. In two and a half weeks, the updated REVIEW command was placed on the CBT MVS Tape (Version 379, File 134) and was ready to be distributed to the public. It was also installed at my site, and given to the operations department. Roman has expressed his happiness. As for me, I'd challenge any software vendor to add a new feature with this kind of speed. Incidentally, if you want a new CBT Tape to see all this software, you can order one from NaSPA. (Now you can just download File 134 (REVIEW source) and File 135 (the load modules) from the web site, www.cbttape.org.) A REVIEW OF "REVIEW". What is this REVIEW program, and why is it special? REVIEW is a full-screen TSO command to browse data files. You might ask, "I thought we had ISPF BROWSE for that. Why do we need something else? Can't we get everything we need from IBM?" The answer is that REVIEW doesn't need ISPF services (although it can use them if they're available). Also, REVIEW can do a zillion more things than ISPF BROWSE. It can often do them a lot faster, especially if you're looking at big files. For example: REVIEW can format SMF records and LOGREC records. It can look at VSAM files and at files with I/O errors. REVIEW can now even write some of the records it's looking at, to an output file. REVIEW handles PDS'es nicely. It is capable of "sequentializing" a PDS using all or some of its members, into IEBUPDTE unload format. REVIEW can show you tape files as well as disk files. You can even look at a DB2 tablespace, row by row. Why should we talk about REVIEW now? I've already written about it before. The answer is that REVIEW is evolving, and Greg Price keeps putting more features into it. (It is "a terminal case of creeping featurism", in Greg's words.) The REVIEW command of today is not the REVIEW command of yesterday. There's more to write about, because there's more that you can use. For the rest of this article, we'll mention a few of the lesser known features in REVIEW and show you how to use them. REVIEW comes with good documentation. Its HELP member, plus the comments at the beginning of the source code on CBT Tape File 134, and the document on "undocumented" commands, will guide you through REVIEW's powerful capabilities very completely. A FEW INTERESTING THINGS FOR STARTERS. Let's start with some simple things. Nowadays, there's a lot of file transfer going on between the mainframe and other systems. On IBM systems, the usual means of representing data is EBCDIC. On many other systems, the data representation method is ASCII. If you look at an ASCII file on an EBCDIC system it is complete gibberish. IBM in its "ultimate foresight" has not provided a way to look at ASCII files in ISPF/PDF. However, if you REVIEW an ASCII file on disk or on tape, look at the initial gibberish, and type the command, ASCII, all of a sudden, the file has been translated into ASCII and it makes sense. Type the word ASCII on the command line again, and the representation toggles back to EBCDIC. This also works for tape files. Speaking about tape files, REVIEW makes them almost as accessible as disk files. It helps to have TSO "MOUNT" attribute turned on for this. If the "MOUNT" attribute is turned on, and your TSO session requests allocation of a tape, then the system will prompt the operator to mount the tape. Otherwise, the mount request will usually be blocked. A systems programmer is not helpless regarding the TSO MOUNT attribute. There is an authorized command on the CBT MVS Utilities Tape (File 300) called CPSCB (change the PSCB), which can toggle the MOUNT attribute on and off. Another command (not authorized) called LPSCB (list the PSCB) shows you the state of the PSCB (protected step control block) for your TSO session. Using LPSCB, you can see if MOUNT is off or on for your session. It is my experience that bit settings in the PSCB will take precedence over RACF settings for whether "MOUNT" is turned on or off, because RACF just helps to initialize the PSCB when your TSO session is being started. However, while the session is running, the system seems to refer just to the PSCB, so that altering the PSCB is quite effective in giving you the control you want. In most shops, temporarily acquiring the "MOUNT" attribute should be no problem. See my thoughts on personally authorizing your TSO commands, which are in CBT Tape Files 185 and 186. Once "MOUNT" is turned on, if you REVIEW a cataloged file that is 'File 1' on a standard-labeled tape, then your console operator will immediately get a mount message for that particular volume. When the tape is mounted, REVIEW proceeds to show you the file, almost the same as if it were a disk file. To REVIEW a non-cataloged file on a standard-labeled tape, you use the VOL parameter, as for a non-cataloged disk file. To REVIEW a file which is not 'File 1', please refer to the REVTAPE clist, which is printed in Figure 1. COPYING PARTS OF A FILE. Two new commands were recently added to REVIEW, to relieve some of the frustration that accompanies the use of any browsing program. The problem is that you can see, but you can't touch. The two new commands, CUT and ADD, allow you to touch what you're browsing as well as just to look at it. CUT copies a certain number of lines, via QSAM, to the REVIEW output dataset. ADD does the same as CUT, except that the copied lines are appended to the end of the output dataset. These two commands allow for a considerable amount of flexibility. The copied lines begin from the top of the screen you're positioned to. As currently implemented in REVIEW, any output file that REVIEW sends data to, has to have the ddname of SYSUT2. You can use the "TSO" subcommand of REVIEW while REVIEWing any dataset, to invoke this allocation. For example, you can say: TSO ALLOC FI(SYSUT2) DA(OUTP.SEQ.FILE)) SH REUSE while you're REVIEWING a large dataset. Then you position to the place where you want to start copying lines. To copy 836 lines starting from the current place, just type: "CUT 836" on the command line, and REVIEW will copy that number of lines. If you want to start at a different place in your file, and you want to add 87 more lines to the output dataset, just position yourself there, and type: "ADD 87". Thus, you have "touch and feel" access to the data you're looking at. This works for VSAM browsing also. Just don't give the output dataset SYSUT2 any DCB attributes when you're allocating it as NEW under TSO. Let REVIEW supply the DCB attributes if you're looking at a VSAM file. REVIEW will give the output dataset RECFM(U) when you're copying VSAM records. LOOKING AT DISK AND TAPE LOCATIONS. REVIEW lets you go directly to a relative TTR disk location, or to a relative block tape location. When REVIEWing a dataset, simply enter the command: NEWTOP ttr-value. The ttr-value is usually a 5 or 6-digit number. If you're looking at a tape file, the number will be the relative block of the tape file you're looking at. NEWTOP pretends that the top-of-data is the relative TTR or block address you've specified. For example, "NEWTOP 00001" points to the real top-of-data for a sequential file. "NEWTOP 00101" points to the first record in the second relative track of the file. "NEWTOP 00302" points to the second record in the fourth relative track of the file. If you go to the bottom of a file or pds member you're REVIEWing, REVIEW will display the end-of-file TTR, so you can get some orientation as to what values to use. The abundant REVIEW documentation will help you very much. How can NEWTOP help you recover a file that has I/O errors when you try to access it? You may not be able to recover all of the file, but you'll probably recover most of it. Suppose for simplicity that the bad file is physical sequential. Allocate SYSUT2 to a new file with the same DCB attributes. Then REVIEW the file from the top. Do a FIND on some non-existent string, to force REVIEW to look at every record of the file. When the I/O error hits, go to the preceding TTR and note its last line number. Go back to the top and enter the CUT command with the proper number of lines to copy. Then step through successive TTR locations. Keep entering "NEWTOP ttr" for the next TTR, until you get real data again. Repeat this process for the later data, except that you use the ADD command to append the new data, instead of the CUT command. In this way, you'll recover all of the good data in the file. IN SUM. There's very much more practical everyday utility to be found in the REVIEW command. Look at its HELP member and the other descriptions to be found on the CBT Tape File 134. REVIEW can assist you in many ways you've never previously dreamed of. Spend some time with REVIEW, and I assure you that REVIEW will repay your time, with interest. Good luck. We're monthly again. See you next month. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. This is the REVTAPE CLIST which is shipped together with the REVIEW command in File 134 of the CBT MVS Tape. This CLIST makes it possible to look at tape files which are not the first file on a tape. 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