MVS TOOLS AND TRICKS OF THE TRADE November 1991 Sam Golob MVS Systems Programmer sbgolob@cbttape.org EXPLOITING PARTITIONED DATASET DIRECTORY FIELDS: PART III. INTRODUCTION TO PART III. Much dataset activity related to MVS computing deals with the partitioned dataset structure. The partitioned dataset, which can be pictured as the "generalized library" construct under MVS, consists of a directory with "member names", followed by the member data itself. The partitioned dataset directory entries can play a large part in MVS program execution when the partitioned dataset is a "load library". Members of a "load library" pds are the disk storage copies of executable programs, known as "load modules". The information necessary to execute a load module under MVS is not all contained in the data portion itself. Essential program loading information used by the MVS "program fetch" component, is stored in pds directory "user fields" that we talked about in the first two parts of this series. Today we shall conclude our pds directory discussion with a look at load module directory "user" fields that can crucially affect program execution. A STRUCTURAL SUMMARY. We stated in the previous installments that a pds directory entry has 12 required bytes, and up to 62 optional "user" bytes. The required bytes are: 8 bytes - member name, 3 bytes - start TTR location of member data, and 1 byte - 3 bits of flags, and 5 bits stating the number of halfwords of user bytes (from 0 to 31 halfwords) in this directory entry. See Figure One for details. Before getting to look at a load module, I'd just like to summarize the "physical" and "logical" structures of partitioned dataset directories. These are the "directory block" (physical) and "directory entry" (logical) structures respectively. Directory blocks have a FIXED DCB structure of RECFM (F), KEYLEN (8) and BLKSIZE (256), regardless of the DCB structure of the data portion (the pds MEMBERS). This makes each directory block 264 characters in length, which is inflexible. Within a directory block, however, there might be several "directory entries" that can vary considerably in structure. A single directory block can contain as many complete directory entries as will fit into the block. Overflow cannot be tolerated; a directory entry cannot span two blocks. Since individual directory entries may vary in size, there is no fast rule as to how many entries will fit into a directory block. All member names in a pds directory are sorted in ascending collating sequence. The 8-byte KEY of each directory block contains the member name of the highest member whose entry is in that block. The first DATA byte of any directory block is a binary one-byte value that indicates the length of meaningful directory entry data in each block (not counting itself). The value in this byte may go from X'00' (decimal 0) to X'FF' (decimal 255). One practical result of this information: It might pay NOT to keep ISPF statistics for the members of your ISPF panel libraries. Without statistics (which make each directory entry bigger), more directory entries can be packed into each directory block. ISPF response time may be noticeably decreased for large panel libraries, because fewer physical blocks have to be searched to find a given member, and ISPF dialogues involve a lot of panel searches. When you allocate a partitioned dataset it is important to allow enough directory blocks to hold your member data. Rather than reallocating a new dataset with more directory blocks when the directory is full, tools exist which allow expansion of pds directories to create more directory blocks "on the fly". One of the best tools is the PDS Program Product (Version 8.4) on File 182 of the CBT MVS Tape (obtainable from NaSPA (414) 423-2420 or SPLA (305) 284-6257 for a handling charge). The "PDS Product" has a subcommand ("FIXPDS EXPANDDIR (nnn)" ) that will accomplish dynamic directory block expansion or reduction in a pds rather effortlessly, with almost no environmental impact. This tool and its vendor-supported successor, PDS/E Sysprog Utilities (if you already have it), can simplify and automate any of the directory entry manipulations we will talk about here, accurately making these changes for single or multiple members at a time. Both products have a command called "DIRENTRY" which displays and formats directory entries. See Figure Two for a DIRENTRY display. MANIPULATION OF A LOAD MODULE DIRECTORY ENTRY. At this point we can show how to flip some bits in a load module directory entry and get some results. You'll need a tool to do the bit flipping. Take your choice. You can use IBM's superzap (AMASPZAP) from SYS1.LINKLIB if you know how to display the location of the directory blocks before making changes to them. My favorite tool for bit flipping is the UCLA fullscreen ZAP program from the CBT MVS Utilities Tape: Files 134, 135, or 300, which has a string "find" facility. The PDS Program Product "ATTRIBUTE" subcommand, with keywords, will accomplish the desired effect more accurately without direct zapping. I don't care how you flip the bits. I'll just show you what bits to flip. Look at the load module in Figure Two, named CNMCNETV. This load module is reentrant, reusable, and authorized. For argument's sake, suppose that reentrancy were not desired (perhaps we made a mistake in the linkedit parms). Let's look at Figure One to see where "reentrancy" is shown. We could turn off the "reentrant" attribute by going into the first attribute byte at +14 into the directory entry, turning off the B'10000000' bit. The value X'C3' at +14 would be changed to X'43'. The load module would then be "reusable" and "authorized" only. Often, "reusability" is on when "reentrancy" is turned on during linkage editing. Possibly reusability is also not desired for our module. By referring to the DSECT description in Figure One, we see that the reusability attribute for the load module is indicated by the B'01000000' bit at +14 into the directory entry. We'll turn off the reusability bit, now changing the contents of the first attribute byte from X'43' to X'03'. You get the idea. Authorization of a load module results from using the linkage editor control card "SETCODE AC(1)" during linkage editing. (For the module to actually execute authorized, its load library must be an authorized library. The library must be in an authorized LINKLIST concatenation, or it must appear in the APF authorization table of SYS1.PARMLIB at IPL time, or be SYS1.LINKLIB or SYS1.SVCLIB on the active res pack.) As you can see from Figure One, the location of the authorization byte (ON is X'01' and OFF is X'00') may vary sharply depending on some other factors. If the module is an ALIAS, is "scatter loaded", or if it contains a "System Status Indicator" (an "SSI"), the displacement of the authorization byte into the directory entry will be different. For a given load module, you have to examine the DSECT in Figure One carefully to determine where the authorization byte is, before attempting to turn it on or off. All this knowledge is useful, and it can be extremely helpful in some emergency situations, but doing such bit flipping accurately can be cumbersome and somewhat error prone. Practically speaking, you can use the "PDS Program Product" from the CBT Utilities Tape, or the "PDS/E" product if you have it. You can point "PDS" to the load library containing your modules, and issue its "DIRENTRY" and "ATTRIBUTE" subcommands. For example (using load module CNMCNETV), to turn off reentrancy, enter: "ATTRIB CNMCNETV NORENT". To turn off reusability, enter: "ATTRIB CNMCNETV NOREUS". And to turn off authorization, just enter: "ATTRIB CNMCNETV NOAUTH". These parameters may be combined: "ATTRIB CNMCNETV NORENT NOREUS NOAUTH" will turn all those attributes off at once. The ATTRIBUTE subcommand of "PDS" can turn ON linkedit attributes as well: "ATTRIB CNMCNETV RENT REUS AUTH" will turn all of these attributes on, accurately. Please study the two illustrations thoroughly, because much information is contained in them. Good luck in all your work. I hope to be seeing you next month. * * * * * * * * * * * * * * * * * * * * * * FIGURE ONE. A DSECT Description of Partitioned Dataset Directory Entries for Load Modules. Load modules use the User Fields of the directory entry in a special way that is defined by the Linkage Editor and the MVS Program Fetch component. Labels in this illustration are from source code in the PDS V8.4 product, module @DIALOG. This source code is on the CBT Tape, File 182. For more standard names, see macro IHAPDS on SYS1.AMODGEN. DIRLINK DS 0F *** DIRECTORY AREA MAPPING *** * DIRNAME DS CL8 Member Name DIRTTR DS XL3 TTR of beginning of the Member DIRFLAG DS X Flags for required direntry fields. * DIRCALIS EQU B'10000000' This member is an alias. DIRCTTRN EQU B'01100000' There is more than 1 TTR to update DIRCUDHW EQU B'00011111' Halfword count bits. Size of user bytes. * DIRUSER DS XL62 Directory USER Fields (62 Bytes Maximum) * ORG DIRUSER FOLLOWING FOR LOAD MODULES DIRSTART DS XL4 TTR of first Text block DIRNOTE DS XL3 TTR of Notelist DIRNOTE# DS X Number of Notelist entries DIRATTR DS XL2 Member Attributes * EQUATES for First Byte ORG DIRATTR DIRAT1ST DS X DIRRENT EQU B'10000000' Reentrant (RENT) DIRREUS EQU B'01000000' Reusable (REUS) DIROVLY EQU B'00100000' Overlay Module (OVLY) DIRBADO EQU B'11001100' OVERLAY CONFLICTS - Not RENT, REUS, * Only Loadable, or SCTR. DIRTEST EQU B'00010000' TEST DIRLOAD EQU B'00001000' Only Loadable (OL) DIRBADL EQU B'00000100' ONLY LOADABLE CONFLICTS - Not SCTR. DIRSCTR EQU B'00000100' Scatter Load (SCTR) DIRBADS EQU B'10101000' SCATTER LOAD CONFLICTS - Not RENT, OVLY * or Only Loadable. DIREXEC EQU B'00000010' Executable DIRF1 EQU B'00000001' * EQUATES for Second Byte ORG DIRATTR+1 DIRAT2ND DS X DIRNODC EQU B'10000000' NODC (Not Downward Compatible) DIRF2 EQU B'01000000' DIRF3 EQU B'00100000' DIRF4 EQU B'00010000' DIRNOED EQU B'00001000' Not Editable (NE) DIRF5 EQU B'00000100' DIRLKEDF EQU B'00000010' F Level Linkage Editor DIRREFR EQU B'00000001' Refreshable (REFR) * DIRSTORE DS XL3 Size of Load Module DIRTEXTL DS XL2 Length of 1st Text Record DIREPA DS XL3 Entry Point Address * DIRATTR2 DS X ADDITIONAL ATTRIBUTE BYTES: DIRAOSLE EQU B'10000000' VS Linkage Editor created this module DIR2PAGA EQU B'00100000' Page Alignment is required DIR2SSI EQU B'00010000' SSI Information present for module DIRAPFLG EQU B'00001000' APF Information for this module is valid * DIRATTR3 DS X ADDITIONAL ATTRIBUTE BYTES: DIRRMANY EQU B'00010000' RMODE=ANY DIRAA31 EQU B'00001000' AMODE=31 (Alias entry) DIRAA24 EQU B'00000100' AMODE=24 (Alias entry) DIRAM31 EQU B'00000010' AMODE=31 (Main entry) DIRAM24 EQU B'00000001' AMODE=24 (Main entry) * DIRATTR4 DS X Count of RLD Entries after first Text * DIRAPF DS 0XL2 APF (If not SCATTER, SSI or ALIAS) DIREP DS XL3 Entry Point of Main Member DIRREAL DS CL8 Real Name of Member DIRAPF2 DS XL2 APF Information (ALIAS, no SCAT or SSI) DIREND2 EQU * End of ALIAS Section * ORG DIRAPF FOLLOWING IS FOR SCATTER LOADED MODULES. DIRSCLL DS XL2 Length of Scatter List DIRSCTL DS XL2 Length of Translate Table DIRSCET DS XL2 ESDID of First Text Record DIRSCEP DS XL2 ESDID of Entry Point DIRAPF3 DS 0XL2 APF Info (If SCATTER, no SSI and no ALIAS) DIREPSC DS XL3 Entry Point (Main Member) DIRREALS DS CL8 Real Name of Member DIRAPF4 DS XL2 APF Info (SCATTER, no SSI and ALIAS) DIREND3 EQU * End of SCATTER, ALIAS Section * * * * * * * * * * * * * * * * * * * * * * FIGURE TWO. This illustration shows a Load Library directory entry, containing some honest, real-life information about a load module. The display was obtained by the vendor product, PDS/E Sysprog Utilities. You should mentally fit this information together with the DSECT description of Figure One. Load module illustrated is: SYS1.LPALIB(CNMCNETV) rent, reus, ac=1 PDS300A ENTER OPTION -- DSN=SYS1.LPALIB,VOL=SER=S1RES1 MEM= >direntry cnmcnetv PDS143I CNMCNETV Directory entry, length=40 0000 C3D5D4C3 D5C5E3E5 00DF242E 00DF2A00 *CNMCNETV........* 0010 00000000 C3F20002 10021000 00009812 *....C2........q.* 0020 00000111 05300101 *........* PDS262I LOC NAME VALUE DESCRIPTION PDS262I --- ---- ----- ----------- PDS262I 00 PDS2NAME CNMCNETV MEMBER NAME PDS262I 08 PDS2TTRP 00DF24 TTR OF FIRST BLOCK OF DATA PDS262I 0B PDS2INDC 2E 1 TTRS FOLLOW; 14 HALFWORDS OF DATA PDS262I 0C PDS2TTRT 00DF2A,00 TTR OF FIRST TEXT BLOCK PDS262I 10 PDS2TTRN 000000,00 (NOT USED FOR THIS MEMBER) PDS262I 14 PDS2ATR1 C3 REENTRANT; REUS; NOT OVERLAY; NOT TEST PDS262I NOT ONLY LOAD; NOT SCATTER; EXEC; 1 TEXT PDS262I 15 PDS2ATR2 F2 NOT DC; TEXT ORG=0; EP=0; NOT HAS RLDS PDS262I EDIT; NOT TEST; LKED F; NOT REFRESHABLE PDS262I 16 PDS2STOR 528. TOTAL CONTIGUOUS MAIN STORAGE REQUIRED PDS262I 19 PDS2FTBL 528. LENGTH OF FIRST BLOCK OF TEXT PDS262I 1B PDS2EPA 000000 ENTRY POINT ADDRESS PDS262I 1E PDS2FTB1 98 PROCESSED BY OS/VS LINKAGE EDITOR PDS262I SSI INFORMATION IS PRESENT PDS262I APF INFORMATION IS VALID PDS262I 1F PDS2FTB2 12 RMODE ANY; ALIAS AMODE 24; MAIN AMODE 31 PDS262I 20 PDS2FTB3 00 RLD/CONTROL RECORDS AFTER FIRST TEXT BLOCK PDS262I 22 PDSSSIWD 01110530 SSI INFORMATION PDS262I 26 PDSAPFCT 01 LENGTH OF PROGRAM AUTHORIZATION CODE PDS262I 27 PDSAPFAC 01 PROGRAM AUTHORIZATION CODE