MVS TOOLS AND TRICKS OF THE TRADE APRIL 2002 Sam Golob MVS Systems Programmer P.O. Box 906 Tallman, New York 10982 Sam Golob is a Senior Systems Programmer. He also participates in library tours and book signings with his wife, author Courtney Taylor. Sam can be contacted at sbgolob@cbttape.org. Information about the CBT MVS Tapes can be found on the web, at http://www.cbttape.org. CBT TAPE SOFTWARE PACKAGING In this new world of the web, I find myself having to "hold the fort" regarding the "old world" of traditional "mainframe" operating system software. But I find myself learning a lot, from watching how some of the "new world people" operate, especially the open source people. I got the idea for this article, by looking at www.mozilla.org, and reading their mission statement. Even though Mozilla operates in the world of web browsers, and I operate in the "free mainframe software" arena, there is a lot in common, and a lot that I can learn from them. The world is constantly changing, and yet there are many things that are the same. You need constancy over time, and yet you also need the flexibility to make improvements. This applies to everybody. It is very true with regard to your own working techniques. Everybody who works, eventually settles into a pattern of techniques used. But not allowing for technical improvements in your techniques, will eventually lead to stagnation, and later, to inadequacy in doing your work. You don't want the world to pass you by. One must always try to incorporate changes and improvements, from within the steadiness of one's previously established and proven work patterns. And so it is with me too. As the person who incorporates new contributions into the public "CBT MVS Utilities Tape" collection, I find that I also have to establish a pattern which the public can understand and relate to. But I constantly have to try and absorb new improvements into my methods. In a sense, as expressed by Mozilla's mission statement, I often have to be a "benevolent dictator", to establish packaging standards for tape contributions, making the stuff easier to install and understand. The public will be the arbiter, if I've done my job well. As long as people can find the material they want, and install it easily, they won't complain. But I have to stay ahead of them. Today I want to do some talking about how I create and package the CBT Tape's files. In a sense, you'll all be looking over my shoulder, and watching me work. So what will you gain from this? I'd say you'll gain a lot. That's why I feel this topic is worth writing about. In my own working life, much of my own technique improvements have resulted from looking over someone else's shoulder, and saying: "Ah--so THAT's how they do it! Never thought of that way before!" Another thing you'll gain, is to learn some of my software packaging techniques, which might help you to efficiently and accurately transport software from one place to another. A third thing you'll gain, is better to UN-package this software. If you need some free software that is on the CBT Tape collection, you'll better be able to obtain it, load it onto your system, and get it ready to use. I don't underestimate this last benefit. A sizable fraction of emails to me, are from people who are having some trouble installing the "CBT Tape" software that they need. STARTING FROM THE DOC The CBT tape documentation file, affectionately called File 001, is an FB-80 EBCDIC text file, whose format was basically established by the CBT Tape's founder, Arnold Casinghino. I currently maintain and edit the contents of File 001. File 001, containing a great wealth of detail, advice, facts, and program description, was originally created by Arnie as a considerable number of separate sections. The current File 001, now well over 45000 lines long, used to be a nightmare to maintain. Just consider a 20000-line segment of File 001 which would need a one-line change. The editing overhead used to be horrific, especially since I like to keep saving my edits in the middle, for safety's sake. I solved this problem by dealing with File 001 as a partitioned dataset. This sounds simple, but it is not. The idea is that File 001 has to be broken into rather small sections in a very standard and reproducible way. Each of the sections can grow and change, but they all have to be put back together in their original order, to re-create the eventual large sequential dataset, which constitutes File 001 as we all know it, and as it is distributed on the CBT Tape. This has to go the other way, too. If I am given the last tape's File 001, I have to be able to create the pds that I use to maintain it. And I have to do it in the same standard way, so even if (God forbid) I lost my copy of my maintenance software, I could still recreate the CBT documentation pds, as I know it. My design consideration was to insert IEBUPDTE-type ./ ADD NAME= cards into a copy of the File 001 doc, such that the member names, in EBCDIC, would all sort in ascending order. I would run IEBUPDTE against this, to break the big doc file into pds members. Therefore, the member list of the pds, would follow the actual order of the pieces of doc, as they are put together in File 001. Then, it would be easy to put the pieces of doc, which are already arranged in the proper order as members of the pds, back into their proper place when the entire sequential doc file is reconstructed. To carry out the design and the creation of the pds, I wrote an Assembler language program called CBTUPD, whose source can be found on File 004 and File 006 of the CBT Tape. The CBTUPD program examines every line in the large doc file, and compares it against a table of tell-tale text strings which delimit each section of the doc, as Arnie and I created it. The table of strings is preceded (in the CBTUPD source code) by either the number 1, 2, or 3. This tells CBTUPD to insert the appropriate ./ ADD NAME= card, with an appropriate predetermined member name that is also coded, in a corresponding table, either one, two, or three lines BEFORE the line containing that particular tell-tale doc string. With that capability, the CBTUPD program does a very neat job of dividing up File 001 into nice looking, standardly-named pds members. One thing further has to be said about the CBT doc file. The last half of it consists of descriptions of the contents of each of the 600 files on the CBT Tape, whether they be "empty" (i.e. contianing a place holder file), or whether they contain usable data. The CBTUPD program constructs appropriate pds member names in its doc pds, to label these "file contents" sections for each tape file. For example, that section of File 001 describing the contents of File 523, in the CBT doc pds, is given a member name of @FILE523. As part of my current file packaging, besides using the @FILE523 member as a part of File 001, I also copy it in, as a member of the File 523 pds itself. This practice forces me to coordinate the internal documentation description of each CBT Tape software contribution file, with the File 001 overview description of that same file. I haven't done this yet for every file on the CBT Tape, but I've done it for almost all of the new contributions. MOST OF THE CBT TAPE FILES ARE FB-80 PDS'ES I have tried to extend Arnie's effort to put each contribution file on the CBT Tape into the most standard format possible. Since much of the material and tools on the CBT Tape are distributed as Assembler language source code, which comes in 80-byte card-image files whose data representation is EBCDIC, the actual format of the files, as they exist on the actual CBT TAPE, is greatly affected by this consideration. There has been a big effort by Arnie and me, to get rid of as many sequential files on the tape as possible, and make them into pds'es. The reason for this is that the TAPEMAP program, from File 299 of the CBT Tape, can display all the pds member names of tape files written in certain formats. The permissible formats include IEBCOPY and IEBUPDTE SYSIN format. Further, a program to compress FB-80 sequential files was written at the Connecticut Bank and Trust Company in 1979, to save tape space, and allow Arnie to squeeze more files onto the (then) standard sized tape reels. Close to 15 years ago, I extended TAPEMAP's power, to display the member names in these compressed files also. The TAPEMAP program would not show names for the sequential files on the CBT Tape, but it would show member names in all the pds files there, which are either in IEBUPDTE format, in compressed IEBUPDTE format, or in IEBCOPY format. Thus, if the CBT Tape files are pds'es, you can find all occurrences of member names you want, by scanning a TAPEMAP //SYSPRNT2 listing for the member name. Thus you can determine which tape files a program would most likely be found in, and that helps your search effort. TSO XMIT FORMAT MAKES FB-80 PACKAGING EASIER With the advent of TSO/E, as opposed to the old MVS TSO of pre-1985 vintage, IBM created a new TSO command for sending data from one MVS system in an NJE complex, to another. This command is called by its name, TRANSMIT, or by its alias, XMIT. The corresponding command for getting the data on the other end, was called RECEIVE. The TSO RECEIVE command has no abbreviation or short form. The plan for the XMIT command, was to send the MVS data across lines controlled by either JES2, JES3, VM, or VSE/POWER. In turn, those software systems are highly card-image (i.e. FB-80) oriented. JES2, JES3, VM, and VSE/POWER "like" 80-byte card image records, and can handle them well. So to carry out the plan, a means was devised, to use the XMIT command to convert various types of mainframe data, especially entire partitioned datasets, to FB-80 card-image sequential files that could be transmitted error-free over JES-controlled lines. On the other end, the RECEIVE command would re-create the original pds or other data, on the receiving MVS system, using the data's original DCB attributes. Practically speaking, there's an important thing to know about the XMIT-RECEIVE combination. If you're sending the data across from one MVS system to another, its format DURING TRANSMISSION is unknown to the users on either end. But in reality, the transmission format of the data is FB-80 sequential. It's just that neither user on either end gets to see the data in its intermediate form. However, just in case the data would NOT be directly and immediately sent across a line, the TSO designers created a way for us to get the data into its intermediate format, and that is by using the OUTDSN( ) keyword of the XMIT command. When you code the XMIT command using the OUTDSN(intermed.dataset.name) keyword, the data then is NOT transmitted across a line, but it is written in its intermediate format, to an FB-80 sequential file on the creating MVS system. That intermediate file can be Internet-ted or otherwise shipped to any MVS system anywhere, and the RECEIVE command, using the INDS(intermed.dataset.name) keyword on the destination system, can then re-create the original dataset with its original DCB properties. This gimmick is what we use in our CBT Tape file packaging. Load module pds'es, for example, can be converted to FB-80 sequential files, using XMIT with the OUTDSN( ) keyword, and these can be included as members of source pds'es on the CBT Tape, since they are also FB-80 card-image files. So instead of having to package two files for source and load, the source in compressed FB-80 IEBUPDTE SYSIN format, and the load in IEBCOPY format, you can put the load module library into an XMIT-format FB-80 file, and include it as a member of the source pds. Then the user of the file, can issue a RECEIVE INDS( ) command against that pds member, to re-create the original load library. The same technique can be used to package source type files that are VB, or are FB but not with LRECL=80. Just put them into XMIT format using the OUTDSN( ) keyword, make them a member of an FB-80 pds, and you have a uniform way to package the varied types of files in one pds. TAPE FILES vs. WEB SITE FILES Most of the files on the actual CBT TAPE, are either in IEBUPDTE SYSIN format FB-80 pds'es that have been compressed, or they are in IEBCOPY format on the tape. On the CBT Tape web site though, these same files are distributed in pkzip'ed TSO XMIT format. Pkzip'ed file format takes much less room on the web server disks, and those files are also smaller than the corresponding tape files, so they can be downloaded over the Internet more quickly. In today's discussion, it doesn't pay to dwell on these differences, except to say that very few sites have an un-zip program on their MVS system, so we must use MVS-oriented methods when real tapes are involved. Suffice it to say, that packaged either way, the usual resulting file on the destination MVS system will probably be a pds or an EBCDIC sequential file. VERSION-ING THE CBT TAPE FILES I recently created a CLIST called GENDAT (found on File 006) which will create a "time-stamp and stats" member for each new CBT Tape file. This member is always named $$$#DATE, and a sample of it is shown in Figure 1. In between release cuts of the CBT Tape versions, I post recently updated or added CBT Tape files to the "Updates" page of the CBT Tape web site. One file might be updated over a dozen times, in between CBT Tape version cuts. Therefore, if you've downloaded a file from the www.cbttape.org Updates page, you want to know which version you've got. This $$$#DATE member tells you. I now run the GENDAT CLIST against every new file version I distribute, on the web site or on the actual CBT Tape. I hope that by now, you understand a little more about the CBT Tape file packaging, and I have to apologize that I don't have the space to describe more of my techniques now. However, when you're downloading a CBT Tape file and trying to install its contents, I trust that the facts I've mentioned, will help you out. The best of everything to you all, and I hope to see you next month. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Figure 1. A sample $$$#DATE member of a CBT Tape File. This member was created by the GENDAT CLIST from File 006. REGULAR CBT TAPE - VERSION 443 FILE: 548 ORIGINAL DSNAME: SBGOLOB.CBT443.FILE548 --------------- --RECFM-LRECL-BLKSIZE-DSORG FB 80 5600 PO PDS117I 8 MEMBERS COUNTED; CUMULATIVE SIZE IS 852 RECORDS TIME THIS PDS WAS SHIPPED: 02/15/02 09:35:08 GMT-5:00