MVS TOOLS AND TRICKS OF THE TRADE September 1993 Sam Golob MVS Systems Programmer sbgolob@cbttape.org Sam Golob is a Senior Systems Programmer TSO HELP - WITHOUT THE DRAWBACKS. When was the last time you used TSO HELP? Probably five years ago if you're normal. IBM's TSO HELP facility is so ornery and difficult to manage, especially for large help members, that people often give up and don't use it at all. The purpose of TSO HELP is to provide help in using TSO commands. The help is packaged as an individual member of a card-image pds. All the "help" libraries are then concatenated in a ddname called SYSHELP allocated to your TSO session. IBM's HELP program accesses this SYSHELP ddname and displays the text on your screen, awkwardly. For example, once you've passed a screen full of help text, you can't go back and redisplay it. Further, IBM's HELP program hasn't been significantly enhanced in twenty years. Even ten years ago, IBM's HELP was a full-fledged dinosaur. Using TSO HELP is very frustrating, encouraging programmers to give up and try to do without it. When programmers try to escape using TSO HELP, there isn't much of an alternative supplied by IBM. Most people look for a manual to explain a command they don't know. If a manual doesn't exist, they just play with the command and use "programmer's instinct". This is not adequate or satisfying, because one gets a feeling that program documentation should be provided more conveniently, and on line. What's wrong with TSO HELP? I'll mention a few considerations. For one thing, you can't jump around in the help text--you have to look at it sequentially. You can jump to a subcommand sometimes, but only if the help member is so formatted (with equal signs marking the subcommands). For another thing, once you've passed a given point in some help text, you can't scroll back up to see it a second time. To look at text you've passed, you can only interrupt the display with ATTENTION, or go all the way to the end, and then you have to issue the command over again. People tend to lose patience with the whole facility. There is a way, through keywords, to see part of a help member without viewing the whole thing. But this presupposes that the help member is formatted according to IBM's special HELP format. Plain text isn't good enough. All this trouble with TSO HELP isn't necessary. Using a readily available public-domain command called HEL, you can now get effortless full screen scrollable TSO help. HEL is a free program which is yours for the installing. Many of you already have HEL "in house" whether or not you know about it, because HEL, in one version or other, has resided on the CBT MVS Tape for a long time--since 1984. WHAT IS HEL, AND WHERE DID IT COME FROM? What is this wonderful and pleasant HEL? HEL is a TSO command from the CBT MVS Tape (obtainable through NaSPA), which can be found in source code on File 134 (or on File 296 in most older tapes). The HEL load module can be copied from File 135 of the CBT Tape, directly onto your ISPLLIB or some other load library accessible to TSO. Of course, ISPLLIB is only accessible when you're in ISPF, so from TSO READY, you have to use either a STEPLIB, a linklist library, or something similar. In any case, the installation of HEL is an easy job. To use HEL, type: "TSO HEL helpmmbr" from an ISPF command line, or "HEL helpmmbr" from TSO READY. You are instantly treated to a beautiful fullscreen scrollable display that has many useful controls. PF1 will display those controls that have been assigned pfkeys. See Figure 1 for a sample of what you get. HEL has its own HELP member, which can be found on the same file as the source code. If this help member is installed in your SYSHELP ddname concatenation under TSO, you can type: "TSO HEL HEL" and get all the details about how to use HEL. We will soon elaborate further, but let me first tell you where the HEL command came from originally. HEL is a derivative program that was adapted from the REVIEW program, which is a TSO fullscreen browse command that doesn't need ISPF. REVIEW was originally written by Bill Godfrey, who did a great deal of pioneering programming work for the systems programming community. Many of Bill Godfrey's other works can also be found in various places on the CBT MVS Tape. In 1984, Bruce Leland, the "great enhancer" of the famous "PDS" program and a developer of its successor vendor product "PDSTOOLS", adapted the code from REVIEW especially for the purpose of looking at HELP members in a scrollable, positionable way. Bruce's program, called HEL to distinguish it from IBM's program called HELP, solved the nagging problem of not being able to scroll upward when looking at a help member. HEL is fullscreen--you can scroll all ways. HEL was always a companion program to REVIEW, since it was originally derived from REVIEW. (We've discussed REVIEW as part of my September 1992 column in "Technical Support".) These two programs are parallel programs. From the year 1986 and onward, the REVIEW program has been greatly enhanced by Greg Price of Melbourne, Australia (this year's "NaSPA Member of the Year"). Greg felt an obligation, at the same time he was inventing new features for REVIEW, to put parallel enhancements into the HEL program. Finally, growing tired of updating two programs all the time, Greg merged the "code from HEL" (to coin a phrase) into REVIEW so that they both would be one program. In the latest CBT Tapes, HEL is an alias for REVIEW, with a different entry point. HOW TO USE HEL. Enough history. Now let's say a few things about how HEL works. HEL will pull a member out of the libraries concatenated to the SYSHELP ddname. All versions of HEL will create a fullscreen display of the top of the member, when HEL is first invoked. See Figure 1 again. At the top of the screen, you have four input fields. The field marked "HELP MEMBER" can be overtyped to look for a different help member (without leaving the HEL program). The field marked "SUBCOMMAND" can be used to position the help member to a subcommand piece of the help member, marked by an equal sign in the help member source. If there is no such marking in the help member, the viewing position will be unchanged. The "RANGE" field contains a number, or a command of PAGE, HALF, CS or (cursor), to indicate a scroll amount. And finally, the "INPUT" field is the place to type an arbitrary subcommand of the HEL program, such as FIND, TOP, BOTTOM, UP 67, or the like. At this point, most people wishing to view TSO help members would be completely satisfied. (You can scroll up.) However, some newer features of Greg Price's version of HEL are worthy of note. Greg already had these features in the REVIEW command, and they were available to HEL once the two programs REVIEW and HEL were merged. One of these nice features is the subcommand "DIR", which displays a full member list of the SYSHELP ddname concatenation. The DIR subcommand of HEL lists all member names of all pds'es currently in the SYSHELP concatenation. This subcommand was originally written for REVIEW, so that its availability to HEL did not constitute a large coding effort. From the DIR directory list, you can select any member to be viewed. An unexpected advantage of this feature is that if two SYSHELP libraries contain like-named members, you can view either one from the directory list. You aren't forced to look at only the first occurrence of that name in the SYSHELP concatenation. Another dividend of HEL's merging with REVIEW is its pfkey display when PF1 is pressed. REVIEW's enhanced color displays have also been made available to HEL, in the new version. If you're running HEL under ISPF, you can save new pfkey settings in your ISPF profile. For example, to permanently change PF18 to LOCATE (another new command), just type: "PFK18 LOCATE", and the new setting will be saved across HEL invocations, using your ISPF profile dataset. There's lots more that came along from the merger, such as the FINDHEX or FH subcommand to find hex strings. That stuff had been available in REVIEW, and now exists in HEL as well. See HEL's help member when you get a new CBT MVS Tape. PLAIN TEXT. A great advantage of HEL over other TSO help programs is that it can show you SYSHELP members that are plain text. Normally, TSO HELP will only display members which have the special formatted headings: FUNCTION, SYNTAX, OPERANDS. Members without these special headings will not be displayed by TSO HELP. HELP will only generate error messages if you attempt to look at such a member. However, HEL will clearly display all plain-text members of help libraries. Thus, if you are sure your programmers will always use HEL instead of HELP, your documentation problems can be reduced. Existing plain-text descriptions and documentation can merely be copied into the help libraries. They don't have to be reformatted so that TSO HELP will display their contents. Using HEL, an individual can read existing documents which the systems staff has made available to them in the help libraries. Thus, the help libraries can be employed as "teachers for the staff" in a much bigger way. HEL has the great advantage over TSO HELP, because its users often search around the help text using FIND commands. HEL's FIND commands can be issued anytime after the text has been displayed. This is a total advantage over TSO HELP. With TSO HELP, once some text has been displayed, you cannot reposition except sequentially forward. FIND commands work as well for plain text as for formatted TSO help members. HEL also has enhanced FINDing tools, such as FINDHEX (FH) and FINDCHR (or FC, a sort of "find asis" that is case sensitive) as well as a the normal FIND command. Thus HEL can become a tremendous time-saver. The staff will be able to find only the information they need, and they can easily skip the rest. SUMMARY. The main result, when a programming staff switches from TSO HELP to the HEL command, is a greater willingness to use the help members in the SYSHELP concatenation. HEL is a pleasure to use. TSO HELP is extremely frustrating. In addition, the systems staff can include plain-text documentation in SYSHELP, which they couldn't do before. Thus, SYSHELP can become a repository of shop wisdom, which will be accessed by the staff frequently. It just goes to show you that the users can often beat IBM by a mile. Now wouldn't it be nice if some of you readers would go to SHARE or GUIDE and make a requirement to the TSO developers for a full-screen HELP program. Let's see if IBM can beat the features of Bill Godfrey, Bruce Leland, and Greg Price. Good luck in all your efforts to improve things. See you next time. * * * * * * * * * * * * * * * * * * * * * * * Figure 1. This is an illustration of a full screen of data from HEL. It just so happens that we're showing help information for the REVIEW command. Notice that in this version of HEL (from Greg Price) there are four input fields. You can overtype the "HELP MEMBER" field to look at a different member. The "INPUT" field allows the typing of an arbitrary command. If you overtype the "SCROLL AMOUNT" field, you can change its default value, and the "SUBCOMMAND" field will position you to a subcommand's position in the help text, if it has been properly marked out with equal signs, according to TSO HELP member formatting rules. HELP MEMBER==> REVIEW SUBCOMMAND==> LINE 1 COL 1 80 INPUT===> SCROLL ===> CS 1 10 20 30 40 50 60 70 80 +---+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+ )F Function - The REVIEW command allows a data set to be examined at a 3270 TSO terminal in full screen mode. Both disk and tape files may be REVIEWed. If a PDS without a member is specified then a member selection list is displayed. Load module members with a residence mode of ANY are shown in high intensity or red. SCLM-managed members are flagged with an equals ('=') sign. A 'K' may be shown in the "ruler" heading line to denote the first and last, or only, column(s) of record keys. On colour terminals the portion of the "ruler" line corrsponding to records keys is shown in red. If the record format indicates printer carriage control characters then an 'A' or an 'M' as appropriate may be shown in column 1 of the "ruler" heading line. It is intended that the installation authorize 'REVVSAM' to allow the REVIEWing of VSAM components for problem diagnosis by programming support staff. Normally, VSAM KSDS, ESDS and RRDS clusters can be REVIEWed without this authorization by specifying the cluster name as the data set name. )X Syntax - REVIEW 'dsname' UNIT('unit') VOLUME('volume') QUICK DATA TOP('rel-addr') SUBSYS('subsys') * * * * * * * * * * * * * * * * * * * * * * * Figure 2. Some of the controls of the HEL command are displayed here. These will show the basic richness of HEL's capabilities. Greg Price's latest version has even more snazziness. SYNTAX - HEL COMMAND THE SCREEN WILL NORMALLY CONTAIN 20 RECORDS, ONE PER LINE, 80 CHARACTERS PER LINE. SUBCOMMANDS : ASIS - LEAVE LOWER CASE LETTERS IN LOWER CASE BOTTOM - DISPLAY THE LAST RECORDS CAPS - TRANSLATE LOWER CASE LETTERS TO CAPS COMMAND - DISPLAY A DIFFERENT HELP COMMAND DOWN - DISPLAY RECORDS BELOW THOSE ON THE SCREEN END - END THE COMMAND FIND - DISPLAY A RECORD CONTAINING A SPECIFIED STRING HELP - DISPLAY HELP INFORMATION HEX - SWITCH HEXADECIMAL FORMATTING ON/OFF. LEFT - DISPLAY DATA TO THE LEFT LIST - DISPLAY A SPECIFIED RECORD NUMBER MEMBER - DISPLAY A DIFFERENT HELP COMMAND PFKNN - CHANGE DEFINITION OF PF KEY NN. RIGHT - DISPLAY DATA TO THE RIGHT SUBCOM - DISPLAY A SUBCOMMAND OF THE CURRENT MEMBER TOP - DISPLAY THE FIRST RECORDS TSO - ISSUE A TSO COMMAND UP - DISPLAY RECORDS ABOVE THOSE ON THE SCREEN WHEN 'UP' OR 'DOWN' DOES NOT SPECIFY HOW FAR UP OR DOWN, THE 'RANGE' VALUE IS USED. THIS VALUE IS ALWAYS DISPLAYED NEAR THE TOP OF THE SCREEN AND CAN BE CHANGED BY MOVING THE CURSOR OVER THE VALUE AND TYPING IN A NEW VALUE. THE NEW VALUE WILL REMAIN IN EFFECT UNTIL THE COMMAND ENDS OR UNTIL YOU CHANGE IT AGAIN.