MVS TOOLS AND TRICKS OF THE TRADE May 1990 Sam Golob MVS Systems Programmer sbgolob@cbttape.org THE PDS PROGRAM PRODUCT, PART 2 This month, I'd like to continue our mini-series featuring the marvelous "PDS" product that is found on the CBT Mods Tape. All of these discussions also pertain to PDS's vendor-supported successor, PDS/E (if you happen to have it). In this column, my emphasis is mostly on products that are free, first. The object is for ALL MVS shops to benefit, regardless of budget. Anyone who has extensively used PDS or PDS/E will immediately understand why we should devote a lot of attention to it. It is a multi-purpose time saver and life saver in our business. PDS is found on the CBT MVS Mods tape that is obtainable from NaSPA (414) 423-2420, or from SPLA at the University of Miami in Florida (305) 284-6257. The PDS/E people usually have an ad in this magazine. PDS is easy to get, and is not hard to install. (One has to use 3 files on the CBT tape.) A small effort to obtain PDS and install PDS, will pay big dividends almost immediately. I have used PDS for quite a few years, and PDS/E since before it's been out. (I was chief alpha- and beta-tester for PDS/E.) In spite of my long exposure to both products, I can practically testify that I learn some new way to use them, for shop-required purposes, just about every single working day. To get PDS, version 8.3 (or 8.4, which may be available by the time you read this), you have to obtain a RECENT CBT Tape from NaSPA, from SPLA, or you may make a copy if one of your friends has one. (Remember, this stuff has no restrictions.) The PDS product lives on File 182. Necessary utilities that work together with PDS, live on Files 296 and 112. The CBT Tape materials are now online, at www.cbttape.org. PDS install is the assembly-link of a load module, and the copying of ISPF panels and a message member into the appropriate libraries for your ISPF session to use. Assembly and linkedit of the auxiliary load modules from files 296 and 112 completes the installation. Options for tailoring the main load module can be adjusted by using conditional assembly globals that are located in members #PDSGEN and #PDSGENB of file 182. That's it. After the PDS version 8.3 or 8.4 install, to check which options you have installed, type the commands: CONTROL GLOBAL, or CONTROL ALLGLOBAL. The first command will display which of your "gen" options differ from the defaults. The second command will display all options that have been set (this is a long list). With PDS/E, the equivalent command is: CONTROL DEFAULTS. PDS is executed as a TSO command, or as a dialog manager option under ISPF. If ISPF is present in the TSO session, the two modes may be toggled back and forth. PDS may also be executed recursively under ISPF if a command table entry is set up to invoke it (see my May 1989 column). PDS comes with loads of documentation and a TSO help member. The documentation distributed with "public PDS" is extensive, but since the product has so many features, you usually have to dig to discover an EXISTING FACILITY that you didn't know you actually had. PDS/E has a completely organized user manual (which took enormous effort to create, as you may well imagine). TODAY'S TOPIC. One purpose of this mini-series is to point out features of PDS that most users haven't noticed. This month, we will talk mainly about its LIST function, which is for looking at all kinds of data objects. LIST under PDS, can do much, much more than that name implies. Personally, it took me a long time to "discover" the LIST subcommand, because I did not realize that it provides a good look at LOAD MODULES and other "strange" objects on disk files. I had fooled myself into thinking that it was something like the old TSO LIST command. PDS's LIST can show MUCH more. I've learned over and over again that one can NEVER assume that "simple" PDS functions are limited. While studying the features of PDS "LIST", one should also bear in mind that the extremely useful "FIND" and "REPLACE" subcommands are related to LIST. A user who has full command and possession of these three subcommands has enormous power at his disposal. Some of this power may not easily be had with any existing utility that I know of. Under PDS/E, the DISASSEMBLE and DELINK functions are also related to the LISTing of load modules. The PDS "LIST" subcommand has a number of options, which are shown in Figure One. These are divided into two categories, which we can call "formatting options" and "selection options". Formatting options of LIST will change the format of the command's output. When one of these LIST formatting options is used during a PDS session, that option remains in place for the remainder of the session, until it is changed by another LIST command with a different formatting option. We should also know that any FIND or REPLACE commands executed subsequently, will display their output in the format of the latest LIST execution. This is a useful fact, that we will later discover to be a powerful tool. The LIST selection options will limit the extent of the display or search to selected parts of the data object to be viewed. LIST selection options will help the user to "zero in" on just what he wants to look at. PDS provides a healthy variety of these. The rest of the way, we shall try to explain both types of LIST options, and we hope to show how they can be real power tools in your hands. A full explanation of LIST options can be found in Figure Two, (which is a reprint from the TSO HELP member for PDS). Let's start with the formatting options, which are the foundation for any discussion of LIST under PDS. LIST Formatting Operands: BLOCK / DUMP / LBLOCK / LDUMP / NUM / SNUM / NONUM We shall summarize these options in a nutshell. Then we shall show how they can be employed by us, to do powerful jobs. This then, is a quick description of the LIST formats: BLOCK displays EBCDIC. DUMP displays HEX. LBLOCK and LDUMP display LOGICAL structures, while BLOCK and DUMP display PHYSICAL blocks. A "power thought" at this point is that if BLOCK or DUMP is in effect, a FIND command (which locates strings of data) or a REPLACE command (which does string replacements in place) on a load module will also discover data in the ESD and IDR parts of the load module. If LBLOCK or LDUMP is in effect currently, only the "text" part of the load module will be searched or changed by the FIND and REPLACE subcommands. NUM, SNUM, and NONUM are for source-type files, FB or VB. The purpose of the NUM option is to re-show any line numberings at the beginning of the data to make these more visible, if that is what is desired by the user. NONUM does not reformat the display. SNUM discards record sequence numbering when the data is displayed. So let's look at some pictures. Figure Three shows a list of a load module in straight "DUMP" format. All data blocks of the entire load module are shown, including the blocks containing the ESD and IDR records. Notice that there are two sets of displacement numbers. The leftmost set of displacements starts from the beginning of the data display and continues across block boundaries. The set of numbers further to the right, chronicles displacements into each data block, and is reset at block boundaries. I must emphasize that in the straight DUMP format, you do not get accurate displacements from the beginning of the executable code--these are PHYSICAL BLOCK DISPLAYS ONLY. What happens, is that the displacements of the load module's initial blocks are added in. This format is most useful when you want to examine the "control" parts of the load module data. The LDUMP format covers the more usual situation that we have. An illustration of the LDUMP format in the case of a load module is shown in Figure Four. Notice that the bottom of the display indicates that the load module pds member contains 6 data blocks. However, only one block is shown by the display. That block is the executable code. Displacements into the data blocks shown by the LDUMP format are the ones we are familiar with. They start at the load point of the load module and continue from there. If the format of the data is VB (variable blocked), the LDUMP format will show only the "logical" data portion, and not the "control" portion (the BDWs and the RDWs) of each records. The LDUMP format is the format to be used when you are not examining the raw physical data, but when you are more oriented to discovering HOW THE DATA WORKS. Figure Five shows the same load module in LBLOCK format. It is obvious that since the display of the data is in EBCDIC, this format is not so well suited for displaying load modules, but is more suited for written text type data. It may be useful for load modules and other "hex" type data when you want to search for embedded messages, and you don't want to look at the large volume of pure hex data that you'd see with the LDUMP format. BLOCK format is similar, but it shows the "control" parts of the data also. BLOCK format is useful if you want to LOOK FOR CHARACTER STRINGS in the "control portion" of a data object. LIST, of course, is also very handy for displaying character-type data, and for source files and documents. These are its more obvious uses, and all the LIST options are applicable to this data also. For our article, I merely wish to emphasize the more unusual applications of LIST, so our readers become aware of more of its power. Now, we'll say a few words about the LIST selection options, and then I'll let you go on and read another article. For load modules, the MODULE and OFFSET keyword options are most valuable to know about. If one has a large load module (IEANUC01 comes to mind) it is not normally desired to LIST the whole thing. The MODULE keyword parameter (see Figure Two for details) allows you to list only one CSECT of the huge monster, or several CSECTs that you may desire to look at. One might add the OFFSET keyword to start a LIST display at a location in the data that is not at the beginning of what would normally be displayed. A display that is started at an OFFSET, will continue from there, to the end of the data selected for display. One uses the SKIPREC and MAXIN keyword parameters of LIST to display some of the data from the middle of a file, if it is known how far into the file that the desired data is. SKIPREC causes you to skip nnnnnn records (logical or physical, depending on display format) before you start the display. MAXIN causes LIST to display only the number of further records specified in its operand. One employs the MAXOUT keyword to start at the beginning of the desired data, and go only a limited distance into it. The operand of the MAXOUT keyword will specify a number of records (or blocks in the case of a physical record display format). This keyword will limit the display, starting from the beginning of what would normally be shown if MAXOUT had not been specified. SKIPCOL and MAXLEN are keywords that force the display to start after the beginning of a record, and end before its end. It is recommended that you play with these keywords after PDS or PDS/E is installed at your shop. Please bear in mind that the "selection" operands of LIST apply to the "FIND" and "REPLACE" subcommands of PDS and PDS/E also. And that's it. Be creative. See you next month. Please let me know of any "PDS(/E)" Newsletter ideas that you have. My phone number is . Thanks. * * * * * * * * * * * * * * * * * * * * * * * FIGURE ONE. LIST Syntax. This panel shows the LIST syntax, which is applicable to SOURCE-type files, fixed or variable blocked, and to LOAD MODULES and RECFM=U files. This syntax applies equally to PDS 8.3 and to PDS/E, but the panel comes from the PDS/E syntax error prompter. Both PDS 8.x and PDS/E have more detailed information in the TSO HELP member. PDS/E has a complete user manual describing all of its subcommands in detail. ------------------------------ List Syntax Error ------------------------------ OPTION ===> PDS844E Syntax error: INVALID KEYWORD Incorrect command syntax; please correct and reenter after LIST C1LG10 ===> Operands: NUM / SNUM / NONUM / LBLOCK / LDUMP / BLOCK / DUMP MAXIN(num) MAXLEN(num) MAXOUT(num) SKIPCOL(num) SKIPREC(num) Defaults: NUM or the previous LIST/FIND/REPLACE format * * * * * * * * * * * * * * * * * * * * * * * FIGURE TWO. This is the complete LIST portion of the TSO HELP member for PDS and PDS/E. =LIST=L=LI=LIS )F Example - LIST mema:memb The LIST subcommand displays data from a member. Unprintable characters for 3270-type devices are translated to periods before they are displayed. The LIST formats are NUM, SNUM, NONUM, LBLOCK, LDUMP, BLOCK and DUMP; for load modules, the NUM, SNUM and NONUM formats are equivalent to the LDUMP format. The default format is initially NUM; however, each time a format operand is entered on a LIST, FIND or REPLACE subcommand, the value entered is used as the output format for subsequent LIST, FIND and REPLACE subcommands. Also, note the following: A. Formats NUM, SNUM and NONUM limit the display length for logical records to 256 characters. B. Formats BLOCK and DUMP apply to physical records; the other formats apply to logical records; and for load modules, LBLOCK and LDUMP formats apply to CSECT data. )X SYNTAX - LIST member NUM/SNUM/NONUM/LBLOCK/LDUMP/BLOCK/DUMP OFFSET(Hx) MODULE(Partm) SKIPREC(n) MAXIN(n) MAXOUT(n) SKIPCOL(n) MAXLEN(n) ALIASES - L, LI, LIS, LIST DEFAULTS - member, NUM or previous LIST/FIND/REPLACE format REQUIRED - none. )O OPERANDS - member - optional, specifies the name of the member(s) to be listed. Default member names, member lists, member name ranges and member name patterns are allowed; for more information, enter HELP GROUP. LIST format keywords are as follows: ))NUM - The line number field (the last 8 bytes of a fixed- format record or the first 8 bytes otherwise) of each logical record is examined; if the field is not numeric, formatting is switched to NONUM mode for the remainder of the member. For SPF-saved members, the high-order six digits of the line number field is formatted; otherwise, the low-order six digits of the line number field is formatted by suppressing leading zeroes. The line number segment is followed by a blank and up to 249 characters of data from a logical record. ))SNUM - The line number field (the last 8 bytes for a fixed- format record or the first 8 otherwise) is discarded. Up to 256 bytes from a logical record are displayed. ))NONUM - Up to 256 bytes from a logical record are displayed. ))LBLOCK - Logical records are formatted with two hexadecimal offsets (displacement in the member and displacement in the logical record) and segments of 64 characters surrounded by asterisks. Note: for load modules, only CSECT data will be displayed and if the partial name Partm is entered in a MODULE operand, only those CSECT or ENTRY names matching Partm will be displayed. CSECT records are formatted with two hexadecimal offsets (a module offset and a CSECT offset) and segments of 64 characters surrounded by asterisks. ))LDUMP - Logical records are formatted with two hexadecimal offsets (displacement in the member and displacement in the logical record), segments of up to 32 characters of hexadecimal data and up to 16 bytes of equivalent characters surrounded by asterisks. Note: for load modules, only CSECT data will be displayed and if the partial name Partm is entered in a MODULE operand, only those CSECT or ENTRY names matching Partm will be displayed. CSECT records are formatted with two hexadecimal offsets (a module offset and a CSECT offset), segments of up to 32 characters of hexadecimal data and up to 16 bytes of characters surrounded by asterisks. ))BLOCK - Physical records are formatted with two hexadecimal offsets (displacement in the member and displacement in the physical record) and segments of 64 characters surrounded by asterisks. ))DUMP - Physical records are formatted with two hexadecimal offsets (displacement in the member and displacement in the physical record), segments of up to 32 characters of hexadecimal data and up to 16 bytes of equivalent characters surrounded by asterisks. LIST control keywords are as follows: ))OFFSET(Hx) - for LBLOCK and LDUMP formats only; Hx may be entered as a 1 to six digit hexadecimal number to specify the module offset at which the display is to begin. If both MODULE AND OFFSET keywords are entered, the offset applies to each module selected. ))MODULE(Partm)-for LBLOCK or LDUMP formats only; Partm may be entered as a 1 to 8 byte partial external name to limit the CSECT or ENTRY names to be displayed to those matching the partial name Partm. If the form MODULE(*) is used, the previous partial name entered on any MODULE keyword will be used. If both MODULE AND OFFSET keywords are entered, the offset applies to each module selected. ))SKIPREC(n) - n is coded as 0 through 9999999 to specify the number of logical records (physical records for BLOCK or DUMP formats) to ignore at the beginning of a member. ))MAXIN(n) - n is coded as 0 through 9999999 to specify the maximum number of logical records (physical records for BLOCK or DUMP formats) to input for a member after satisfying any SKIPREC operand. ))MAXOUT(n) - n is coded as 0 through 9999999 to specify the maximum number of logical records (physical records for BLOCK or DUMP formats) to output for a member. ))SKIPCOL(n) - n is coded as 0 through 99999 to specify the number of columns to ignore at the beginning of each logical record (physical record for BLOCK or DUMP formats). Note: for NUM or SNUM output format with record format V, SKIPCOL(0) refers to the first data position after the line number field. ))MAXLEN(n) - n is coded as 0 through 99999 to specify the maximum length of a logical record (physical record for BLOCK or DUMP formats) to display. * * * * * * * * * * * * * * * * * * * * * * * FIGURE THREE. This is a LIST of a LOAD MODULE in DUMP FORMAT. Notice that the displacements in the entire module are measured from the beginning of the first data block, and NOT from the beginning of the executable code. This represents display of the PHYSICAL data. We would have needed the LDUMP format of Figure Four to display logical displacement values in the way we are used to seeing and using these values. FIND and REPLACE commands which will follow this LIST, can affect ALL of the data, because the scan is PHYSICAL, and not logical. Even the IDR and ESD data can be scanned and replaced using this format. If the data being listed were in VB format instead of in RECFM=U, physical blocks, including block descriptor words (BDWs) and record descriptor words (RDWs) would have been displayed by LIST. - DSN=TST2SSG.LOAD,VOL=SER=TSO001 MEM=APSUX01 >list apsux01 dump DUMP RECORD 1 LENGTH 24 TTR 00D809 000000 0000 20800000 00010010 C1D7E2E4 E7F0F140 *........APSUX01 * 000010 0010 00000000 00000536 *........* DUMP RECORD 2 LENGTH 251 TTR 00D80A 000018 0000 80FA0100 00000000 00000000 00000000 *................* 000028 0010 00000000 00000000 00000000 00000000 *................* 000038 0020 00000000 00000000 00000000 00000000 *................* 000048 0030 00000000 00000000 00000000 00000000 *................* 000058 0040 00000000 00000000 00000000 00000000 *................* 000068 0050 00000000 00000000 00000000 00000000 *................* 000078 0060 00000000 00000000 00000000 00000000 *................* 000088 0070 00000000 00000000 00000000 00000000 *................* 000098 0080 00000000 00000000 00000000 00000000 *................* 0000A8 0090 00000000 00000000 00000000 00000000 *................* 0000B8 00A0 00000000 00000000 00000000 00000000 *................* 0000C8 00B0 00000000 00000000 00000000 00000000 *................* 0000D8 00C0 00000000 00000000 00000000 00000000 *................* 0000E8 00D0 00000000 00000000 00000000 00000000 *................* 0000F8 00E0 00000000 00000000 00000000 00000000 *................* 000108 00F0 00000000 00000000 000000 *...........* DUMP RECORD 3 LENGTH 18 TTR 00D80B 000113 0000 801102F5 F6F6F5F2 F9F5F0F8 40010090 *...566529508 ...* 000123 0010 042F *..* DUMP RECORD 4 LENGTH 21 TTR 00D80C 000125 0000 80148480 0100F5F6 F6F8F9F6 F2F0F140 *..d...566896201 * 000135 0010 02019004 2F *.....* DUMP RECORD 5 LENGTH 20 TTR 00D80D 00013A 0000 0D000000 00040000 06000000 40000538 *............ ...* 00014A 0010 00010538 *....* DUMP RECORD 6 LENGTH 1,336 TTR 00D80E 00014E 0000 47F0F06A 10C1D7E2 E4E7F0F1 404040F8 *.00Ý.APSUX01 8* 00015E 0010 F84BF0F5 F3F5F6F6 F560F2F7 F5404040 *8.0535665-275 * - - - - - D A T A M I S S I N G - - - - - 0005CE 0480 504640E0 504659E0 C50847D0 C4701FFF *&. \&..\E..}D...* 0005DE 0490 58D0D004 58E0D00C 980CD014 07FED7C1 *.}}..\}.q.}...PA* 0005EE 04A0 E3C3C840 C1D9C5C1 406040C1 D7E2E4E7 *TCH AREA - APSUX* 0005FE 04B0 F0F14040 F8F84BE7 E7E7C4BA C4BCC4BE *01 88.XXXD.D.D.* 00060E 04C0 C4C0C4C2 C4C4C4C6 C4C8C4CA C4CCC4CE *D{DBDDDFDHD.D.D.* 00061E 04D0 C4D0C4D2 C4D4C4D6 C4D8C4DA C4DCC4DE *D}DKDMDODQD.D.D.* 00062E 04E0 C4E0C4E2 C4E4C4E6 C4E8C4EA C4ECC4EE *D\DSDUDWDYD.D.D.* 00063E 04F0 C4F0C4F2 C4F40000 00000001 00000002 *D0D2D4..........* 00064E 0500 00000003 0000000C 00000010 0000007F *..............."* 00065E 0510 00000000 000040E2 E3C1D9E3 C3D6D5E3 *...... STARTCONT* 00066E 0520 40D3D6C3 C1D3D9D6 D6D4C1D4 00000000 * LOCALROOMAM....* 00067E 0530 12000000 21200000 *........* 6 blocks in this member * * * * * * * * * * * * * * * * * * * * * * * FIGURE FOUR. This is a DUMP OF LOGICAL DATA in a LOAD MODULE, using the LDUMP FORMAT of LIST. Notice that even though the module contains 6 records, only the executable code is shown. The ESD and IDR records at the beginning of the load module are not considered. Displacement OFFSETS are measured from the beginning of the executable code, in the "normal" way that we are used to. A FIND or REPLACE command which would follow this LIST command, will affect only the executable portion of the load module. If the data being listed were in VB format instead of RECFM=U, LOGICAL RECORDS would be displayed in HEX by this format of the LIST command. BDWs and RDWs would not be shown. >list apsux01 ldump AT 000000 CSECT APSUX01 LENGTH 000536 000000 0000 47F0F06A 10C1D7E2 E4E7F0F1 404040F8 *.00Ý.APSUX01 8* 000010 0010 F84BF0F5 F3F5F6F6 F560F2F7 F5404040 *8.0535665-275 * - - - - - D A T A M I S S I N G - - - - - 000480 0480 504640E0 504659E0 C50847D0 C4701FFF *&. \&..\E..}D...* 000490 0490 58D0D004 58E0D00C 980CD014 07FED7C1 *.}}..\}.q.}...PA* 0004A0 04A0 E3C3C840 C1D9C5C1 406040C1 D7E2E4E7 *TCH AREA - APSUX* 0004B0 04B0 F0F14040 F8F84BE7 E7E7C4BA C4BCC4BE *01 88.XXXD.D.D.* 0004C0 04C0 C4C0C4C2 C4C4C4C6 C4C8C4CA C4CCC4CE *D{DBDDDFDHD.D.D.* 0004D0 04D0 C4D0C4D2 C4D4C4D6 C4D8C4DA C4DCC4DE *D}DKDMDODQD.D.D.* 0004E0 04E0 C4E0C4E2 C4E4C4E6 C4E8C4EA C4ECC4EE *D\DSDUDWDYD.D.D.* 0004F0 04F0 C4F0C4F2 C4F40000 00000001 00000002 *D0D2D4..........* 000500 0500 00000003 0000000C 00000010 0000007F *..............."* 000510 0510 00000000 000040E2 E3C1D9E3 C3D6D5E3 *...... STARTCONT* 000520 0520 40D3D6C3 C1D3D9D6 D6D4C1D4 00000000 * LOCALROOMAM....* 000530 0530 12000000 2120 *......* 6 blocks in this member * * * * * * * * * * * * * * * * * * * * * * * FIGURE FIVE. LBLOCK FORMAT for a LOAD MODULE only shows data in EBCDIC form. "Unprintable" data which might cause trouble when a display is attempted to a terminal, is converted into periods. This form of display may be of limited usefulness for load modules, and might only serve to highlight character strings in them. For RECFM=VB source-type data, this format would be extremely useful. >list apsux01 lblock AT 000000 CSECT APSUX01 LENGTH 000536 000000 0000 *.00Ý.APSUX01 88.0535665-275 ...............................* - - - - - D A T A M I S S I N G - - - - - 000440 0440 *K.....K.....K..'.%k*.=k...K.&.E..\..&\&..\.. \&.....D......\..ÿ\* 000480 0480 *&. \&..\E..}D....}}..\}.q.}...PATCH AREA - APSUX01 88.XXXD.D.D.* 0004C0 04C0 *D{DBDDDFDHD.D.D.D}DKDMDODQD.D.D.D\DSDUDWDYD.D.D.D0D2D4..........* 000500 0500 *..............."...... STARTCONT LOCALROOMAM..........* 6 blocks in this member