MVS TOOLS AND TRICKS OF THE TRADE February 1991 Sam Golob MVS Systems Programmer sbgolob@cbttape.org CONVERSION BETWEEN CLIST FORMATS: VB-FB, FB-VB As of this writing, I've now spent several months editing the CBT MVS Tape. I can begin to appreciate the great job that Arnie Casinghino has done managing that tape over the last fifteen years, and his long-term dedication to us all. Thanks again, Arnie. We owe you something we can never fully repay. This month, we'll describe a CLIST format conversion program called CVTCLIST, which is found in its latest incarnation on the CBT MVS Tape, File 187. When you need it, CVTCLIST saves you enormous amounts of labor, and it gives your shop a freedom you've never thought possible. CVTCLIST is an ancient program. Bob Collins of Chicago got it to work under MVS in the mid-70s, and put it on the CBT tape then. CVTCLIST had some famous bugs when converting CLIST libraries from VB to FB format. I made a big effort to fix those bugs about a year ago, and have now improved the program more, calling the current version (as of this writing) Version 2.1. The CVTCLIST program converts entire libraries of CLISTs from 80-byte fixed blocked format to 255-byte variable blocked format. More importantly, it can convert the other way too. The current version of CVTCLIST accurately folds long lines of executable data when converting from VB-255 format to FB-80. Therefore, CVTCLIST affords a data center freedom from being tied down permanently to any one of these formats. Version 2.1 of CVTCLIST can be found on File 187 of Version 322 or higher of the CBT Tape. The CBT Tape can be obtained either from NaSPA (414) 423-2420, or from Fred Robinson of the Share Program Library Agency (305) 284-6257. A QUICK OVERVIEW OF THE TWO CLIST FORMATS. CLISTs are programs which run under TSO. CLISTs can execute TSO commands or other programs in the foreground. CLIST programs are really files that are interpreted by the CLIST language processor during a TSO session. The CLIST file is executed as a program either explicitly using the "EXEC" TSO command, or implicitly if the file is a member of a PDS, allocated to the "SYSPROC" ddname in your TSO session. Most installations provide public CLIST libraries for their TSO users. These libraries are concatenated to the SYSPROC ddname by the installation, usually. Sometimes, an installation's SYSPROC concatenation will contain many hundreds of CLISTs, possibly thousands, in several different libraries. IBM allows the CLIST language processor to accept as input, files in either 80-byte fixed blocked card-image format, or in variable blocked format with record length equal to 255. CLIST files in fixed blocked format can have sequence numbers in columns 73-80. Data is ignored in those columns, when the record format is FB. When a CLIST is in variable blocked (or VB) format, columns 1-8 are ignored as data, and are used for sequence numbers. You see that the two formats have incompatible sequence numbering. The CLIST processor is aware of the record format of its input file, and treats the sequence number columns accordingly. We must say a word about the SYSPROC ddname concatenation of libraries. Libraries of CLIST files in this concatenation must be either ALL FB or ALL VB. That is an MVS restriction. MVS data management looks at any concatenation of libraries and builds its one data control block from the information in the first, or highest library. If that library is FB, MVS regards the whole collection as FB. If it's VB, MVS looks at all the libraries as though they are VB. Now we stated above that CLIST sequence numbering for FB CLISTs is incompatible with the numbering for VB clists. It's obvious that mixed FB and VB libraries in one concatenation will cause serious CLIST execution problems. Therefore, any installation which maintains public SYSPROC concatenations must commit to either ALL FB or ALL VB, for the record format. CONVERSION PROCEDURES - WHAT'S INVOLVED? Until recently (even now) IBM has been restricted to distributing its own CLISTs in 80-byte FB format. IBM's System Maintenance Programs SMP4 and SMP/E (before Release 5) could not accept variable blocked files for their automated installation processing. Therefore, any shop whose CLISTs were VB format had to convert IBM's FB CLISTs to VB before they could be used. I shall describe this quite laborious process. Even worse is the predicament of a shop that has VB CLISTs and which wants to back out. I'll describe what's involved in that, too. Then we'll show how the CVTCLIST program will accomplish all these things automatically, without any effort on the part of the programmer. FB to VB conversion involves three things: First, removal of all sequence numbering from columns 73-80 of each record in the file. Second, conversion of the file from FB to VB format. This means appending 4-byte record descriptor words or RDW's and block descriptor words or BDW's to the logical records and physical blocks of data. This also involves stripping trailing blanks off the ends of the variable records. Third, all meaningful data in each record must be shifted 8 bytes to the right. Columns 1-72 now become columns 9-80. This is to make sure that the data will be executable in the new format, and also to make room for new sequence numbers in columns 1-8. ISPF can be used to do the FB-VB conversion, and has been the traditional method employed. Actual FB-VB data conversion can be done by the copy option 3.3. The ISPF copy program does the proper prefixing of BDW's and RDW's and stripping of trailing blanks. That's the easy part. The hard part is that each CLIST must then be edited individually. All numerics in columns 73-80 must be converted to blanks. Then all lines must be shifted 8 columns to the right. Finally, each CLIST should be renumbered and the edit saved. Some of this work might be automated through the use of ISPF edit macros. A frequent problem in this method is that the person doing it, might forget to remove the old sequence numbers from columns 73-80. After shifting to the right, these will appear in columns 81-88. Upon execution of the converted CLIST, the CLIST processor will mistake these old sequence numbers for data, since they are not in columns 1-8. Serious execution errors will result. It would be nice to eliminate such spurious sequence numbers after the fact. I call the process of eliminating numerics in columns 81-88 "STRIPPING". IBM has provided a cumbersome CLIST called ICQSMC00 that does FB-VB conversion of a CLIST library. When first distributed five years ago, ICQSMC00 was full of bugs and it didn't even run. People tell me that now it works. It takes many minutes to execute, however. ICQSMC00 only does FB-VB conversions, not VB-FB. For VB-FB conversions, to my knowledge, IBM leaves you high and dry. So now let us look at VB-FB. What's involved? There are again several steps. Here, there is a judgment factor concerning how to fold a long data line into several short ones so it'll execute the same. I had to make these decisions when I was fixing the VB-FB algorithm in CVTCLIST, so I'll tell you how I decided to do it. Please argue with me if you want to. The steps are as follows: Ignore BDW's and RDW's and the first 8 columns of data. Look at the length of the data that comes afterward. If that data is 72 lines or less, write it as a fixed record starting in column 1, and pad to 72 columns with blanks. If the data line is longer than 72 bytes, split the data after column 71, place a dash (continuation character) in column 72, and make a new record to continue spilling over the data, starting in column 1 of the new record. Continue this process until the data in the long line is exhausted. Pad to column 72 of the last new record with blanks. Optionally supply sequence numbers in columns 73-80 of the new fixed records. This is hard to do accurately with ISPF edit. It may possibly be done more conveniently using an edit macro. Most shops with VB CLISTS will feel trapped if they have lots of CLISTs to convert. So now we're ready to show how the conversion program CVTCLIST comes to the rescue. USING THE CVTCLIST PROGRAM. The CVTCLIST conversion program is extremely easy to use. There is a SYSPRINT ddname for messages. Input is to the SYSUT1 ddname. Output is to the SYSUT2 ddname. That's all. When the program starts executing, it makes sure that the SYSUT1 and SYSUT2 DCBs have different record formats. If SYSUT1 is FB and SYSUT2 is VB, then the conversion goes FB-VB. Similarly, if SYSUT1 is VB and SYSUT2 is FB, then the conversion goes VB-FB. The conversion algorithms in CVTCLIST are as described above, but in addition, sequence renumbering of the converted members is done. A wrinkle was introduced with CVTCLIST Version 2.1. Formerly, the library that was the target of a conversion had to be empty. Now, the target conversion library can have members already there. You have control with parms in the execute statement. No parm defaults to replace of existing member names. A parm of "NOREPLACE" will preserve previously existing members in the target library, while adding all newly converted members that have new names. CVTCLIST Version 2.1 has full member-name level reporting, as well as a summary report of totals. See Figures One, Two, and Three for these reports. "LITTLE THINGS" TO CONSIDER. The CVTCLIST program preserves the old directory entry of converted members. For example, if the original member had ISPF statistics, they are copied over to the new member's directory entry. Sometimes this can be awkward. For example, if you're doing line splits in a VB-FB conversion, the converted member will have more logical records than the original member. This increase of record count would not be reflected in the new copied directory entry. Therefore, CVTCLIST counts and reports the number of splits in a member. Then it tests the directory entry to see if it is in ISPF format. If it is, CVTCLIST adds the number of splits to the old record count, giving the true record count in the directory. This is a neat touch. CVTCLIST Version 2.1 now supplies new sequence numbers incremented by 10000, which are "agreeable" with ISPF numbering conventions. CVTCLIST Version 2.1 does not optionally do "stripping" of numerics from VB CLISTS in columns 81-88 when converting them back to FB. Nor does it report the possible need for "bad sequence number" stripping in existing CLISTs. I'm considering implementation of this feature in the future Version 2.2. The feature might come in handy for some shops (including mine). Well anyway, I hope this discussion has provided some food for thought in the way CLISTs have been set up at your shop. It'll certainly help you in converting IBM's CLISTs if yours are VB. If your shop has had reservations about converting to VB (or even back to FB), knowledge and use of the CVTCLIST program will help in the decision. See you again next month. Good luck.