MVS TOOLS AND TRICKS OF THE TRADE August 1990 Sam Golob MVS Systems Programmer sbgolob@cbttape.org SMP/E HACKING EXAMPLE - REGRESSING VTAM, PART 1 Last month, we discussed the usefulness of SMPPTFIN pre-processing outside of SMP or SMP/E. I hope to continue on the subject of "SMP additions" in more depth in a future installment. I feel that SMP/E facilities are not complete for all our needs. They can use quite a bit of user supplementation. However this month, a very interesting SMP situation had arisen in our shop. I'll describe what we did in the hope that you may compare notes, and add this technique to your repertoire of knowledge. Because of space constraints, this topic will be divided between two issues, and the figure numbering will span both issues. However, THE SIDEBAR SUMMARIZES THE COMPLETE PROCEDURE THAT WAS FOLLOWED. Anyone needing hands-on help on this topic can consult the sidebar. Next month's discussion will merely add further detail. THE PROBLEM. Our shop had the following problem. We are happy users of VTAM release 2.2 (HVT2202). We were running MVS/370 (SP 1.3.5) and were trying to go to MVS/XA 2.2.3 with a CBIPO. IBM was pleased to inform us that while they still support VTAM 2.2, they no longer ship that release to new customers, and it is unavailable in a CBIPO. My boss (who does the ordering) asked them to ship the CBIPO without VTAM. This, IBM refused to do, because they obviously do not want to ship a system that "does not work". We finally settled on the compromise of ordering VTAM 3.2 (HVT3205 and JVT3215) on free trial so we could get the CBIPO. VTAM 3.2 costs considerably more than 2.2, and we don't need the extra function. I assured my boss that once the IPO was up and running somewhat, I would find a way to regress VTAM 3.2 out, and plug VTAM 2.2 back in its place so he could cancel the VTAM 3.2 trial. I had to "put my money where my mouth was", and actually accomplish the deed. This was the problem we had. Well we're proud to say that we've overcome it successfully. I'll try to tell you how it was done. The main difficulty is that VTAM is not a standalone product--it interfaces with other components of the operating system. We were attempting to transplant an installed VTAM "imbedded" in an MVS/370 system over to an new MVS/XA system that was considerably different from the old system. We had to faithfully implant the older VTAM into new surroundings, in the way that the fit was intended by IBM originally. One thing that helped us was having SMP/E Release 5. (SMP/E Release 4 will do the job too.) Shortly before the CBIPO had been ordered, we converted our old SMP4 (non SMP/E) maintenance system to IBM's newest. Even though I probably could have done this stuff on the old system, I was quick to take advantage of the new facilities of SMP/E, particularly the GENERATE function, which can be pictured as the reverse of JCLIN. Hang in there and let me explain the SMP/E things, so we all clearly understand the concepts behind what we're trying to do. SOME "FOUNDATION" SMP/E KNOWLEDGE: What is JCLIN? JCLIN contains the "smarts" of how your operating system is built. It consists of IEBCOPY, ASSEMBLY, and LINKEDIT JCL that builds the working components of your operating system from its physical "building blocks". The physical pieces of the product, or ELEMENTS, are shipped to you in the DLIBs--the "distribution libraries" of macros and modules. IBM sends DLIBs directly to customers of a newly-shipped system. After installation, the DLIBs are updated through the SMP ACCEPT processing. When the JCL for construction of a software product is fed into SMP/E, patterns for building that product's executable pieces are now made known to SMP/E as internal entries. SMP/E can follow these patterns later, so that subsequent product fixes are inserted into their proper places and they will operate properly. Building blocks alone "do not a house make". As we have stated, COPY, ASSEMBLY, and LINKEDIT JCL may be necessary for building the target structure ("operating system") from the blocks. The JCL that properly puts the pieces together has to undergo two processes. Process number one: it must ACTUALLY BE RUN against the building blocks to build the executable TARGET LIBRARIES initially. Process number two: its pattern must be fed into SMP via the process of "JCLIN", so that SMP will "know" the system architecture for its later use in applying system fixes. I think that it is not adequate to describe JCLIN as "JCL that goes into SMP", as some IBM books do. JCLIN CONTAINS THE CONSTRUCTION BLUEPRINTS that describe the "walls, rooms, and hallways of the building". Just as a building cannot be properly built without PLANS, an operating system component cannot be properly built without its JCLIN. Where did the JCLIN for your "building" ("operating system component") originally come from? It may have come from your "SYSGEN STAGE TWO" deck, which in turn came from your installation's "SYSGEN STAGE ONE" system configuration deck THAT YOUR INSTALLATION CODED. Your SYSGEN STAGE ONE gets assembled against the current set of SYSGEN MACROS that have been shipped with the distribution libraries by IBM. And it is these SYSGEN MACROS which contain the "brains" and the blueprint of how to "build the building". That's the case where the JCLIN came from products that have "SYSGEN support" from IBM. If a product does not have SYSGEN support, the JCLIN was shipped within the initial FUNCTION SYSMOD when the product was first ordered. If you have my "Technical Support" article: "SMP Demystified" from December 1988, now would be a good time to take it out for another look. I have written a clear treatment of this material there. To go on, the JCLIN that builds your system, once fed into SMP, is not easily retrieved from SMP. Before the introduction of the GENERATE facility to SMP/E, the only way that retrieval could have been done is through "LIST of the LMOD, ASSEM, and DLIB entries" for the FMIDs that you wanted to study. The resultant long listing would have to be carefully edited and tediously converted back into JCL format "by hand". IBM developers added the GENERATE facility to SMP/E (in release 3 I believe) to solve that problem for the user. Running a GENERATE job against an SMP/E TARGET ZONE translates the LMOD, ASSEM, and DLIB entries back into a JCL stream that would have originally created those entries. Thus, GENERATE can be viewed as a reverse process to JCLIN. JCLIN feeds the building pattern of the operating system working components into SMP/E. GENERATE retrieves this JCLIN back out from SMP/E, and displays it as JCL. RECONSTRUCTING THE PRODUCT WITH JCLIN AND ITS "ELEMENTS". Now, armed with these foundation materials, we shall angle toward our current concern. A software product installed with SMP can be completely characterized by two components: its ELEMENTS (building blocks, if you will), and its JCLIN, which tells SMP how to construct the building from the blocks. The physical elements are stored in partitioned datasets called distribution libraries or DLIBs. The SMP/E records of all elements belonging to a product are stored in VSAM datasets called ZONEs. Distribution libraries ("DLIBs") are tracked by a DLIB ZONE of SMP/E. Working system libraries are tracked by a TARGET ZONE of SMP/E that is PAIRED with the DLIB ZONE. The JCLIN for building a product is also stored in the TARGET ZONE for that product. SMP/E (as did old SMP) provides a mechanism to directly alter its control entries. This mechanism is called "UCLIN". Through UCLIN, adjustments can be made by the programmer as necessary to manually control SMP processes. Under SMP/E, A "SET BDY" (set boundary) command directs the action of the UCLIN to the one particular ZONE whose entries are to be adjusted. It follows that WE CAN COMPLETELY BUILD A PRODUCT from the following ingredients: First, we need a complete collection of the physical elements. These are stored in the appropriate DLIBs for the product. We need records of these elements for our FMID(s) out of SMP/E. Those can be obtained through the "UNLOAD" facility of SMP/E, which can dump all element records in UCLIN format out of either the DLIB ZONE or the TARGET ZONE. UCLIN format is directly used as input to SMP/E, to construct corresponding new element entries in a new ZONE. Second, we need the source of JCLIN--the JCL stream needed to construct the working parts out of the distributed software pieces. That JCLIN source is supplied by running an SMP/E GENERATE job against an installed TARGET ZONE for the FMID(s) of our product(s). The equivalent of the originating JCL input stream is then created. It is these ingredients that we will use to construct a VTAM 2.2 installation in the SMP/E setting of our new XA 2.2.3 system. The parts for the new installation will come from the VTAM 2.2 product that we already have, which was installed by SMP/E on the MVS/370 system. WHAT TO DO. See the SIDEBAR for an outline of the steps that should be followed. An elaboration on the details, the "extra care" items, and one or two "gotchas" will follow in next month's issue. Meanwhile, someone wishing to actually DO this kind of stuff, can get it done from the SIDEBAR outline. If you need more help, the magazine editors will gladly supply you with my phone number. Good luck. See you next month. * * * * * * * * * * * * * * * * * * * * * * * SIDEBAR. Procedure steps to accomplish the replacement of VTAM 3.2 on an MVS/XA system with VTAM 2.2 transplanted from our previous MVS/370 system. 1. Do ACCEPT processing on the 370 system for all HVT2202 PTFs that have been APPLYed. This will load the DLIBs with the VTAM 2.2 elements at the highest "clean" levels. 2. Back up all disk packs involved. (This goes without saying.) 3. UNLOAD from the old system: the DLIB zone FORFMID(HVT2202) and the TARGET zone FORFMID(HVT2202). See Figure One. 3A. Optionally do the same FORFMID(HVT3205,JVT3125) off the new system, just to have the decks for reference. In our case these decks will not be used. 4. Run GENERATE FORFMID(HVT2202) from the MVS/370 system. See Figure Two for an example. 5. Run GENERATE FORFMID(HVT3205,JVT3215) from the XA system. See Figure Three. 6. Create a dummy FUNCTION to run on the XA system, that will DELETE(HVT3205,JVT3215). Call this FUNCTION DELVT32. This FUNCTION will actually be APPLYed and ACCEPTed. Figure Four will show an example. 7. Create a dummy FUNCTION to run on the 370 system, that will DELETE(HVT2202). Call this FUNCTION DELVT22. This FUNCTION will only be APPLY CHECKed. DON'T APPLY IT-- PLEASE!! REJECT it as soon as you've finished with it, just to be safe. The ELEMENT report from the APPLY CHECK listing for this FUNCTION will be used to create a COPY JOB to copy all DLIB elements from the old system's DLIBs to the new system's DLIBs. 8. Create the COPY JOB for the DLIB elements by either editing the APPLY CHECK report for DELVT22, or by using my COBOL program GIMELMNQ as a service aid. GIMELMNQ is not publicly distributed yet. Figure Five shows the output it produces. 9. APPLY and ACCEPT the delete FUNCTION DELVT32 on the new XA system. SAVE THE REPORTS. The utility report for the APPLY will contain crucial linkedits. 10. Use UCLIN to delete the SYSMOD entry for HVT2202 in both the TARGET and DLIB zones of the new system. This entry had been marked as deleted by HVT3205, and it must be gotten rid of in both zones of the XA SMP/E system. DEL SYSMOD(HVT2202) . is the UCLIN statement required in both zones. *** 11. Edit the GENERATE jobs for both VTAMs to produce one correct hybrid deck that we will actually use. Details will follow on how to do this. This step is the heart of the matter. See Figures Six and Seven. The general rule is: Self-contained VTAM modules follow the OLD (2.2) pattern. Modules interfacing with other components follow the NEW (3.2) pattern. 12. Copy all HVT2202 ELEMENTs (and their aliases, if any) from the "370" DLIBs to the XA DLIBs. The XA DLIBs have now been stripped of VTAM elements by the ACCEPT of DELVT32. Figure Eight shows a part of my copy job created for this step. 13. Actually run the hybrid GENERATE copy job and linkedit jobs that you had created in Step 11. This will load the TARGET libraries with the correct load modules. 14. Now bring SMP/E into sync. UCLIN the DLIB UNLOAD of HVT2202 into the DLIB ZONE of the XA system. UCLIN the TARGET LIB UNLOAD of HVT2202 into the TARGET ZONE of the XA system. Then JCLIN the hybrid GENERATE deck into the XA system. Figures Nine and Ten illustrate these processes. 15. Check all jobs for clean return codes, and fix all errors, if any. Move the modules to an IPL-able pack, and IPL. We should have a "runnable" installed product at this stage. Voila. * * * * * * * * * * * * * * * * * * * * * * * FIGURE ONE. SMP/E UNLOAD of VTAM Release 2.2 DLIB Zone Entries and TARGET Zone Entries, to be transported to XA DLIB Zone and XA TARGET Zone, respectively. //TSTB#SG$ JOB (TS,2322),'TECH.SUPP-SAM.GOLOB',CLASS=M,NOTIFY=TSTBSSG, // MSGLEVEL=(1,1),MSGCLASS=T //******************************************************************// //* SMP/E - UNLOAD JOB - HVT2202 DLIB Zone and TARGET Zone *// //******************************************************************// //* //UNLOADDL EXEC SMPEMVS1,AC= <=== MVS/370 SMP/E Procedure //SMPCNTL DD * SET BDY(MVSDLB). UNLOAD FORFMID(HVT2202). /* //SMPPUNCH DD DISP=(NEW,CATLG,DELETE),UNIT=3380,VOL=SER=WORK02, // SPACE=(TRK,(120,300),RLSE),DSN=TST.DLIB.UNLOAD.HVT2202, // DCB=(RECFM=FB,DSORG=PS,LRECL=80,BLKSIZE=11440) //* //* ------------------------------------------------------------ *// //* //UNLOADTG EXEC SMPEMVS1,AC= <=== MVS/370 SMP/E Procedure //SMPCNTL DD * SET BDY(MVSTGT). UNLOAD FORFMID(HVT2202). /* //SMPPUNCH DD DISP=(NEW,CATLG,DELETE),UNIT=3380,VOL=SER=WORK02, // SPACE=(TRK,(120,300),RLSE),DSN=TST.TARGET.UNLOAD.HVT2202, // DCB=(RECFM=FB,DSORG=PS,LRECL=80,BLKSIZE=11440) * * * * * * * * * * * * * * * * * * * * * * * FIGURE TWO. SMP/E GENERATE Command execution to reconstruct the JCLIN that is needed to build the VTAM 2.2 TARGET Libraries in an MVS/370 setting. //TSTB$MO$ JOB (TS,2322),'TECH.SUPP-MARIANNE',CLASS=M,NOTIFY=TSTBSSG, // MSGLEVEL=(1,1),MSGCLASS=T TYPRUN=HOLD //* //* LIB: TSX1.INSTLIB(MVSGEN) //* GDE: CBIPO MVS INSTALLATION //* DOC: THIS JOB EXECUTES THE GENERATE COMMAND OF SMP/E TO CREATE //* THE JOBS THAT CONSTRUCT THE TARGET SYSTEM LIBRARIES. THE //* GENERATE COMMAND CREATES THE JOB STREAM TO THE SMPPUNCH //* FILE. IN OUR CASE THIS IS DONE ONLY FOR FMID HVT2202. //* //* THE JOBSTREAM PRODUCED BY THE GENERATE COMMAND IS //* SEPARATED INTO TWO PARTS: THE FIRST, V22GEN1, IS A JOB //* TO PERFORM IEBCOPY OF DLIB MEMBERS. IT MUST COMPLETE //* BEFORE THE SECOND HALF, V22GEN2, IS RUN. //* //GENERA1 EXEC SMPEMVS1,REGION=6144K,AC= <=== MVS/370 SMP/E Procedure //SMPCNTL DD * SET BOUNDARY(MVSTGT) . GENERATE FORFMID(HVT2202) JOBCARD(SMPGENL,JOBCARD) . /* //SMPPUNCH DD DSN=&&JOBS,DISP=(NEW,PASS), // SPACE=(6160,(300,200)),UNIT=SYSALLDA, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160,DSORG=PS) //SMPGENL DD DSN=TSX1.GENLIB,DISP=SHR, // UNIT=3380,VOL=SER=VEND02 //* //SPLIT3 EXEC PGM=IEBGENER, <=== Split Output into // REGION=512K <=== COPY and LNKEDIT //SYSPRINT DD SYSOUT=* <=== Parts. //SYSUT1 DD DSN=&&JOBS,DISP=(OLD,PASS) //SYSUT2 DD DSN=TSX1.INSTLIB,DISP=SHR, // UNIT=3380,VOL=SER=VEND02 //SYSIN DD * GENERATE MAXNAME=2,MAXGPS=1 MEMBER NAME=V22GEN1 RECORD IDENT=(8,'//******',1) MEMBER NAME=V22GEN2 /* // * * * * * * * * * * * * * * * * * * * * * * * FIGURE THREE. SMP/E GENERATE Command execution to reconstruct the JCLIN that is needed to build the VTAM 3.2 TARGET Libraries in an MVS/XA 2.2.3 setting. //TSTB$MO$ JOB (TS,2322),'TECH.SUPP-MARIANNE',CLASS=M,NOTIFY=TSTBSSG, // MSGLEVEL=(1,1),MSGCLASS=T TYPRUN=HOLD //* //* LIB: TSX1.INSTLIB(MVSGEN) //* GDE: CBIPO MVS INSTALLATION //* DOC: Generate Job for VTAM 3.2 on the MVS/XA SMP/E system. //* //GENERA1 EXEC SMPEMXA,REGION=6144K,AC= <=== MVS/XA SMP/E Procedure //SMPCNTL DD * SET BOUNDARY(M22TGT) . GENERATE FORFMID(HVT3205,JVT3215) JOBCARD(SMPGENL,JOBCARD) . /* //SMPPUNCH DD DSN=&&JOBS,DISP=(NEW,PASS), // SPACE=(6160,(300,200)),UNIT=3380, // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160,DSORG=PS) //SMPGENL DD DSN=TSX1.GENLIB,DISP=SHR //* //SPLIT3 EXEC PGM=IEBGENER, <=== Split output into // REGION=512K <=== COPY and LINKEDIT //SYSPRINT DD SYSOUT=* <=== Parts. //SYSUT1 DD DSN=&&JOBS,DISP=(OLD,PASS) //SYSUT2 DD DSN=TSX1.INSTLIB,DISP=SHR //SYSIN DD * GENERATE MAXNAME=2,MAXGPS=1 MEMBER NAME=V32GEN1 RECORD IDENT=(8,'//******',1) MEMBER NAME=V32GEN2 /* // * * * * * * * * * * * * * * * * * * * * * * * FIGURE FOUR. Illustration of DUMMY FMID DELVT32 which is used to delete VTAM 3.2 from the MVS/XA SMP/E system. ++FUNCTION (DELVT32). ++VER(Z038) /* DELETES VTAM 3.2 FUNCTIONS WHICH CAME WITH THE CBIPO FOR MVS/XA 2.2.3, BUT WHICH WE DO NOT INTEND TO RUN IN PRODUCTION. S. GOLOB - 04/03/90 */ DELETE( HVT3205 JVT3215 ). * * * * * * * * * * * * * * * * * * * * * * * FIGURE FIVE. Illustration of output from my GIMELMNQ Service Aid which produces the following ELEMENT listing from an SMP/E APPLY CHECK of the DELVT22 FUNCTION. This listing is sorted by the DLIB name in columns 44-51 and edited to produce IEBCOPY SELECT MEMBER statements. After I have made sure that these members have no ALIASES, this IEBCOPY job is used to accurately move all DLIB members from the MVS/370 DLIBs to the MVS/XA DLIBs. AMDUSRFD /*MOD DELETED AOS24 */ CHANGE /*MAC DELETED AMACLIB */ CLSDST /*MAC DELETED AMACLIB */ COS /*MAC DELETED AMACLIB */ ------------ DATA MISSING FOR BREVITY ----------- GTDEVSIZ /*MAC DELETED ATSOMAC */ IHASU1 /*MAC DELETED AMODGEN */ IHASU34 /*MAC DELETED AMODGEN */ IHASU35 /*MAC DELETED AMODGEN */ IHASU40 /*MAC DELETED AMODGEN */ IHASU54 /*MAC DELETED AMODGEN */ IHBRDWRA /*MAC DELETED AMACLIB */ IKTASCII /*MOD DELETED AOST3 */ IKTASTPT /*MOD DELETED AOST3 */ ------------ DATA MISSING FOR BREVITY ----------- IKT3270O /*MOD DELETED AOST3 */ IKT3767I /*MOD DELETED AOST3 */ IKT3767O /*MOD DELETED AOST3 */ IKT93EST /*MOD DELETED AOST3 */ INQUIRE /*MAC DELETED AMACLIB */ INTAB /*MAC DELETED AMACLIB */ INTRPRET /*MAC DELETED AMACLIB */ ISTACBEX /*MAC DELETED AMACLIB */ ISTACB1 /*MAC DELETED AMACLIB */ ISTACCAN /*MOD DELETED AOS26 */ ISTACCAP /*MOD DELETED AOS26 */ ------------ DATA MISSING FOR BREVITY ----------- * * * * * * * * * * * * * * * * * * * * * * *