USING REXX COMMAND FILES WITH TEAMCONNECTION MVS BUILD SCRIPTS FOR PL/I PROGRAMS Document Number TR 29.2235 Mike Petersen Jeri Petersen TeamConnection Integration IBM Software Solutions Research Triangle Park, N.C. (c) Copyright International Business Machines Corporation 1996. All rights reserved. ii REXX and MVS Build Scripts TRADEMARKS AND SERVICE MARKS The following terms are trademarks or service marks of the IBM Corporation in the United States or other countries: +---------------+---------------+---------------+---------------+ | CICS | | | | | | | | | | DB2 | | | | | | | | | | IBM | | | | | | | | | | IMS | | | | | | | | | | OS/2 | | | | | | | | | | TeamConnection| | | | | | | | | | VisualAge | | | | +---------------+---------------+---------------+---------------+ The following terms are trademarks or service marks of other com- panies: +---------------+---------------+---------------+---------------+ | Object Store | Object Design,|Inc. | | +---------------+---------------+---------------+---------------+ (C) Copyright IBM Corp. 1997 iii iv REXX and MVS Build Scripts ABSTRACT This report introduces the concept of using REXX command files for use with TeamConnection MVS build scripts. Using REXX command files for TeamConnection MVS builds allows you to use the power of REXX to provide function that is not possible in the normal JCL-like build scripts for MVS. This includes: o Only returning messages to TeamConnection when there is a problem. o Concatenating a program product include library that is main- tained on the MVS host with other include members that are maintained within TeamConnection. o Changing compiler or linkage editor options based on the work area, driver, or release name. o Changing the DB2 system id based on a work area, driver, or release name. o Trapping messages from DB/2 where multiple messages might be returned. o Handling multiple outputs (for example, both a DBRM and object code). o Needing to get the link edit and bind to occur at the same time so that the date/time stamp for the load module and package are not out of date. The specific examples are for PL/I, DB2, and CICS. However, the techniques can be applied to other languages such as COBOL and other environments such as IMS or TSO. Refer to TR29.2196 - ___________ Using REXX Command Files with TeamConnection MVS Build Scripts ______________________________________________________________ for information on handling COBOL. ACKNOWLEDGMENTS The authors would also like to acknowledge the following people who worked on build scripts for PL/I before this Technical Report was started: o Tom Loeber o Mehdi Sanayei (C) Copyright IBM Corp. 1997 v ITIRC KEYWORDS o Build agent o Build processor o Build server o CICS o PL/I o Configuration Management o DB2 o Drivers o Library Management o REXX o TeamConnection o Work areas vi REXX and MVS Build Scripts ABOUT THE AUTHORS Mike Petersen is an IBM software developer for TeamConnection integration in Raleigh, North Carolina. Mike was an SCLM soft- ware developer for six years. He has worked in systems, applica- tion, and other product programming areas. He also has had assignments with world trade, IBM faculty loan program, technical education, and technical support for marketing. Mike received a BS in mathematics with a physics minor in 1972 and an MS in computer science in 1974 from Purdue University. In 1979 he received an MBA from Marist College. Jeri Petersen is an IBM software developer for TeamConnection integration in Raleigh, North Carolina. Jeri was in VisualAge Generator development for nine years. She has also worked in application development for IBM, as well as for other companies. Jeri received a BS in mathematics with a physics minor in 1972 from Purdue University, an MS in computer science in 1974 from Rutgers University, and an MBA in 1979 from Marist College. (C) Copyright IBM Corp. 1997 vii viii REXX and MVS Build Scripts CONTENTS TRADEMARKS AND SERVICE MARKS . . . . . . . . . . . . . . . III ABSTRACT . . . . . . . . . . . . . . . . . . . . . . . . . . V Acknowledgments . . . . . . . . . . . . . . . . . . . . . . v ITIRC Keywords . . . . . . . . . . . . . . . . . . . . . vi ABOUT THE AUTHORS . . . . . . . . . . . . . . . . . . . . . VII FIGURES . . . . . . . . . . . . . . . . . . . . . . . . . . XI BEFORE WE BEGIN . . . . . . . . . . . . . . . . . . . . . . . 1 Disclaimer - Notice to Users of the Source Code Examples 2 OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . 3 RUNPGM . . . . . . . . . . . . . . . . . . . . . . . . . . 3 RUNPGMT . . . . . . . . . . . . . . . . . . . . . . . . . . 6 HOW THE BUILDER DEFINITION, IRXJCL, AND THE REXX COMMAND FILE WORK . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Defining the Builder . . . . . . . . . . . . . . . . . . 19 Notes on mvspli.jcl (the Build Script) . . . . . . . . . 19 Notes on mvsrxpli.rxp (the REXX Command File) . . . . . . 20 SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE . . . 25 Simple PL/I Program Include Member . . . . . . . . . . . 25 PL/I Program, Link Edit Statements, and Build Tree . . . 26 PL/I with DB2 Program, Link Edit Statements, and Build Tree 28 PL/I with CICS Program, Link Edit Statements, and Build Tree . . . . . . . . . . . . . . . . . . . . . . . . . . 31 PL/I with DB2 and CICS Program, Link Edit Statements, and Build Tree . . . . . . . . . . . . . . . . . . . . . . . 33 Sibling Output Build Trees . . . . . . . . . . . . . . . 35 PUTTING IT ALL TOGETHER . . . . . . . . . . . . . . . . . . 39 Create a New Family . . . . . . . . . . . . . . . . . . . 39 Start the TeamConnection Client . . . . . . . . . . . . . 43 Create Components . . . . . . . . . . . . . . . . . . . . 44 Create a Release . . . . . . . . . . . . . . . . . . . . 46 Create Builders . . . . . . . . . . . . . . . . . . . . . 46 Create A Parser . . . . . . . . . . . . . . . . . . . . . 50 Open a Feature and Create a Work Area . . . . . . . . . . 51 Create Parts . . . . . . . . . . . . . . . . . . . . . . 52 Create Build Tree . . . . . . . . . . . . . . . . . . . . 55 Start the MVS Build Agent and Build Processor . . . . . . 59 Build the Object Modules . . . . . . . . . . . . . . . . 60 Build the Load Modules . . . . . . . . . . . . . . . . . 61 VARIATIONS IN MVSPLI.JCL AND MVSRXPLI.RXP . . . . . . . . . 65 Keeping mvspli.jcl at the MVS Host . . . . . . . . . . . 65 (C) Copyright IBM Corp. 1997 ix Keeping mvsrxpli.rxp at the MVS Host . . . . . . . . . . 66 Supporting Program Product Include Libraries . . . . . . 67 Supporting Program Product Include Libraries Concatenated with TeamConnection Copybooks . . . . . . . . . . . . . . 67 Setting PL/I Compiler Options - Hardcoding . . . . . . . 69 Setting PL/I Compiler Options - From Builder Definition . 69 Setting PL/I Compiler Options - Based on Work Area Name . 70 Reducing the Number of Build Messages . . . . . . . . . . 73 HINTS AND TIPS FOR MVS BUILDS . . . . . . . . . . . . . . . 75 APPENDIX A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK EDIT AND BIND . . . . . . . . . . . . . . . . . . . . . . . . 79 Defining the Builder . . . . . . . . . . . . . . . . . . 79 Notes on mvslnk.jcl (the Build Script) . . . . . . . . . 80 Notes on mvsrplnk.rxp (the REXX Command File) . . . . . . 83 Variations in Link and Bind . . . . . . . . . . . . . . . 94 Combining mvsrxpli.rxp with mvsrplnk.rxp . . . . . . . . 95 Using a BIND Command File . . . . . . . . . . . . . . . 96 Reducing the Number of Build Messages . . . . . . . . . 99 APPENDIX B. SAMPLE REXX TO CREATE BUILD TREES . . . . . . 101 Variations in Creating the Build Trees . . . . . . . . . 103 APPENDIX C. GLOSSARY . . . . . . . . . . . . . . . . . . . 105 x REXX and MVS Build Scripts FIGURES 1. Sample JCL Using LE/370 for RUNPGM . . . . . . . . . . . 3 2. Sample JCL to Compile a PL/I Program . . . . . . . . . . 4 3. Sample JCL-Like Build Script to Compile a PL/I Program 5 4. Sample JCL Using LE/370 for RUNPGMT . . . . . . . . . . 8 5. mvspli Builder Definition When Using REXX Command File for a PL/I Compile . . . . . . . . . . . . . . . . . . . 9 6. mvspli.jcl - Specialized Build Script Using IRXJCL to Pass Control to REXX Command File . . . . . . . . . . 10 7. Build Tree for a PL/I Compile Using REXX Command File 11 8. mvsrxpli.rxp - REXX Command File Supporting DB2, CICS, and PL/I Programs . . . . . . . . . . . . . . . . . . 12 9. PLIPGM.INC - PL/I Include Member . . . . . . . . . . . 25 10. PLIPGM.PLI - PL/I Program . . . . . . . . . . . . . . 26 11. PLIPGM.LNK - PL/I Link Edit Statements . . . . . . . . 26 12. PLIPGM - Build Tree for PL/I Program . . . . . . . . . 27 13. PLIPGM - Connect Commands to Create Build Tree . . . . 27 14. PLIDB2 - PL/I Program with DB2 . . . . . . . . . . . . 28 15. PLIDB2.LNK - PL/I with DB2 Link Edit Statements . . . 28 16. PLIDB2 - Build Tree for PL/I Program with DB2 . . . . 29 17. PLIDB2 - Connect Commands to Create Build Tree . . . . 30 18. PLICICS - PL/I Program with CICS . . . . . . . . . . . 31 19. PLICICS.LNK - PL/I with CICS Link Edit Statements . . 31 20. PLICICS - Build Tree for PL/I Program with CICS . . . 32 21. PLICICS - Connect Commands to Create Build Tree . . . 32 22. PLIDCIC - PL/I Program with DB2 and CICS . . . . . . . 33 23. PLIDCIC.LNK - PL/I with DB2 and CICS Link Edit Statements . . . . . . . . . . . . . . . . . . . . . . 33 24. PLIDCIC - Build Tree for PL/I Program with DB2 and CICS 34 25. PLIDCIC - Connect Commands to Create Build Tree . . . 35 26. Build Trees for Sibling Outputs PLIDB2.OBJ and PLIDB2.DBR . . . . . . . . . . . . . . . . . . . . . . 36 27. Builder Information . . . . . . . . . . . . . . . . . 48 28. mvslnk.jcl - Build Script for Link Edit and Bind . . . 80 29. mvsrplnk.rxp - REXX Command File Supporting Link Edit and Bind . . . . . . . . . . . . . . . . . . . . . . . 84 30. REXX Command File to Create Build Trees . . . . . . . 102 (C) Copyright IBM Corp. 1997 xi xii REXX and MVS Build Scripts BEFORE WE BEGIN This report is written for the TeamConnection user who needs to create build scripts for MVS. Experience should include some familiarity with TeamConnection concepts, MVS build processors, and the REXX language. The sample JCL shown for RUNPGM and RUNPGMT has been customized to use LE/370. The names of the programs and builders have been chosen to indi- cate the type of processing they perform. Any names could be used in their place. The family server was on an OS/2 machine. The technique described in this Technical Report was tested with TeamConnection Version 2.0. (C) Copyright IBM Corp. 1997 1 DISCLAIMER - NOTICE TO USERS OF THE SOURCE CODE EXAMPLES THIS TECHNICAL REPORT PROVIDES THE SOURCE CODE EXAMPLES, BOTH INDIVIDUALLY AND AS ONE OR MORE GROUPS, "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOURCE CODE EXAMPLES, BOTH INDIVIDUALLY AND AS ONE OR MORE GROUPS, IS WITH YOU. SHOULD ANY PART OF THE SOURCE CODE EXAMPLES PROVE DEFECTIVE, YOU (AND NOT IBM OR AN AUTHORIZED DEALER) ASSUME THE ENTIRE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 2 REXX and MVS Build Scripts OVERVIEW TeamConnection supplies 2 MVS jobs that can be used to run an MVS build processor: o RUNPGM, described in "RUNPGM." o RUNPGMT, described in "RUNPGMT" on page 6. RUNPGM RUNPGM, shown in Figure 1, runs the TeamConnection MVS build processor, TEAMPROC, as an MVS batch job. This technique sup- ports build scripts written entirely in a JCL-like language. +---------------------------------------------------------------+ | | | //your job card | | //******************************************************|***/ | //* PROGRAM: RUNPGM | */ | //* JCL to start TeamConnection MVS Build Server | */ | //******************************************************|***/ | //* Some dataset names might need to be modified | */ | //* according to your system's customization | */ | //******************************************************|***/ | //RUNPGM EXEC PGM=TEAMPROC, | | // PARM='ENVAR("_CEE_ENVFILE=DD:EDCENV")/-S @32901 -U VI| -K IBM-1047', | // REGION=4M | | //STEPLIB DD DSN=userid.TEAMC.LOADLIB,DISP=SHR | | // DD DSN=DSNA.DSNLOAD,DISP=SHR | | // DD DSN=SYS1.CEE.SCEERUN,DISP=SHR | | // DD DSN=SYS1.PLI.PLICOMP,DISP=SHR | | //* userid.TEST.JCL must be allocated as a PDS with lrec|=80, | //* and recfm=FB | | //TEAMPROC DD DSN=userid.TEAMC.TEST.JCL,DISP=SHR | | //EDCENV DD DSN=userid.TEAMC.ENVVAR,DISP=SHR | | //STDOUT DD SYSOUT=* | | //STDERR DD SYSOUT=* | | //SYSUDUMP DD SYSOUT=* | | //CEEDUMP DD SYSOUT=* | | // | | | +---------------------------------------------------------------+ Figure 1. Sample JCL Using LE/370 for RUNPGM Build scripts written in the JCL-like language are easy to create from existing JCL. For example, Figure 2 on page 4, shows the (C) Copyright IBM Corp. 1997 3 JCL used to do a PL/I compile without TeamConnection involved. Figure 3 on page 5 shows the corresponding build script for TeamConnection. TCPARM and TCEXT are special TeamConnection keywords that indicate parameters to be passed and file exten- sions for parts respectively. +---------------------------------------------------------------+ | | | //your job card | | //*-----------------------------------------------------|-----------*/ | //* PROGRAM: mvspli.jcl | | //* PL/I for MVS - Compile Only | | //* | | //*-----------------------------------------------------|-----------*/ | //PLICOMP EXEC PGM=IEL0AA,PARM='INCLUDE,OBJECT,NODECK' | | //STEPLIB DD DISP=SHR,DSN=DSNA.DSNLOAD | | // DD DISP=SHR,DSN=SYS1.PLI.PLICOMP | | //SYSIN DD DISP=SHR,DSN=userid.PRIVATE.SOURCE(PLIAPP)| | //SYSLIB DD DISP=SHR,DSN=userid.PRIVATE.SOURCE | | //SYSPRINT DD DISP=SHR,DSN=userid.PRIVATE.SYSPRINT | | //SYSLIN DD DISP=OLD,DSN=userid.TCMVS.OBJ(PLIAPP) | | /* | | //SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA, | | // SPACE=(1024,(200,50),,CONTIG,ROUND),DCB=B|KSIZE=1024 | | +---------------------------------------------------------------+ Figure 2. Sample JCL to Compile a PL/I Program 4 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | //*-----------------------------------------------------|-----------*/ | //* PROGRAM: mvspli.jcl | | //* PL/I for MVS - Compile Only | | //* | | //*-----------------------------------------------------|-----------*/ | //PLICOMP EXEC PGM=IEL0AA, | | // PARM='&TCPARM' | | //SYSIN DD TCEXT=PLI,DISP=(NEW,DELETE), | | // SPACE=(32000,(30,10)),UNIT=SYSDA, | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //SYSLIB DD TCEXT=INC,DISP=(NEW,DELETE), | | // SPACE=(32000,(30,10,5)),UNIT=SYSDA, | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //SYSPRINT DD TCEXT=TCOUT,DISP=(NEW,DELETE), | | // SPACE=(13300,(30,30)),UNIT=SYSDA, | | // DCB=(RECFM=FBA,LRECL=133,BLKSIZE=1330) | | //SYSLIN DD TCEXT=OBJ,UNIT=SYSDA, | | // DISP=(NEW,DELETE),SPACE=(32000,(30,10)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //* | | //SYSUT1 DD DSN=&&SYSUT1,UNIT=SYSDA, | | // SPACE=(1024,(200,50),,CONTIG,ROUND),DCB=B|KSIZE=1024 | | +---------------------------------------------------------------+ Figure 3. Sample JCL-Like Build Script to Compile a PL/I Program OVERVIEW 5 RUNPGMT RUNPGMT, shown in Figure 4 on page 8, runs the TeamConnection MVS build processor, TEAMPROC, under an MVS/TSO session from within an MVS batch job. RUNPGMT was originally developed for use with VisualAge Generator. However, as explained in the sections that follow, RUNPGMT can be used for other languages. RUNPGMT is used to accomplish the build in the following way. o The RUNPGMT job, shown in Figure 4 on page 8, runs the MVS build processor and: 1. Starts IKJEFT01 (an MVS/TSO session). 2. Calls TEAMPROC from within the MVS/TSO session. 3. When the build starts from TeamConnection, the build script specified for the builder is placed in the data set identified by the TEAMPROC DD statement. o The builder definition, shown in Figure 5 on page 9, identi- fies the following: - The source file for the build script. - The parameters for the build script. When using a REXX command file for MVS builds, the first parameter speci- fies the name of the REXX command file that is to run during the build. The other parameters are passed to the REXX command file. The builder definition in this example is for a PL/I compile. o The build script, shown in Figure 6 on page 10, causes the following to happen: - Gives control to program IRXJCL. IRXJCL allows a REXX command file to run under the MVS/TSO session. - The REXX command file must be in the data set identified by the SYSEXEC DD statement. - Other DD statements in the build script support inputs or outputs for the build that must be transferred from / to TeamConnection. In Figure 6 on page 10, the DD state- ments provide the inputs and outputs needed for combina- tions of a DB2 precompile, a CICS translate, and a PL/I compile. This same build script can be used to support several builder definitions. See "Notes on mvspli.jcl (the Build Script)" on page 19 for more a detailed explanation of this build script. 6 REXX and MVS Build Scripts o The build tree, shown in Figure 7 on page 11, includes an input part with a file extension of .rxp. Using TCEXT=RXP on the SYSEXEC DD statement of the build script causes the .rxp part from the build tree to be placed in the temporary data set associated with the SYSEXEC DD statement. The build tree in this example is for a PL/I compile. o The mvsrxpli.rxp part shown in Figure 8 on page 12, does the actual function needed for the build. The mvsrxpli.rxp part handles combinations of a DB2 precompile, a CICS translate, and a PL/I compile. This same REXX command file can be used to support several builder definitions just by varying the parameters specified in the builder definition. See "Notes on mvsrxpli.rxp (the REXX Command File)" on page 20 for more a detailed explana- tion of this REXX command file. Using build scripts for IRXJCL that invokes a REXX command file has the following advantages: o It is easier to combine several steps into a single build script. For example, the REXX command file can pass the output of the DB2 precompiler to the CICS translator and from the CICS translator to the PL/I compiler. o Better performance if the intermediate outputs do not need to be saved in TeamConnection because they do not need to be passed back to the build agent. o Smaller build tree because the intermediate outputs do not need to be shown because they do not need to be saved in TeamConnection. o The same REXX command file can be used to handle several com- binations of translators. For example, the REXX command file shown in Figure 8 on page 12 handles the following: - PL/I - CICS and PL/I - DB2 and PL/I - DB2, CICS, and PL/I OVERVIEW 7 +---------------------------------------------------------------+ | | | //your job card | | //******************************************************|***/ | //* PROGRAM: RUNPGMT | */ | //* JCL to start TeamConnection MVS Build Server under | */ | //* a TSO environment. Primary use is intended for | */ | //* VisualGen support. | */ | //******************************************************|***/ | //* Some dataset names might need to be modified | */ | //* according to your system's customization | */ | //******************************************************|***/ | | | //RUNPGMT EXEC PGM=IKJEFT01,REGION=6M,DYNAMNBR=30 | | //STEPLIB DD DSN=DSNA.DSNLOAD,DISP=SHR | | // DD DSN=userid.TEAMC.LOADLIB,DISP=SHR | | // DD DSN=SYS1.CEE.SCEERUN,DISP=SHR | | // DD DSN=SYS1.COB2COMP,DISP=SHR | | //* userid.TEST.JCL must be allocated as a PDS with lrec|=80, | //* and recfm=FB | | //TEAMPROC DD DSN=userid.TEAMC.TEST.JCL,DISP=SHR | | //EDCENV DD DSN=userid.TEAMC.ENVVAR,DISP=SHR | | //STDOUT DD SYSOUT=* | | //STDERR DD SYSOUT=* | | //SYSUDUMP DD SYSOUT=* | | //CEEDUMP DD SYSOUT=* | | //SYSTSPRT DD SYSOUT=* | | //SYSTSIN DD * | | CALL 'userid.TEAMC.LOADLIB(TEAMPROC)' + | | 'ENVAR("_CEE_ENVFILE=DD:EDCENV")/-S @32911 -U SYSDA|-K IBM-1047' | // | | | +---------------------------------------------------------------+ Figure 4. Sample JCL Using LE/370 for RUNPGMT 8 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | Builder mvspli | | Release release1 | | Script mvspli.jcl | | Environment mvstso | | Comp. oper. <= | | RC value 4 | | File type text | | Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl | | Parameters 'MVSRXPLI N N Y' | | Timeout 10 | | | +---------------------------------------------------------------+ Figure 5. mvspli Builder Definition When Using REXX Command File for a PL/I Compile OVERVIEW 9 +---------------------------------------------------------------+ | | | //REXX EXEC PGM=IRXJCL, | | // PARM=&TCPARM | | //* | | //* BUILD SCRIPT FOR EXECUTING A REXX PROGRAM TO DO PL/I|COMPILES | //* | | //* TEAMPROC MUST RUN IN A TSO ADDRESS SPACE | | //* | | //* IRXJCL RUNS THE PROGRAM NAMED IN THE FIRST PARAMETER|OF &TCPARM | //* AS A REXX PROGRAM AND PASSES THE REMAINING PARAMETER| | //* | | //* IRXJCL LOOKS INTO SYSEXEC FOR THE REXX PROGRAM | | //* | | //SYSEXEC DD TCEXT=RXP,DISP=(NEW,DELETE), | (1) | // UNIT=VIO,SPACE=(32000,(30,10,5)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //DBRM DD TCEXT=DBR,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(32000,(30,10,5)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160) | | //SOURCE DD TCEXT=PLI,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(32000,(30,10)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //INCSRC DD TCEXT=INC,DISP=(NEW,DELETE), | (2) | // UNIT=SYSDA,SPACE=(32000,(30,10,5)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //OBJECT DD TCEXT=OBJ,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(32000,(30,10)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //ERRLIST TCEXT=TCOUT,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(13300,(30,30)), | | // DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330) | | //OUTLIST DD * | (3) | &TCOUTPUT | | // | | | +---------------------------------------------------------------+ Figure 6. mvspli.jcl - Specialized Build Script Using IRXJCL to Pass Control to REXX Command File 10 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | *---------------* Key: (+) - D|pendencies | | plipgm.obj | a|ded by parser | | builder = | (I) - I|put | | mvspli | (O) - O|tput | *---------------* | | | *---------------* | | | (+) (I)| plipgm.pli | | | |-----------| parser = | | | | | pliprs | | | | *---------------* | | | | | | *---------------* | | | (I)| mvsrxpli.rxp | | | *-----------| | | | *---------------* | | | +---------------------------------------------------------------+ Figure 7. Build Tree for a PL/I Compile Using REXX Command File OVERVIEW 11 +---------------------------------------------------------------+ | | | /* REXX */ | | TRACE INTERMEDIATES | | | | parse arg db2 cics plicmp otherparms | (1) | /*******************************************************|*************/ | /* INITIALIZATION | */ | /*******************************************************|*************/ | | (2) | wspc = 500 /* Space allocati|n default */ | | | dsnload = 'DSNA.DSNLOAD' /* DB2 libraries | */ | | | dfhload = 'CICS330.SDFHLOAD' /* CICS libraries|/ variables */ | cics_suffix = '1$' | | | | plicomp = 'SYS1.PLI.PLICOMP' /* PLI libraries | */ | | | /*******************************************************|*************/ | /* RETRIEVE DATASET NAMES FOR FILES DEFINED IN THE BUILD|SCRIPT */ | /*******************************************************|*************/ | | (3) | dsinfo = getdsn_last('DBRM') | | if dsinfo > 0 then | | call errorhndlr GETDBRM,dsinfo | | dbrmlib = SYSDSNAME | | | | dsinfo = getdsn_last('SOURCE') | | if dsinfo > 0 then | | call errorhndlr GETSOURCE,dsinfo | | srclib = SYSDSNAME | | | | dsinfo = getdsn_last('INCSRC') | | if dsinfo > 0 then | | call errorhndlr GETINCSRC,dsinfo | | cpysrc = SYSDSNAME | | | | dsinfo = getdsn_last('OBJECT') | | if dsinfo > 0 then | | call errorhndlr GETOBJECT,dsinfo | | objlib = SYSDSNAME | | | +---------------------------------------------------------------+ Figure 8 (Part 1 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs 12 REXX and MVS Build Scripts +---------------------------------------------------------------+ | /*******************************************************|*************/ | /* FORCE DB2, CICS, AND PLICMP PARAMETERS TO Y OR N | */ | /*******************************************************|*************/ | | (4) | if db2 <> 'Y' then | | db2 = 'N' | | if cics <> 'Y' then | | cics = 'N' | | if plicmp <> 'Y' then | | plicmp = 'N' | | | | /*******************************************************|*************/ | /* CALL APPROPRIATE ROUTINES | */ | /*******************************************************|*************/ | | (5) | if db2 = 'Y' then | | do | | call getdbrmnam | | call precompile | | end | | if cics = 'Y' then | | call translate | | if plicmp = 'Y' then | | call compile | | | | exit 0 | | | +---------------------------------------------------------------+ Figure 8 (Part 2 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs OVERVIEW 13 +---------------------------------------------------------------+ | precompile: | | /*******************************************************|*************/ | /* ALLOCATE THE DATASETS NECESSARY FOR THE DB2 PRECOMPI|E. */ | /* THE DATASET ALLOCATED TO THE SYSCIN DD IS PASSED TO |ITHER THE */ | /* THE TRANSLATE OR COMPILE SUBROUTINE DEPENDING ON WHE|HER CICS IS */ | /* INVOLVED OR NOT. | */ | /*******************************************************|*************/ | | (6) | "ALLOC FI(DBRMLIB) DA('"dbrmlib"("dbrmmbr")') OLD REUSE| | "ALLOC FI(SYSCIN) BLOCK(800) SPACE("wspc","wspc") UNIT|SYSDA) REUSE" | "ALLOC FI(SYSLIB) DA('"cpysrc"') SHR REUSE" | (7) | "ALLOC FI(SYSPRINT) DUMMY REUSE" | | "ALLOC FI(SYSTERM) BLOCK(800) SPACE("wspc","wspc") UNIT|SYSDA) REUSE" | "ALLOC FI(SYSUT1) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSUT2) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSIN) DA('"srclib"') SHR REUSE" | | | | "CALL '"dsnload"(DSNHPC)' 'HOST(PLI)'" | (8) | precompile_rc = rc | | | | "FREE FI(DBRMLIB,SYSLIB,SYSPRINT,SYSUT1,SYSUT2,SYSIN)" | | if precompile_rc < 0 | precompile_rc > 4 then | (9) | do | | "FREE FI(SYSCIN)" | | call errorhndlr PRECOMPILE,precompile_rc,SYSTERM | | end | | else | | call TCOUThndlr PRECOMPILE,precompile_rc,SYSTERM | (10) | | | return | | | +---------------------------------------------------------------+ Figure 8 (Part 3 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs 14 REXX and MVS Build Scripts +---------------------------------------------------------------+ | translate: | | /*******************************************************|*************/ | /* ALLOCATE THE DATASETS NECESSARY FOR THE CICS TRANSLA|OR. */ | /*******************************************************|*************/ | | (11) | "ALLOC FI(SYSPRINT) SPACE("wspc","wspc") UNIT(SYSDA) RE|SE" | "ALLOC FI(SYSPUNCH) BLOCK(800) SPACE("wspc","wspc") UNI|(SYSDA) REUSE" | | | /*********************************************/ | | /* IF DB2 WAS USED */ | | /* THEN */ | | /* ALLOCATE SYSCIN TO SYSIN */ | | /* ELSE */ | | /* ALLOCATE SYSIN TO THE BUILD OBJECT */ | | /*********************************************/ | | | (12) | if db2 = 'Y' then | | call realloc SYSCIN,SYSIN | | else | | "ALLOC FI(SYSIN) DA('"srclib"') SHR REUSE" | | | | "CALL '"dfhload"(DFHEPP"cics_suffix")'", | (13) | "'NOSOURCE'" | | translate_rc = rc | | | | "FREE FI(SYSCIN SYSIN)" | | if translate_rc < 0 | translate_rc > 4 then | (14) | do | | "FREE FI(SYSPUNCH)" | | call errorhndlr TRANSLATE,translate_rc,SYSPRINT | | end | | else | | call TCOUThndlr TRANSLATE,translate_rc,SYSPRINT | (15) | | | return | | | +---------------------------------------------------------------+ Figure 8 (Part 4 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs OVERVIEW 15 +---------------------------------------------------------------+ | compile: | | /*******************************************************|*************/ | /* COMPILE ALLOCATES THE DATASETS NECESSARY TO COMPILE |HE */ | /* REQUESTED OBJECT. | */ | /*******************************************************|*************/ | /*********************************************/ | | /* IF CICS WAS USED */ | | /* THEN */ | | /* ALLOCATE SYSPUNCH TO SYSIN */ | | /* ELSE */ | | /* IF DB2 WAS USED */ | | /* THEN */ | | /* ALLOCATE SYSCIN TO SYSIN */ | | /* ELSE */ | | /* ALLOCATE SYSIN TO THE BUILD OBJECT */ | | /*********************************************/ | | | (16) | if cics = 'Y' then | | call realloc SYSPUNCH,SYSIN | | else | | if db2 = 'Y' then | | call realloc SYSCIN,SYSIN | | else | | "ALLOC FI(SYSIN) DA('"srclib"') SHR REUSE" | | | (17) | "ALLOC FI(SYSLIB) DA('"cpysrc"') SHR REUSE" | (18) | "ALLOC FI(SYSLIN) DA('"objlib"') SHR REUSE" | | "ALLOC FI(SYSUT1) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSUT2) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSUT3) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSUT4) BLOCK(800) SPACE("wspc","wspc") UNIT|VIO) REUSE" | "ALLOC FI(SYSPRINT) BLOCK(800) SPACE("wspc","wspc") UNIT|SYSDA) REUSE" | | (19) | pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,OPT(2),NOSOUR|E' | if cics = 'Y' then | | pliopts = pliopts || ',SYSTEM(CICS)' | | | | "CALL '"plicomp"(IEL0AA)' '"pliopts"'" | | | | compile_rc = rc | | | | "FREE FI(SYSUT1,SYSUT2,SYSUT3,SYSUT4)" | | "FREE FI(SYSPUNCH SYSCIN SYSIN,SYSLIB,SYSLIN)" | | if compile_rc < 0 | compile_rc > 4 then | (20) | call errorhndlr COMPILE,compile_rc,SYSPRINT | | else | | call TCOUThndlr COMPILE,compile_rc,SYSPRINT | (21) | | | return | +---------------------------------------------------------------+ Figure 8 (Part 5 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs 16 REXX and MVS Build Scripts +---------------------------------------------------------------+ | realloc: procedure | | /*******************************************************|*************/ | /* REALLOCATE A FILE TO A PREVIOUS DATA SET | */ | /*******************************************************|*************/ | parse arg oldddname, newddname | | dsinfo = getdsn_last(oldddname) | | "ALLOC FI("newddname") DSN('"SYSDSNAME"') SHR REUSE" | | return | | | | getdsn_last: procedure expose sysdsname sysmsglvl1 sysms|lvl2 | /*******************************************************|*************/ | /* DETERMINE DATA SET NAME OF A TEMPORARY FILE | */ | /*******************************************************|*************/ | parse arg ddname parm_rest | | getdsn ddname | | getdsn_rc = rc | | if getdsn_rc < 0 | getdsn_rc > 0 then | | sysdsname = '' | | else | | do | | last_dsn = sysdsname.0 | | sysdsname = sysdsname.last_dsn | | end | | return getdsn_rc | | | | | | getdbrmnam: procedure expose dbrmmbr | (22) | /*******************************************************|*************/ | /* DETERMINE NAME OF PL/I SOURCE FOR USE AS DBRM MEMBER|NAME */ | /*******************************************************|*************/ | dsinfo = getdsn_last('OUTLIST') | | if dsinfo > 0 then | | call errorhndlr GETOUTLIST,dsinfo | | | | myoutput. = '' | | "ALLOC FI(OUTLISTX) DA('"SYSDSNAME"') SHR REUSE" | | "execio * diskr OUTLISTX (stem myoutput. open finis)" | | | | /* OUTLIST contains one line for each output in the buil| tree. */ | /* Because the file extension is removed, the OBJ and DB|M outputs */ | /* cannot be distinguished. Use the naming convention o| xxxxx.OBJ */ | /* and xxxxx.DBR for the object module and DBRM respecti|ely. */ | /* This means it does not matter which line of OUTLIST i| used to */ | /* set dbrmmbr. | */ | | | dbrmmbr = word(myoutput.1,1) | | | | return | | | +---------------------------------------------------------------+ Figure 8 (Part 6 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs OVERVIEW 17 +---------------------------------------------------------------+ | TCOUThndlr: procedure expose sysmsglvl1 sysmsglvl2 | (23) | /*******************************************************|*************/ | /* SAVE PRINT LISTINGS FROM EACH STEP TO RETURN TO TEAM|ONNECTION */ | /*******************************************************|*************/ | parse arg function, return_code, copyddname | | dsinfo = getdsn_last('ERRLIST') | | "ALLOC FI(ERROUT) DA('"SYSDSNAME"') MOD REUSE" | | if copyddname <> '' then | | do | | "execio * diskr "copyddname" (stem errvar. open fini|)" | "execio * diskw errout (STEM errvar. open finis)" | | "FREE FI("copyddname")" | | end | | else | | 'EXECIO 2 DISKW ERROUT (STEM sysmsglvl OPEN FINIS)' | | "FREE FI(ERROUT)" | | | | return | | | | | | errorhndlr: procedure expose sysmsglvl1 sysmsglvl2 | (24) | /*******************************************************|*************/ | /* ISSUE ERROR MESSAGE FOR FUNCTION, ERROR CODE, AND DA|A SET */ | /*******************************************************|*************/ | parse arg function, return_code, copyddname | | dsinfo = getdsn_last('ERRLIST') | | "ALLOC FI(ERROUT) DA('"SYSDSNAME"') MOD REUSE" | | if copyddname <> '' then | | do | | "execio * diskr "copyddname" (stem errvar. open fini|)" | "execio * diskw errout (STEM errvar. open finis)" | | "FREE FI("copyddname")" | | end | | else | | 'EXECIO 2 DISKW ERROUT (STEM sysmsglvl OPEN FINIS)' | | "FREE FI(ERROUT)" | | exit(return_code) | | | | | +---------------------------------------------------------------+ Figure 8 (Part 7 of 7). mvsrxpli.rxp - REXX Command File Sup- porting DB2, CICS, and PL/I Programs 18 REXX and MVS Build Scripts HOW THE BUILDER DEFINITION, IRXJCL, AND THE REXX COMMAND FILE WORK This section describes how the builder definition, the build script, and the REXX command file work together to control the build for the object module. DEFINING THE BUILDER When IRXJCL is used in the build script, the parameters for the builder define which REXX command file is used during the build. For example, in the builder definition: Builder mvspli Release release1 Script mvspli.jcl Environment mvstso Comp. oper. <= RC value 4 File type text Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl Parameters 'MVSRXPLI N N Y' Timeout 10 the parameters are: MVSRXPLI Name of the REXX command file that is run by IRXJCL. IRXJCL always expects the first parameter to be the name of the REXX command file. N N Y Correspond to the parameters expected by MVSRXPLI. The SCRIPT name is the name of the build script in Figure 6 on page 10. NOTES ON MVSPLI.JCL (THE BUILD SCRIPT) The following notes correspond to the numbers in the right margin of the mvspli.jcl build script, shown in Figure 6 on page 10. The notes explain concepts used in the build script. NOTE: 1. The SYSEXEC DD statement must point to the library where the REXX command file resides. In this example, mvsrxpli.rxp is included in the build tree for the part. Because mvsrxpli.rxp has the file extension of .rxp, TCEXT=RXP causes mvsrxpli.rxp to be placed in the temporary data set allocated (C) Copyright IBM Corp. 1997 19 to the SYSEXEC DD statement. This makes mvsrxpli.rxp avail- able to the IRXJCL program. 2. The INCSRC DD statement is the temporary library where include members that are maintained on TeamConnection will be placed. This assumes that all the include members have the file extension of .inc. 3. The OUTLIST DD statement is used by mvsrxpli.rxp to obtain the names of the output parts. &TCOUTPUT results in multiple lines of in-stream data, with each line corresponding to one output part. The output parts included are based on the build tree. The file extensions are not included. Using a naming convention where the object module name and DBRM member have the same part name except for the file extension allows mvsrxpli.rxp to determine the name of the DBRM member that is created by the precompiler. For example, if the object module name is plidb2.obj, the corresponding DBRM name is plidb2.dbr. Thus mvsrxpli.rxp does not need to determine which of the lines within the OUTPUT DD statement is really the DBRM. NOTES ON MVSRXPLI.RXP (THE REXX COMMAND FILE) The following notes correspond to the numbers in the right margin of the mvsrxpli.rxp REXX command file, shown in Figure 8 on page 12. The notes explain concepts used in the REXX command file. NOTE: 1. The parameters for mvsrxpli.rxp are: DB2 Y/N flag indicating whether a DB2 precompile is required CICS Y/N flag indicating whether a CICS translate is required PLICMP Y/N flag indicating whether a PL/I compile is required OTHERPARMS Other parameters could be added in the future. For example, to control the options for the DB2 precompiler, CICS translator, and/or PL/I compiler. 2. The initialization statements set the names of the MVS host libraries and other variables used in the REXX command file. You might need to change the names of the libraries to match the data set naming conventions for your organization. 20 REXX and MVS Build Scripts 3. Determine the names of the temporary data sets that were allocated to various DD statements. 4. Insure that the db2, cics, and plicmp parameters have only Y or N values. 5. Call the correct (internal) subroutines based on the parame- ters that were passed to mvsrxpli.rxp. 6. Allocate data sets that are used by the DB2 precompiler. The data sets allocated here correspond to the data sets that are used in your current JCL for the DB2 precompiler. 7. Allocate the temporary data set that contains the include members that are maintained on TeamConnection. 8. Invoke the DB2 precompiler, specifying the parameters to be used. The parameters are hard-coded in this example. 9. If there was an error, free the output data set where the PL/I source that was expanded by the DB2 precompiler is normally placed. Also call the errorhndlr routine to format the DB2 precompiler messages to go back to TeamConnection. The errorhndlr routine exits from the mvsrxpli.rxp REXX command file. 10. If there were no errors, call the TCOUThndlr routine to save the messages and other information that were written to the SYSTERM file by the DB2 precompiler. The TCOUThndlr routine saves the same information as the errorhndlr routine, but does not cause an exit from the mvsrxpli.rxp REXX command file. 11. Allocate data sets that are used by the CICS translator. The data sets allocated here correspond to the data sets that are used in your current JCL for the CICS translator. 12. If the DB2 precompiler was run, reallocate the file con- taining the expanded PL/I source from the DB2 precompiler to the file where the CICS translator expects the PL/I source to be located. If the DB2 precompiler was not run, allocate the file where the CICS translator expects the PL/I source to be located to the input being passed from TeamConnection. 13. Invoke the CICS precompiler, specifying the parameters to be used. The parameters are hard-coded in this example. 14. If there was an error, free the output data set where the PL/I source that was expanded by the CICS translator is normally placed. Also call the errorhndlr routine to format the CICS translator messages to go back to TeamConnection. The errorhndlr routine exits from the mvsrxpli.rxp REXX command file. HOW THE BUILDER DEFINITION, IRXJCL, AND THE REXX COMMWORKFI21 15. If there were no errors, call the TCOUThndlr routine to save the messages and other information that were written to the SYSPRINT file by the CICS translator. The TCOUThndlr routine saves the same information as the errorhndlr routine, but does not cause an exit from the mvsrxpli.rxp REXX command file. 16. If the CICS translator was run, reallocate the file con- taining the expanded PL/I source from the CICS translator to the file where the PL/I compiler expects the PL/I source to be located. If the CICS was not run and the DB2 precompiler was run, reallocate the file containing the expanded PL/I source from the DB2 precompiler to the file where the PL/I compiler expects the PL/I source to be located. If neither the PL/I translator nor the DB2 precompiler were run, allo- cate the file where the PL/I compiler expects the PLI source to be located to the input being passed from TeamConnection. 17. Allocate the remaining data sets that are used by the PL/I compiler. The data sets allocated here correspond to the data sets that are used in your current JCL for the PL/I com- piler. 18. Allocate the data set that contains the include members that are maintained on TeamConnection. 19. Invoke the PL/I compiler, specifying the parameters to be used. The parameters are hard-coded in this example. Note that different parameters can be used depending on whether the CICS translator was run or not. 20. If there was an error, call the errorhndlr routine to format the PL/I compiler messages to go back to TeamConnection. The errorhndlr routine exits from the mvsrxpli.rxp REXX command file. 21. If there were no errors, call the TCOUThndlr routine to save the messages and other information that were written to the SYSPRINT file by the PL/I compiler. The TCOUThndlr routine saves the same information as the errorhndlr routine, but does not cause an exit from the mvsrxpli.rxp REXX command file. 22. Use the OUTLIST DD statement as a way of determining the output parts. Because &TCOUTPUT in the IRXJCL job shown in Figure 6 on page 10 removes the file extension from the output parts, this technique relies on having naming con- ventions such that the DBRM output part and the object module have the same part name. For example, plidb2.dbr and plidb2.obj are the names of the DBRM and the object module respectively. 23. The TCOUThndlr routine can be called whenever there is infor- mation that you want to save from a step in the REXX command 22 REXX and MVS Build Scripts file. In mvsrxpli.rxp, TCOUThndlr is called to save the information from the DB2 precompiler, CICS translator, and PL/I compiler steps. It is identical to the errorhndlr routine, except that TCOUThndlr returns to the invoking routine, while the errorhndlr exits from mvsrxpli.rxp. 24. The errorhndlr routine is only called when an unacceptable return code has occurred in the precompile, translate, compile, and so on. It copies the error information from a file such as the compiler's SYSPRINT to the temporary data set associated with the ERRLIST DD statement in the IRXJCL job shown in Figure 6 on page 10. Because the ERRLIST DD statement includes the parameter TCEXT=TCOUT, it causes any output placed in this data set to be sent back to TeamConnection and to appear in the VIEW BUILD MESSAGE for the part that was built. HOW THE BUILDER DEFINITION, IRXJCL, AND THE REXX COMMWORKFI23 24 REXX and MVS Build Scripts SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE This section contains sample parts and their corresponding build trees. The build trees are shown with the following assumptions: o mvsrxpli.rxp (the REXX command file for DB2 precompile, CICS translate, and PL/I compile shown in Figure 8 on page 12) IS NOT stored on the MVS host. Therefore it is necessary to include mvsrxpli.rxp as input to the .obj part. o mvsrplnk.rxp (the REXX command file for link edit and DB2 bind shown in Figure 29 on page 84) IS stored on the MVS host. Therefore mvsrplnk.rxp must not be included as input to the .lkd part. A REXX command file can be used to create any of the build trees shown below. See Appendix B, "SAMPLE REXX TO CREATE BUILD TREES" on page 101 for a sample REXX command file. SIMPLE PL/I PROGRAM INCLUDE MEMBER +---------------------------------------------------------------+ | | | DCL 1 HDR, | | 5 ASA CHAR(1) INIT(' '), | | 5 OUTDATA CHAR(132) INIT('TEAMCONNECTION INCLU|E STATEMENT'); | | +---------------------------------------------------------------+ Figure 9. PLIPGM.INC - PL/I Include Member (C) Copyright IBM Corp. 1997 25 PL/I PROGRAM, LINK EDIT STATEMENTS, AND BUILD TREE +---------------------------------------------------------------+ | | | PLIPGM: PROC OPTIONS(MAIN); | | /* */ | | /* Simple program for testing PL/I compiler */ | | /* */ | | %INCLUDE PLIPGM; | | | | PUT LIST('PLIPGM STARTS'); | | PUT LIST('PLIPGM ENDS'); | | END; | | | +---------------------------------------------------------------+ Figure 10. PLIPGM.PLI - PL/I Program +---------------------------------------------------------------+ | | | INCLUDE OBJECT(PLIPGM) | | NAME PLIPGM(R) | | | +---------------------------------------------------------------+ Figure 11. PLIPGM.LNK - PL/I Link Edit Statements 26 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | *--------------* Key: (+) - D|pendencies are | | plipgm.lkd | a|ded by parser | | builder = | (I) - I|put | | mvsplilnk | (O) - O|tput | *--------------* | | | *---------------* | | | (I)| plipgm.lnk | | | |-----------| | | | | *---------------* | | | | | | *---------------* | | | (I)| plipgm.obj | | | *-----------| builder = | | | | mvspli | | | *---------------* | | | *---------------*| | | (+) (I)| plipgm.pli || | |-----------| parser = || | | | pliprs || | | *---------------*| | | | | | *---------------*| | | (I)| mvsrxpli.rxp || | *-----------| || | *---------------*| | | +---------------------------------------------------------------+ Figure 12. PLIPGM - Build Tree for PL/I Program +---------------------------------------------------------------+ | | | teamc Part -connect plipgm.pli -type TCPart -release |elease1 -workarea initwa | -parent plipgm.obj -input | | teamc Part -connect mvsrxpli.rxp -type TCPart -release |elease1 -workarea initwa | -parent plipgm.obj -input | | teamc Part -connect plipgm.obj -type TCPart -release |elease1 -workarea initwa | -parent plipgm.lkd -input | | teamc Part -connect plipgm.lnk -type TCPart -release |elease1 -workarea initwa | -parent plipgm.lkd -input | | | +---------------------------------------------------------------+ Figure 13. PLIPGM - Connect Commands to Create Build Tree SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 27 PL/I WITH DB2 PROGRAM, LINK EDIT STATEMENTS, AND BUILD TREE +---------------------------------------------------------------+ | | | PLIDB2: PROC OPTIONS(MAIN); | | /* */ | | /* Simple program for testing DB2 precompiler */ | | /* */ | | %INCLUDE PLIPGM; | | | | EXEC SQL | | DECLARE EZE001001WDT15A | | CURSOR FOR | | SELECT | | CURRENT TIMESTAMP | | FROM | | TURBO.MESSAGE T1 | | ; | | | | PUT LIST('PLIDB2 STARTS'); | | PUT LIST('PLIDB2 ENDS'); | | END; | | | +---------------------------------------------------------------+ Figure 14. PLIDB2 - PL/I Program with DB2 +---------------------------------------------------------------+ | | | INCLUDE OBJECT(PLIDB2) | | INCLUDE SYSLIB(DSNELI) | | NAME PLIDB2(R) | | | +---------------------------------------------------------------+ Figure 15. PLIDB2.LNK - PL/I with DB2 Link Edit Statements 28 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | *--------------* Key: (+) - D|pendencies are | | plidb2.lkd | a|ded by parser | | builder = | (I) - I|put | | mvsdb2plilnk | (O) - O|tput | *--------------* | | | *---------------* | | | (I)| plidb2.lnk | | | |-----------| | | | | *---------------* | | | | | | *---------------* | | | (I)| plidb2.obj | | | |-----------| builder = | | | | | mvsdb2pli | | | | *---------------* | | | | *---------------*| | | | (+) (I)| plidb2.pli || | | |-----------| parser = || | | | | pliprs || | | | *---------------*| | | | | | | | *---------------*| | | | (I)| mvsrxpli.rxp || | | |-----------| || | | | *---------------*| | | | | | | | *---------------*| | | | (O)| plidb2.dbr || | | *-----------| (sibling || | | | output) || | | *---------------*| | | | | | | | | *---------------* (build tree diagra| in TeamConnection | | (I)| plidb2.dbr | shows + for expan|ion; | |-----------| | see "Sibling Outp|t Build Trees" | | *---------------* for discussion) | | | | | | *---------------* | | | (O)| plidb2.msg | | | *-----------| | | | *---------------* | | | +---------------------------------------------------------------+ Figure 16. PLIDB2 - Build Tree for PL/I Program with DB2 SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 29 +---------------------------------------------------------------+ | | | teamc Part -connect plidb2.pli -type TCPart -release |elease1 -workarea initwa | -parent plidb2.obj -input | | teamc Part -connect mvsrxpli.rxp -type TCPart -release |elease1 -workarea initwa | -parent plidb2.obj -input | | teamc Part -connect plidb2.dbr -type TCPart -release |elease1 -workarea initwa | -parent plidb2.obj -output | | teamc Part -connect plidb2.dbr -type TCPart -release |elease1 -workarea initwa | -parent plidb2.lkd -input | | teamc Part -connect plidb2.obj -type TCPart -release |elease1 -workarea initwa | -parent plidb2.lkd -input | | teamc Part -connect plidb2.lnk -type TCPart -release |elease1 -workarea initwa | -parent plidb2.lkd -input | | teamc Part -connect plidb2.msg -type TCPart -release |elease1 -workarea initwa | -parent plidb2.lkd -output | | | +---------------------------------------------------------------+ Figure 17. PLIDB2 - Connect Commands to Create Build Tree The DBRM member (plidb2.dbr) is output from the build of the object module and input to the build for the load module. This insures that the link edit and bind are done on the same MVS host and at the same time to avoid a mismatch in the date/time stamp for the load module and DB2 package. The message member (plidb2.msg) is output from the build of the load module. It is used to assist in determining the number of .obj / .dbr pairs in the build. This is done by matching the .msg part with the .lnk part. For further details, see Appendix A, "BUILDER, BUILD SCRIPT, AND REXX FOR LINK EDIT AND BIND" on page 79. 30 REXX and MVS Build Scripts PL/I WITH CICS PROGRAM, LINK EDIT STATEMENTS, AND BUILD TREE +---------------------------------------------------------------+ | | | PLICICS: PROC OPTIONS(MAIN); | | /* */ | | /* Simple program for testing CICS translator */ | | /* */ | | %INCLUDE PLIPGM; | | DCL EYE_CATCHER CHAR(50) INIT('PLICICS PROGRAM'); | | DCL TIME_INFO FIXED DEC(15); | | EXEC CICS ASKTIME ABSTIME(TIME_INFO); | | END; | | | +---------------------------------------------------------------+ Figure 18. PLICICS - PL/I Program with CICS +---------------------------------------------------------------+ | | | INCLUDE SYSLIB(DFHPL1OI) | | REPLACE PLISTART | | INCLUDE OBJECT(PLICICS) | | NAME PLICICS(R) | | | +---------------------------------------------------------------+ Figure 19. PLICICS.LNK - PL/I with CICS Link Edit Statements SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 31 +---------------------------------------------------------------+ | | | *--------------* Key: (+) - D|pendencies are | | plicics.lkd | a|ded by parser | | builder = | (I) - I|put | | mvscicsplilnk| (O) - O|tput | *--------------* | | | *---------------* | | | (I)| plicics.lnk | | | |-----------| | | | | *---------------* | | | | | | *---------------* | | | (I)| plicics.obj | | | *-----------| builder = | | | | mvscicspli | | | *---------------* | | | *---------------*| | | (+) (I)| plicics.pli || | |-----------| parser = || | | | pliprs || | | *---------------*| | | | | | *---------------*| | | (I)| mvsrxpli.rxp || | *-----------| || | *---------------*| | | +---------------------------------------------------------------+ Figure 20. PLICICS - Build Tree for PL/I Program with CICS +---------------------------------------------------------------+ | | | teamc Part -connect plicics.pli -type TCPart -release |elease1 -workarea initwa | -parent plicics.obj -input | | teamc Part -connect mvsrxpli.rxp -type TCPart -release |elease1 -workarea initwa | -parent plicics.obj -input | | teamc Part -connect plicics.obj -type TCPart -release |elease1 -workarea initwa | -parent plicics.lkd -input | | teamc Part -connect plicics.lnk -type TCPart -release |elease1 -workarea initwa | -parent plicics.lkd -input | | | +---------------------------------------------------------------+ Figure 21. PLICICS - Connect Commands to Create Build Tree 32 REXX and MVS Build Scripts PL/I WITH DB2 AND CICS PROGRAM, LINK EDIT STATEMENTS, AND BUILD TREE +---------------------------------------------------------------+ | | | PLIDCIC: PROC OPTIONS(MAIN); | | /* */ | | /* Simple program for testing DB2 precompiler */ | | /* and CICS translator */ | | /* */ | | %INCLUDE PLIPGM; | | DCL EYE_CATCHER CHAR(50) INIT('PLIDCIC PROGRAM'); | | DCL TIME_INFO FIXED DEC(15); | | | | EXEC SQL | | DECLARE EZE001001WDT15A | | CURSOR FOR | | SELECT | | CURRENT TIMESTAMP | | FROM | | TURBO.MESSAGE T1 | | ; | | | | EXEC CICS ASKTIME ABSTIME(TIME_INFO); | | | | END; | | | +---------------------------------------------------------------+ Figure 22. PLIDCIC - PL/I Program with DB2 and CICS +---------------------------------------------------------------+ | | | INCLUDE SYSLIB(DFHPL1OI) | | REPLACE PLISTART | | INCLUDE OBJECT(PLIDCIC) | | INCLUDE SYSLIB(DSNCLI) | | NAME PLIDCIC(R) | | | +---------------------------------------------------------------+ Figure 23. PLIDCIC.LNK - PL/I with DB2 and CICS Link Edit State- ments SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 33 +---------------------------------------------------------------+ | | | *------------------* Key: (+) - D|pendencies are | | plidcic.lkd | a|ded by parser | | builder = | (I) - I|put | | mvsdb2cicsplilnk | (O) - O|tput | *------------------* | | | *---------------* | | | (I)| plidcic.lnk | | | |-----------| | | | | *---------------* | | | | | | *---------------* | | | (I)| plidcic.obj | | | |-----------| builder = | | | | | mvsdb2cicspli | | | | *---------------* | | | | *---------------*| | | | (+) (I)| plidcic.pli || | | |-----------| parser = || | | | | pliprs || | | | *---------------*| | | | | | | | *---------------*| | | | (I)| mvsrxpli.rxp || | | |-----------| || | | | *---------------*| | | | | | | | *---------------*| | | | (O)| plidcic.dbr || | | *-----------| (sibling || | | | output) || | | *---------------*| | | | | | | | | *---------------* (build tree diagra| in TeamConnection | | (I)| plidcic.dbr | shows + for expan|ion; | |-----------| | see "Sibling Outp|t Build Trees" | | *---------------* for discussion) | | | | | | *---------------* | | | (O)| plidcic.msg | | | *-----------| | | | *---------------* | | | +---------------------------------------------------------------+ Figure 24. PLIDCIC - Build Tree for PL/I Program with DB2 and CICS 34 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | teamc Part -connect plidcic.pli -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.obj -input | | teamc Part -connect mvsrxpli.rxp -type TCPart -release |elease1 -workarea initwa | -parent plidcic.obj -input | | teamc Part -connect plidcic.dbr -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.obj -output | | teamc Part -connect plidcic.dbr -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.lkd -input | | teamc Part -connect plidcic.obj -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.lkd -input | | teamc Part -connect plidcic.lnk -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.lkd -input | | teamc Part -connect plidcic.msg -type TCPart -release r|lease1 -worka rea initwa | -parent plidcic.lkd -output | | | +---------------------------------------------------------------+ Figure 25. PLIDCIC - Connect Commands to Create Build Tree The DBRM member (plidcic.dbr) is output from the build of the object module and input to the build for the load module. This insures that the link edit and bind are done on the same MVS host and at the same time to avoid a mismatch in the date/time stamp for the load module and DB2 package. The message member (plidcic.msg) is output from the build of the load module. It is used to assist in determining the number of .obj / .dbr pairs in the build. This is done by matching the .msg part with the .lnk part. For further details, see Appendix A, "BUILDER, BUILD SCRIPT, AND REXX FOR LINK EDIT AND BIND" on page 79. SIBLING OUTPUT BUILD TREES As shown in Figure 16 on page 29 and Figure 24 on page 34, you can connect additional output part(s) to a part that will be built. For example, in Figure 16 on page 29: o plidb2.dbr is an output of plidb2.obj. o plidb2.msg is an output of plidb2.lkd. In TeamConnection terms, plidb2.dbr and plidb2.obj are SIBLING OUTPUTS. Similarly, plidb2.msg and plidb2.lkd are sibling outputs. Sibling outputs have the following effects on part properties: SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 35 o When a builder is assigned or changed for one part, the same change occurs for both parts. o Any parameters specified for the build of one part are used for building both parts. Sibling outputs have the following effects on the build tree diagram: o Expansion of either sibling output part shows the other sibling as an output. For example, the build trees for plidb2.obj and plidb2.dbr are shown in Figure 26. +---------------------------------------------------------------+ | | | Key: (+) - D|pendencies are | a|ded by parser | (I) - I|put | (O) - O|tput | | | *---------------* *------------|--* | | plidb2.obj | | plidb2.dbr | | | | builder = | | builder = | | | | mvsdb2pli | | mvsdb2pli | | | *---------------* *------------|--* | | *---------------* | | *---------------* | | (+) (I)| plidb2.pli | | (|) (I)| plidb2.pli | | |-----------| parser = | |-----|-----| parser = | | | | pliprs | | | | pliprs | | | *---------------* | | *---------------* | | | | | | *---------------* | | *---------------* | | (I)| mvsrxpli.rxp | | | (I)| mvsrxpli.rxp | | |-----------| | |-----|-----| | | | *---------------* | | *---------------* | | | | | | *---------------* | | *---------------* | | (O)| plidb2.dbr | | | (O)| plidb2.obj | | *-----------| (sibling | *-----|-----| (sibling | | | output) | | | output) | | *---------------* | *---------------* | | +---------------------------------------------------------------+ Figure 26. Build Trees for Sibling Outputs PLIDB2.OBJ and PLIDB2.DBR o When the sibling is shown as an output part, there is no part expansion in the TeamConnection build tree diagram. For example, in Figure 16 on page 29, plidb2.msg only appears as an output part. The TeamConnection build tree diagram does 36 REXX and MVS Build Scripts not include a + to indicate an expansion is possible. Simi- larly, where plidb2.dbr is an output of plidb2.obj, the TeamConnection build tree diagram does not include the +. To see one sibling (plidb2.dbr) as output of the other in the build tree diagram, you must first expand its sibling output (plidb2.obj). Thus there is no need to expand the output part (plidb2.dbr) to see the relationship between the two parts. Doing an expansion of plidb2.dbr would take you in a circle. o When a sibling output of one part is shown as an input to another part, there is support for a part expansion in the TeamConnection build tree diagram. For example, when plidb2.dbr is an input to plidb2.lkd, the TeamConnection build tree diagram includes the + to indicate plidb2.dbr can be expanded. To see the input part (plidb2.dbr) in the build tree diagram, you must first expand the part that is built (plidb2.lkd). You might want to see the expanded build tree for the input part (plidb2.dbr) because its sibling output might not be part of the same build tree. In Figure 16 on page 29, both sibling outputs (plidb2.obj and plidb2.dbr) are inputs to the final part (plidb2.lkd). In this case, either sibling or both can be expanded. To simplify the diagrams shown in Figure 12 on page 27 through Figure 24 on page 34, only the .obj part is expanded. SAMPLE PARTS AND BUILD TREES FOR THE BASIC TECHNIQUE 37 38 REXX and MVS Build Scripts PUTTING IT ALL TOGETHER The following sections show the TeamConnection processing to do builds with the REXX command file. CREATE A NEW FAMILY This section shows how to create a new family, update the hosts and services files, and start the family. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Make sure the following are running: | | | | | | o TCP/IP | | | o ObjectStore | | | | | | Make a directory called e:\family. | | +--------------------------------------+------------------------+ | Open the TeamConnection group | The "TeamConnection | | folder. | Group - Icon View" | | | window appears. | +--------------------------------------+------------------------+ | Double-click on the TeamConnection | The "TeamConnection | | Family Administrator icon. | Family Administrator" | | | window appears. | +--------------------------------------+------------------------+ | Select FAMILY, then NEW, and then | An "Untitled-Settings" | | DEFAULT. | notebook appears, with | | | the "Family Informa- | | | tion" page displayed. | +--------------------------------------+------------------------+ | Enter the following: | | | | | | o Family Information: | | | | | | FAMILY NAME plirexx | | | PATH e:\family | | | PORT 9807 or some | | | other unused port | | | MAILER mailexit or | | | null.cmd | | +--------------------------------------+------------------------+ | Select the "Initial Superuser" tab. | The "Initial Super- | | | user" page appears. | +--------------------------------------+------------------------+ (C) Copyright IBM Corp. 1997 39 +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Enter the following: | | | | | | o Initial Superuser: | | | | | | LOGIN SuprUser | | | NAME Super User | | | HOST SuprHost | | | USER ID | | | PASSWORD | | +--------------------------------------+------------------------+ | Below the notebook, press the CREATE | The "Create Family" | | push button. | window appears and | | | runs the commands to | | | create the family and | | | the super user. This | | | takes about 5 minutes. | | | The return code at the | | | end should be 0. | +--------------------------------------+------------------------+ | Press the OK push button. | The "TeamConnection | | | Family Administrator" | | | window appears with an | | | icon for plirexx in | | | the window. | +--------------------------------------+------------------------+ | From an OS/2 window, enter: | The current value of | | | the ETC environment | | echo %ETC% | variable appears. | | | This value is the name | | | of the directory to | | | use in the next few | | | steps. The | | | instructions below | | | assume that the direc- | | | tory is C:\MPTN\ETC. | +--------------------------------------+------------------------+ | Change the directory and drive to | | | C:\MPTN\ETC. | | +--------------------------------------+------------------------+ 40 REXX and MVS Build Scripts +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Add plirexx, mvssock, and tsosock to | The sockets are used | | C:\MPTN\ETC\hosts. Also make sure | as follows: | | that there is a carriage return | | | after each line. The hosts listed | PLIREXX Family | | in Table 1 on page 41 should be in | Server | | the hosts file. | | | | MVSSOCK MVS Build | | | processor | | | using RUNPGM | | | | | | TSOSOCK MVS Build | | | processor | | | using | | | RUNPGMT | +--------------------------------------+------------------------+ | Add plirexx, mvssock, and tsosock to | | | C:\MPTN\ETC\services. The services | | | listed in Table 2 on page 42 should | | | be in the services file. | | +--------------------------------------+------------------------+ | From the "TeamConnection Family | The "plirexx - Family | | Administrator" window, double-click | Servers" window | | on the plirexx icon. | appears. | +--------------------------------------+------------------------+ | Press the START push button in the | The family server is | | "Family Server" section of the | started. When the | | window. | message to "Press | | | CTRL-C to stop" | | | appears, minimize the | | | "plirexx - Family | | | Servers" window and | | | the "TeamConnection | | | Family Administrator" | | | window. | +--------------------------------------+------------------------+ +---------------------------------------------------------------+ | Table 1. Hosts File | +---------------+-------------------------------+---------------+ | IP ADDRESS | HOST NAME | FAMILY / | | | | SOCKET | +---------------+-------------------------------+---------------+ | 9.37.195.42 | FamHost.raleigh.ibm.com | plirexx | +---------------+-------------------------------+---------------+ | 9.67.43.25 | carmvs1.raleigh.ibm.com | mvssock | +---------------+-------------------------------+---------------+ | 9.67.43.25 | carmvs1.raleigh.ibm.com | tsosock | +---------------+-------------------------------+---------------+ PUTTING IT ALL TOGETHER 41 +---------------------------------------------------------------+ | Table 2. Services File | +---------------+---------------+-------------------------------+ | FAMILY / | PORT NUMBER | COMMENT | | SOCKET | | | +---------------+---------------+-------------------------------+ | plirexx | 9807/tcp | #port address for plirexx | +---------------+---------------+-------------------------------+ | mvssock | 32901/tcp | #port address for MVS build | | | | processor using RUNPGM | +---------------+---------------+-------------------------------+ | tsosock | 32911/tcp | #port address for MVS build | | | | processor using RUNPGMT | +---------------+---------------+-------------------------------+ 42 REXX and MVS Build Scripts START THE TEAMCONNECTION CLIENT This section shows how to start the TeamConnection client and change the SETTINGS. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | On the TeamConnection server | | | machine, create a working directory | | | called E:\WORK\plirexx | | +--------------------------------------+------------------------+ | Open the TeamConnection Group | | | folder. | | +--------------------------------------+------------------------+ | Select the TeamConnection client | A list of options | | icon with mouse button 2. | appears. | +--------------------------------------+------------------------+ | Select SETTINGS. | The "TeamConnection | | | Client - Settings" | | | notebook appears. | +--------------------------------------+------------------------+ | On the "Program" page, change the | | | working directory to E:\WORK\plirexx | | +--------------------------------------+------------------------+ | Close the "TeamConnection Client - | | | Settings" notebook. | | +--------------------------------------+------------------------+ | Double-click on the TeamConnection | The "TeamConnection - | | client icon. | Tasks" window appears. | +--------------------------------------+------------------------+ | Select WINDOWS and then SETTINGS. | The "Settings" note- | | | book appears, with the | | | "Environment" page | | | showing. | +--------------------------------------+------------------------+ | Enter the following on the "Environ- | | | ment" page: | | | | | | FAMILY plirexx | | | RELEASE release1 | | | BECOME USER SuprUser | | | USER ID SuprUser | | | RELATIVE DIRECTORY e:\mytemp | | | | | | Then press the APPLY push button. | | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 43 +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Press the TEST CONNECTION TO SERVER | The "Settings" infor- | | push button. | mation window should | | | appear and indicate | | | that you connected to | | | the server. There | | | should be no error | | | messages. | +--------------------------------------+------------------------+ | Press OK to close the information | | | window | | +--------------------------------------+------------------------+ | Select the POOL tab in the "Set- | All build activity in | | tings" notebook. | the basic demon- | | | stration uses "pool1". | | Enter POOL1 for the POOL value. | This value is the | | | default and is auto- | | Press the APPLY push button. | matically entered into | | | the "Pool" field of | | | the build windows. | +--------------------------------------+------------------------+ | Select the GUI tab in the "Settings" | Deselecting Verbose | | notebook. | commands reduces the | | | number of messages you | | Make sure that the checkbox for | receive. | | VERBOSE COMMANDS is deselected. | | | | | | Press the APPLY push button. | | +--------------------------------------+------------------------+ | Double-click on the upper left | The "TeamConnection - | | corner of the "Settings" window. | Tasks" window appears. | | | The user ID and | | | plirexx should be in | | | the lower left corner | | | of the tasks window. | +--------------------------------------+------------------------+ CREATE COMPONENTS This section creates the component structure for the demon- stration. The demonstration uses the overall controlling compo- nent projname. The other components can be used for modifications of the demonstration to show activities related to components. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then COMPONENTS, and | The "Create Compo- | | then CREATE. | nents" window appears. | +--------------------------------------+------------------------+ 44 REXX and MVS Build Scripts +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Enter the components shown in | | | Table 3 on page 45, pressing the | | | APPLY push button after each entry. | | +--------------------------------------+------------------------+ | Press the CANCEL push button. | The "TeamConnection - | | | Tasks" window appears. | +--------------------------------------+------------------------+ | Select OBJECTS, then COMPONENTS, and | The "Components | | then COMPONENTS. | Filter" window | | | appears. | +--------------------------------------+------------------------+ | In the "History" section, select | The "TeamConnection - | | SHOW ALL COMPONENTS. | Components" window | | | appears. | | Press the OK push button. | | +--------------------------------------+------------------------+ | Close the "TeamConnection - Compo- | The "TeamConnection - | | nents" window. | Tasks" window appears. | +--------------------------------------+------------------------+ +---------------------------------------------------------------+ | Table 3. Components | +---------+----------+----------+----------+--------------------+ | COMPO- | PARENT | PROCESS | OWNER | DESCRIPTION | | NENT | | | | | +---------+----------+----------+----------+--------------------+ | projname| root | proto- | SuprUser | overall control- | | | | type | | ling component | +---------+----------+----------+----------+--------------------+ | subsys1 | projname | proto- | SuprUser | subsystem 1 | | | | type | | | +---------+----------+----------+----------+--------------------+ | subsys2 | projname | proto- | SuprUser | subsystem 2 | | | | type | | | +---------+----------+----------+----------+--------------------+ PUTTING IT ALL TOGETHER 45 CREATE A RELEASE This section shows how to create a release. Parts, work areas, and builders cannot be created without first specifying a release. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then RELEASES, and | The "Create Releases" | | then CREATE. | window appears. | +--------------------------------------+------------------------+ | Enter the following information: | The "TeamConnection - | | | Tasks" window appears. | | RELEASES release1 | The release has been | | COMPONENT projname | created. | | PROCESS no_track | | | OWNER SuprUser | | | DESCRIPTION projname release 1 | | | | | | Also select AUTOMATIC VERSION | | | PRUNING. | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ CREATE BUILDERS This section creates the builders that are used throughout the demonstration. All builders should be created at this time so that you do not need to return to this activity later. The builders for link edit and bind (mvsplilnk, mvsdb2plilnk, mvscicsplilnk, and mvsdb2cicsplilnk) are described in Appendix A, "BUILDER, BUILD SCRIPT, AND REXX FOR LINK EDIT AND BIND" on page 79. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then BUILDERS, and | The "Create Builders" | | then CREATE on client workstation. | window appears. | +--------------------------------------+------------------------+ | Enter the builder information shown | A NULL builder could | | in Figure 27 on page 48, pressing | be used for a col- | | the APPLY push button after each | lector part in the | | entry. | demonstration. | +--------------------------------------+------------------------+ | Press the CANCEL push button to | The "TeamConnection - | | return to the Tasks list. | Tasks" window appears. | +--------------------------------------+------------------------+ | Select OBJECTS and then BUILDERS. | The "Builder Filter" | | | window appears. | +--------------------------------------+------------------------+ 46 REXX and MVS Build Scripts +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | In the "History" section, select | The "TeamConnection - | | SHOW ALL BUILDERS. | Builders" window | | | appears. | | Press the OK push button. | | +--------------------------------------+------------------------+ | Close the "TeamConnection - | The "TeamConnection - | | Builders" window. | Tasks" window appears. | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 47 +---------------------------------------------------------------+ | | | Builder mvspli | | Release release1 | | Script mvspli.jcl | | Environment mvstso | | Comp. oper. <= | | RC value 4 | | File type text | | Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl | | Parameters 'MVSRXPLI N N Y' | | Timeout 10 | | | | Builder mvsdb2pli | | Release release1 | | Script mvspli.jcl | | Environment mvstso | | Comp. oper. <= | | RC value 4 | | File type text | | Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl | | Parameters 'MVSRXPLI Y N Y' | | Timeout 10 | | | | Builder mvscicspli | | Release release1 | | Script mvspli.jcl | | Environment mvstso | | Comp. oper. <= | | RC value 4 | | File type text | | Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl | | Parameters 'MVSRXPLI N Y Y' | | Timeout 10 | | | | Builder mvsdb2cicspli | | Release release1 | | Script mvspli.jcl | | Environment mvstso | | Comp. oper. <= | | RC value 4 | | File type text | | Source file e:\tcdemo2\plirexx\scripts\mvspli.jcl | | Parameters 'MVSRXPLI Y Y Y' | | Timeout 10 | | | | | +---------------------------------------------------------------+ Figure 27 (Part 1 of 3). Builder Information 48 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | | | Builder mvsplilnk | | Release release1 | | Script mvslnk.jcl | | Environment mvstso | | Comp. oper. == | | RC value 0 | | File type none | | Source file | | Parameters 'MVSRPLNK N N N NA NA &TCWKAREA' | | Timeout 4 | | | | Builder mvsdb2plilnk | | Release release1 | | Script mvslnk.jcl | | Environment mvstso | | Comp. oper. == | | RC value 0 | | File type none | | Source file | | Parameters 'MVSRPLNK Y N N DSNA TOOLCICS &TCWKAREA' | | Timeout 4 | | | | Builder mvscicsplilnk | | Release release1 | | Script mvslnk.jcl | | Environment mvstso | | Comp. oper. == | | RC value 0 | | File type none | | Source file | | Parameters 'MVSRPLNK N N Y NA NA &TCWKAREA' | | Timeout 4 | | | | Builder mvsdb2cicsplilnk | | Release release1 | | Script mvslnk.jcl | | Environment mvstso | | Comp. oper. == | | RC value 0 | | File type none | | Source file | | Parameters 'MVSRPLNK Y N Y DSNA TOOLCICS &TCWKAREA' | | Timeout 4 | | | | | +---------------------------------------------------------------+ Figure 27 (Part 2 of 3). Builder Information PUTTING IT ALL TOGETHER 49 +---------------------------------------------------------------+ | | | | | Builder mvsnull | | Release release1 | | Script NULL | | Environment mvstso | | Comp. oper. == | | RC value 0 | | File type none | | Source file | | Parameters | | Timeout 1 | | | | | +---------------------------------------------------------------+ Figure 27 (Part 3 of 3). Builder Information CREATE A PARSER This section creates parsers to determine if a part has a depend- ency. The term "create a parser" involves telling TeamConnection which command to run for parsing a part. Programs that actually get control to do the parsing must be written just like any other tool. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then PARSERS, and | The "Create Parser" | | then CREATE. | window appears. | +--------------------------------------+------------------------+ | Set the following fields: | The "TeamConnection - | | | Tasks" window appears. | | PARSER pliprs | The parser has been | | RELEASE release1 | created. | | COMMAND fhbplprs.cmd | | | | | | Press the OK push button. | | | | | | NOTE: fhbplprs.cmd is a sample PL/I | | | parser supplied with TeamConnection. | | +--------------------------------------+------------------------+ 50 REXX and MVS Build Scripts OPEN A FEATURE AND CREATE A WORK AREA This section opens a feature and creates a work area for the initial load of the database. This is a typical activity for migrating existing parts (source code, tables) into TeamConnection. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then FEATURES, and | The "Open Feature" | | then OPEN. | window appears. | +--------------------------------------+------------------------+ | Enter the following information: | The "Open Feature" | | | information window | | COMPONENT projname | appears with a message | | REMARKS initial load of the | that the new feature | | family | was opened success- | | NAME initialize | fully. | | PREFIX f | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Press the OK push button again to | | | return to the "TeamConnection - | | | Tasks" window. | | +--------------------------------------+------------------------+ | Select ACTIONS, then FEATURES, and | The "Accept Feature" | | then ACCEPT. | window appears. | +--------------------------------------+------------------------+ | Enter the following information: | The "TeamConnection - | | | Tasks" window appears. | | FEATURES initialize | The feature has been | | REMARKS accepting initial | accepted. | | load of the family | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Select ACTIONS, then WORK AREAS, and | The "Create Work | | then CREATE. | Areas" window appears. | +--------------------------------------+------------------------+ | Enter the following information: | The "TeamConnection - | | | Tasks" window appears. | | WORK AREAS initwa | The work area has been | | RELEASES release1 | created. | | OWNER SuprUser | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 51 CREATE PARTS This section creates the parts for the initial load of the data- base as well as the output parts that will be created from builds. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select ACTIONS, then PARTS, and then | The "Create Parts" | | CREATE. | window appears. | +--------------------------------------+------------------------+ | Set the following fields for each | The extension of | | part: | include parts can be | | | "inc" in lower case or | | PART NAMES see Table 4 on | upper case. The case | | page 53 | of the part name | | RELEASE release1 | without the extension | | WORK AREA initwa | must match the case of | | COMPONENT projname | the copybook in the | | FILE TYPE see Table 4 on | source program. | | page 53 | | | SOURCE see Table 4 on | To set the FILE TYPE | | page 53 | to NONE for the .lkd | | SOURCE FILE see Table 4 on | parts, you might need | | page 53 | to set SOURCE to SAME | | BUILDER see Table 4 on | first. | | page 53 | | | PARSER see Table 4 on | | | page 53 | | | | | | Enter the parts shown in Table 4 on | | | page 53, pressing the APPLY push | | | button after each entry. | | +--------------------------------------+------------------------+ | Press the CANCEL push button to | The "TeamConnection - | | return to the Tasks list. | Tasks" window appears. | +--------------------------------------+------------------------+ 52 REXX and MVS Build Scripts +---------------------------------------------------------------+ | Table 4 (Page 1 of 2). projname Create Part Information | +------------+-----+------+------------------+------------+-----+ | PART NAME | FILE| SOURC| SOURCE FILE | BUILDER | PARS|R | | TYPE| | | | | +------------+-----+------+------------------+------------+-----+ | mvsrxpli.rx| Text| Copy | e:\tcdemo2\plirex| | | | | | from | \parts\mvsrxpli.r|p | | +------------+-----+------+------------------+------------+-----+ | PLIPGM.inc | Text| Copy | e:\tcdemo2\plirex| | plip|s | | | from | \parts\plipgm.inc| | | +------------+-----+------+------------------+------------+-----+ | PL/I ONLY | | | | | | +------------+-----+------+------------------+------------+-----+ | plipgm.pli | Text| Copy | e:\tcdemo2\plirex| | plip|s | | | from | \parts\plipgm.pli| | | +------------+-----+------+------------------+------------+-----+ | plipgm.obj | Bina|yNo | | mvspli | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plipgm.lnk | Text| Copy | e:\tcdemo2\plirex| | | | | | from | \parts\plipgm.lnk| | | +------------+-----+------+------------------+------------+-----+ | plipgm.lkd | None| | | mvsplilnk | | +------------+-----+------+------------------+------------+-----+ | PL/I WITH | | | | | | | DB2 | | | | | | +------------+-----+------+------------------+------------+-----+ | plidb2.pli | Text| Copy | e:\tcdemo2\plirex| | plip|s | | | from | \parts\plidb2.pli| | | +------------+-----+------+------------------+------------+-----+ | plidb2.obj | Bina|yNo | | mvsdb2pli | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidb2.dbr | Bina|yNo | | | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidb2.lnk | Text| Copy | e:\tcdemo2\plirex| | | | | | from | \parts\plidb2.lnk| | | +------------+-----+------+------------------+------------+-----+ | plidb2.msg | Text| No | | | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidb2.lkd | None| | | mvsdb2pliln| | +------------+-----+------+------------------+------------+-----+ | PL/I WITH | | | | | | | CICS | | | | | | +------------+-----+------+------------------+------------+-----+ | plicics.pli| Text| Copy | e:\tcdemo2\plirex| | plip|s | | | from | \parts\plicics.pl| | | +------------+-----+------+------------------+------------+-----+ | plicics.obj| Bina|yNo | | mvscicspli | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ PUTTING IT ALL TOGETHER 53 +------------+-----+------+------------------+------------+-----+ | plicics.lnk| Text| Copy | e:\tcdemo2\plirex| | | | | | from | \parts\plicics.ln| | | +------------+-----+------+------------------+------------+-----+ | plicics.lkd| None| | | mvscicsplil|k | +------------+-----+------+------------------+------------+-----+ | PL/I WITH | | | | | | | DB2 AND | | | | | | | CICS | | | | | | +------------+-----+------+------------------+------------+-----+ | plidcic.pli| Text| Copy | e:\tcdemo2\plirex| | plip|s | | | from | \parts\plidcic.pl| | | +------------+-----+------+------------------+------------+-----+ | plidcic.obj| Bina|yNo | | mvsdb2cicsp|i | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidcic.dbr| Bina|yNo | | | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidcic.lnk| Text| Copy | e:\tcdemo2\plirex| | | | | | from | \parts\plidcic.ln| | | +------------+-----+------+------------------+------------+-----+ | plidcic.msg| Text| No | | | | | | | sourc| | | | +------------+-----+------+------------------+------------+-----+ | plidcic.lkd| None| | | mvsdb2cicsp|ilnk | +------------+-----+------+------------------+------------+-----+ 54 REXX and MVS Build Scripts CREATE BUILD TREE This section shows how to create a build tree. A build tree shows the configuration of the application. TeamConnection uses the build tree to determine what parts need to be built. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select OBJECTS, then PARTS, and then | The "Part Filter" | | PARTS. | window appears. | +--------------------------------------+------------------------+ | Set the following fields: | The "TeamConnection - | | | Parts" window appears. | | RELEASE release1 | | | WORK AREA initwa | | | | | | In the "History" section, select | | | SHOW ALL PARTS | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | For each icon in Table 5 on page 57: | The fields "Path | | | names", "Type", | | o select the ICON in the | "Release", and "Work | | "TeamConnection - Parts" window | area" should already | | | have the correct | | o click on the second mouse button | values. | | | | | o select CONNECT from the pop up | | | | | | o Set the following fields and | | | radio buttons in the "Connect | | | Parts" window: | | | | | | PARENT see Table 5 | | | on page 57 | | | RELATION TO PARENT see Table 5 | | | on page 57 | | | | | | o Press the OK push button. | | +--------------------------------------+------------------------+ | Close the "TeamConnection - Parts" | The "TeamConnection - | | window. | Tasks" window appears. | +--------------------------------------+------------------------+ | Select OBJECTS, then PARTS, and then | The "BuildView Filter" | | BUILDVIEW. | window appears. | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 55 +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Set the following fields: | The "TeamConnection - | | | BuildView" window | | RELEASE release1 | appears. | | WORK AREA initwa | | | BASE NAMES like %.obj and sort | | | 1st Asc | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Expand the PLIPGM.OBJ icon to show | Examine the tree for | | the entire tree. | proper structure (see | | | Figure 12 on page 27). | +--------------------------------------+------------------------+ | Also expand the following .obj parts | | | and compare them to the expected | | | build tree diagrams. | | | | | | PLIDB2 Figure 16 on page 29 | | | | | | PLICICS Figure 20 on page 32 | | | | | | PLIDCIC Figure 24 on page 34 | | +--------------------------------------+------------------------+ 56 REXX and MVS Build Scripts +---------------------------------------------------------------+ | Table 5 (Page 1 of 2). release1 Build Tree Information | +-------------------------+-------------------------+-----------+ | ICON | PARENT | RELATION | +-------------------------+-------------------------+-----------+ | PL/I ONLY | | | +-------------------------+-------------------------+-----------+ | plipgm.pli | plipgm.obj | input | +-------------------------+-------------------------+-----------+ | mvsrxpli.rxp | plipgm.obj | input | +-------------------------+-------------------------+-----------+ | plipgm.obj | plipgm.lkd | input | +-------------------------+-------------------------+-----------+ | plipgm.lnk | plipgm.lkd | input | +-------------------------+-------------------------+-----------+ | PL/I WITH DB2 | | | +-------------------------+-------------------------+-----------+ | plidb2.pli | plidb2.obj | input | +-------------------------+-------------------------+-----------+ | mvsrxpli.rxp | plidb2.obj | input | +-------------------------+-------------------------+-----------+ | plidb2.dbr | plidb2.obj | output | +-------------------------+-------------------------+-----------+ | plidb2.dbr | plidb2.lkd | input | +-------------------------+-------------------------+-----------+ | plidb2.obj | plidb2.lkd | input | +-------------------------+-------------------------+-----------+ | plidb2.lnk | plidb2.lkd | input | +-------------------------+-------------------------+-----------+ | plidb2.msg | plidb2.lkd | output | +-------------------------+-------------------------+-----------+ | PL/I WITH CICS | | | +-------------------------+-------------------------+-----------+ | plicics.pli | plicics.obj | input | +-------------------------+-------------------------+-----------+ | mvsrxpli.rxp | plicics.obj | input | +-------------------------+-------------------------+-----------+ | plicics.obj | plicics.lkd | input | +-------------------------+-------------------------+-----------+ | plicics.lnk | plicics.lkd | input | +-------------------------+-------------------------+-----------+ | PL/I WITH DB2 AND CICS | | | +-------------------------+-------------------------+-----------+ | plidcic.pli | plidcic.obj | input | +-------------------------+-------------------------+-----------+ | mvsrxpli.rxp | plidcic.obj | input | +-------------------------+-------------------------+-----------+ | plidcic.dbr | plidcic.obj | output | +-------------------------+-------------------------+-----------+ | plidcic.dbr | plidcic.lkd | input | +-------------------------+-------------------------+-----------+ | plidcic.obj | plidcic.lkd | input | +-------------------------+-------------------------+-----------+ PUTTING IT ALL TOGETHER 57 +-------------------------+-------------------------+-----------+ | plidcic.lnk | plidcic.lkd | input | +-------------------------+-------------------------+-----------+ | plidcic.msg | plidcic.lkd | output | +-------------------------+-------------------------+-----------+ 58 REXX and MVS Build Scripts START THE MVS BUILD AGENT AND BUILD PROCESSOR This section shows how to start an MVS build agent and build processor. Together this pair is called a build server. Build events wait in the job queue for a build agent to start. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Go to an OS/2 window (recommended on | | | the machine that is running the | | | TeamConnection family server). | | +--------------------------------------+------------------------+ | Make sure the TC_DBPATH environment | | | variable is set to the proper value | | | (e:\family\plirexx for example). | | +--------------------------------------+------------------------+ | Issue the command | The build agent starts | | | in the OS/2 window. | | TEAMAGNT -F PLIREXX -E MVSTSO -P |OOL1 | | -S TSOSOCK -K IBM-850 | | +--------------------------------------+------------------------+ | Minimize the OS/2 window - DO NOT | | | CLOSE. | | +--------------------------------------+------------------------+ | Go to an MVS window or terminal and | | | logon. | | +--------------------------------------+------------------------+ | Submit the job that runs the | The job should be | | TeamConnection RUNPGMT program (it | active on the MVS job | | might be in the data set | queue and waiting for | | logonid.TEAMC.JCLLOAD(RUNPGMT)). | a file from the MVS | | | build agent. | | See Figure 4 on page 8 for an | | | example of the JCL. | | +--------------------------------------+------------------------+ | Logoff or monitor the job for | | | errors. | | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 59 BUILD THE OBJECT MODULES This section builds the MVS applications. BUILD puts build events on the job queue and the build agent removes them. The build agent sends the build script (from the builder) and the inputs to the build processor. The build processor runs the build script. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | From the "TeamConnection - | | | BuildView" window, select | | | PLIPGM.OBJ. | | +--------------------------------------+------------------------+ | Select SELECTED, and then BUILD. | The "Build Parts" | | | window appears. | +--------------------------------------+------------------------+ | Set the following fields and radio | The "Build Progress" | | buttons: | window appears. | | | | | PATH NAME plipgm.obj | | | TYPE TCPart | | | RELEASE release1 | | | WORK AREA initwa | | | POOL pool1 | | | BUILD MODE Normal | | | PARAMETERS | | | DETAIL FILE | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Monitor the "Build Progress" window. | The "TeamConnection - | | Press the OK push button when the | BuildView" window | | build is complete. | appears. | +--------------------------------------+------------------------+ | Press F5 to refresh the | The "TeamConnection - | | "TeamConnection - BuildView" window. | BuildView" window | | | reappears. If the | | | build was successful, | | | plipgm.obj should have | | | a green checkmark. | +--------------------------------------+------------------------+ | Select PLIPGM.OBJ | | +--------------------------------------+------------------------+ | Select SELECTED, then VIEW, and then | The "View Build | | VIEW BUILD MESSAGE. | Message" window | | | appears. | +--------------------------------------+------------------------+ 60 REXX and MVS Build Scripts +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Press the OK push button. | The messages from the | | | most recent build of | | | plipgm.obj appear. | | | | | | Review the messages | | | for any problems. | +--------------------------------------+------------------------+ | Optional - the MVS job can be can- | | | celled with a print to examine the | | | output, but would need to be sub- | | | mitted again for additional builds. | | +--------------------------------------+------------------------+ | Repeat the above steps to build the | | | following parts: | | | | | | o plidb2.obj | | | o plicics.obj | | | o plidcic.obj | | +--------------------------------------+------------------------+ | Close the "TeamConnection - | The "TeamConnection - | | BuildView" window. | Tasks" window appears. | +--------------------------------------+------------------------+ BUILD THE LOAD MODULES Before you build the load modules, be sure that o mvslnk.jcl (the build script for link edit and bind, shown in Figure 28 on page 80) and o mvsrplnk.rxp (the REXX command file for link edit and bind, shown in Figure 29 on page 84) are on the MVS host. Also be sure that: o The TEAMPROC DD statement in RUNPGMT points to the parti- tioned data set where you stored mvslnk.jcl o The SYSEXEC DD statement in mvslnk.jcl points to the parti- tioned data set where you stored mvsrplnk.rxp. +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Select OBJECTS, then PARTS, and then | The "BuildView Filter" | | BUILDVIEW. | window appears. | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 61 +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Set the following fields: | The "TeamConnection - | | | BuildView" window | | RELEASE release1 | appears. | | WORK AREA initwa | | | BASE NAMES like %.lkd and sort | | | 1st Asc | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Expand the PLIPGM.LKD icon to show | Examine the tree for | | the entire tree. | proper structure (see | | | Figure 12 on page 27). | +--------------------------------------+------------------------+ | Also expand the following parts and | | | compare them to the expected build | | | tree diagrams. | | | | | | PLIDB2 Figure 16 on page 29 | | | | | | PLICICS Figure 20 on page 32 | | | | | | PLIDCIC Figure 24 on page 34 | | +--------------------------------------+------------------------+ | From the "TeamConnection - | | | BuildView" window, select | | | PLIPGM.LKD. | | +--------------------------------------+------------------------+ | Select SELECTED, and then BUILD. | The "Build Parts" | | | window appears. | +--------------------------------------+------------------------+ | Set the following fields and radio | The "Build Progress" | | buttons: | window appears. | | | | | PATH NAME plipgm.lkd | | | TYPE TCPart | | | RELEASE release1 | | | WORK AREA initwa | | | POOL pool1 | | | BUILD MODE Normal | | | PARAMETERS | | | DETAIL FILE | | | | | | Press the OK push button. | | +--------------------------------------+------------------------+ | Monitor the "Build Progress" window. | The "TeamConnection - | | Press the OK push button when the | BuildView" window | | build is complete. | appears. | +--------------------------------------+------------------------+ 62 REXX and MVS Build Scripts +--------------------------------------+------------------------+ | ACTION | DESCRIPTION | +--------------------------------------+------------------------+ | Press F5 to refresh the | The "TeamConnection - | | "TeamConnection - BuildView" window. | BuildView" window | | | reappears. If the | | | build was successful, | | | plipgm.lkd should have | | | a green checkmark. | +--------------------------------------+------------------------+ | Select PLIPGM.LKD | | +--------------------------------------+------------------------+ | Select SELECTED, then VIEW, and then | The "View Build | | VIEW BUILD MESSAGE. | Message" window | | | appears. | +--------------------------------------+------------------------+ | Press the OK push button. | The messages from the | | | most recent build of | | | plipgm.lkd appear. | | | | | | Review the messages | | | for any problems. | +--------------------------------------+------------------------+ | Optional - the MVS job can be can- | | | celled with a print to examine the | | | output, but would need to be sub- | | | mitted again for additional builds. | | +--------------------------------------+------------------------+ | Repeat the above steps to build the | | | following parts: | | | | | | o plidb2.lkd | | | o plicics.lkd | | | o plidcic.lkd | | +--------------------------------------+------------------------+ | Close the "TeamConnection - | The "TeamConnection - | | BuildView" window. | Tasks" window appears. | +--------------------------------------+------------------------+ PUTTING IT ALL TOGETHER 63 64 REXX and MVS Build Scripts VARIATIONS IN MVSPLI.JCL AND MVSRXPLI.RXP The following sections describe variations in the basic technique that is described above. o "Keeping mvspli.jcl at the MVS Host" o "Keeping mvsrxpli.rxp at the MVS Host" on page 66 o "Supporting Program Product Include Libraries" on page 67. o "Supporting Program Product Include Libraries Concatenated with TeamConnection Copybooks" on page 67. o "Setting PL/I Compiler Options - Hardcoding" on page 69. o "Setting PL/I Compiler Options - From Builder Definition" on page 69. o "Setting PL/I Compiler Options - Based on Work Area Name" on page 70. o "Reducing the Number of Build Messages" on page 73. Although "Setting PL/I Compiler Options - Hardcoding" on page 69, "Setting PL/I Compiler Options - From Builder Definition" on page 69, and "Setting PL/I Compiler Options - Based on Work Area Name" on page 70, describe handling parameters for the PL/I com- piler, the same techniques can also be applied to the DB2 precom- piler and CICS translator options. References to comments in the following sections refer to the comment numbers in Figure 6 on page 10 and Figure 8 on page 12. KEEPING MVSPLI.JCL AT THE MVS HOST You might want to keep mvspli.jcl (Figure 6 on page 10) on the MVS Host system, rather than maintaining it in TeamConnection. If several builders all share the same build script (mvspli.jcl), the advantage of maintaining the build script on the MVS host is that you do not need to update each builder to pick up the revised build script. The disadvantage is that when mvspli.jcl is changed, TeamConnection is not aware of the change and does not automatically rebuild all programs whose builder has been changed due to the change in the build script. This could be an advantage if you frequently change mvspli.jcl to add new func- tions that do not require existing modules to be rebuilt. To use an MVS host copy of mvspli.jcl, make the following changes: (C) Copyright IBM Corp. 1997 65 o Make sure that the current copy of mvspli.jcl is in the data set pointed to by the TEAMPROC DD statement in RUNPGMT. o Modify the properties for the 4 builders (mvspli, mvsdb2pli, mvscicspli, and mvsdb2cicspli) that use mvspli.jcl as the build script. When you modify the builders' properties, set the FILE TYPE to NONE. KEEPING MVSRXPLI.RXP AT THE MVS HOST You might want to keep mvsrxpli.rxp (Figure 8 on page 12) on the MVS Host system, rather than maintaining it in TeamConnection. The advantage of storing mvsrxpli.rxp on the MVS host is that it simplifies the build tree. The disadvantage is that when mvsrxpli.rxp is changed, TeamConnection is not aware of the change and does not automatically rebuild all programs that use mvsrxpli.rxp as part of the build. This could be an advantage if you frequently change mvsrxpli.rxp to add new functions that do not require existing modules to be rebuilt. To use an MVS host copy of mvsrxpli.rxp, make the following changes: o In mvspli.jcl, change the SYSEXEC DD statement to point to the data set where MVSRXPLI resides. For example, the new DD statement would be something like: //SYSEXEC DD DSN=JERI.TEAMC.REXXCMDS,DISP=SHR If you have not stored mvspli.jcl at the MVS host, then to put this change into effect, you must modify the properties for the 4 builders (mvspli, mvsdb2pli, mvscicspli, and mvsdb2cicspli) that use mvspli.jcl as the build script. When you modify the builders' properties, set the SOURCE FILE to point to the path and directory for the updated mvspli.jcl. o Upload mvsrxpli.rxp to the MVS host and store it as member MVSRXPLI in the data set referenced by SYSEXEC (JERI.TEAMC.REXXCMDS in this example). o Remove mvsrxpli.rxp from the build trees for all PL/I source programs. o If you use crtplibt.cmd as shown in Appendix B, "SAMPLE REXX TO CREATE BUILD TREES" on page 101, modify it so that it does not connect mvsrxpli.rxp to the .obj part. o Make any future changes to the copy of mvsrxpli.rxp that is stored at the MVS host. 66 REXX and MVS Build Scripts SUPPORTING PROGRAM PRODUCT INCLUDE LIBRARIES If all include members are provided by a program product and are maintained only on the MVS host, not within TeamConnection, make the following modifications: o In mvspli.jcl (Figure 6 on page 10), change the INCSRC DD statement to point to the program product library that con- tains the include members. For example, the new DD statement should be something like: //INCSRC DD DSN=program.product.include.library,DISP=SHR If you have not stored mvspli.jcl at the MVS host, then to put this change into effect, you must modify the properties for the 4 builders (mvspli, mvsdb2pli, mvscicspli, and mvsdb2cicspli) that use mvspli.jcl as the build script. When you modify the builders' properties, set the SOURCE FILE to point to the path and directory for the updated mvspli.jcl. o Do not specify a parser for the PL/I source programs. This is because you do not want TeamConnection to detect dependen- cies for any of the include members. You can remove the parser from a part by modifying the part's properties and setting the PARSER to NULL. SUPPORTING PROGRAM PRODUCT INCLUDE LIBRARIES CONCATENATED WITH TEAMCONNECTION COPYBOOKS If some include members are provided by a program product and are maintained only on the MVS host and other include members are developed locally and maintained within TeamConnection, make the following modifications: o In mvspli.jcl (Figure 6 on page 10), change the INCSRC state- ment to point to a permanent data set on the MVS host that contains a copy of the include members that are maintained within TeamConnection. For example, the new DD statement should be something like: //INCSRC DD TCEXT=INC,DSN=JERI.TEAMC.MYINC.&TCRELEAS.,DISP=OLD Using TCEXT=INC causes TeamConnection to place any include members identified as dependencies of the PL/I source program in the data set specified by the DSN parameter. If the include member already exists in the data set, the include member is replaced. Using &TCRELEAS as part of the data set name allows you to maintain separate include libraries on the host, based on the name of the release within TeamConnection. VARIATIONS IN mvspli.jcl AND mvsrxpli.rxp 67 If you have not stored mvspli.jcl at the MVS host, then to put this change into effect, you must modify the properties for the 4 builders (mvspli, mvsdb2pli, mvscicspli, and mvsdb2cicspli) that use mvspli.jcl as the build script. When you modify the builders' properties, set the SOURCE FILE to point to the path and directory for the updated mvspli.jcl. o In mvsrxpli.rxp (Figure 8 on page 12), make the following changes: - In the "INITIALIZATION" section near comment (1), add a statement to initialize a variable to the name of the program product library that contains the include members. For example, add: hostonlylib = 'program.product.include.library' where program.product.include.library is the actual name of the library on the MVS host, for example: CICS330.SDHFPL1 - In the precompile routine at comment (6), change the allocation for SYSLIB to: "ALLOC FI(SYSLIB) DA('"hostonlylib"','"cpysrc"') SHR REUSE" The ALLOC command requires all data sets in the concat- enation to be catalogued. Specifying a permanent (cata- logued) data set for the INCSRC DD statement in mvspli.jcl makes this possible. - In the compile routine at comment (17), change the allo- cation for SYSLIB to: "ALLOC FI(SYSLIB) DA('"hostonlylib"','"cpysrc"') SHR REUSE" o Specify a parser for the PL/I source program and any include members that are stored in TeamConnection. The PL/I parser (fhbplprs.cmd) provided with TeamConnection, identifies only the include members that are stored in TeamConnection as dependencies of the PL/I source program. Include members that are not stored in TeamConnection are ignored by the parser and are not added as dependencies of the PL/I source program. This provides support for a mixture of include members stored in TeamConnection and in an MVS program product library. NOTE: If you use this technique, when you VIEW BUILD MESSAGES, you might see an error message like the following: 6021-647 Data set incompatibility, particularly the lrecl, will prevent any copying from 'DD:TC$INC(PLIPGM)' TO 'DD:TC000017' This message typically appears when the program being built uses an existing include member that has not been changed. 68 REXX and MVS Build Scripts Verify that: o New include members are copied to the MVS host o Changes to include members are copied to the MVS host If the above are true, then as long as the object modules are built correctly, you can ignore this message. SETTING PL/I COMPILER OPTIONS - HARDCODING Figure 8 on page 12 shows one technique for setting compiler options -- hard coding them in mvsrxpli.rxp. For example, at comment (19), the choice of compiler options is made based on whether the PL/I source program uses CICS commands or not. pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,OPT(2),NOSOURCE' if cics = 'Y' then pliopts = pliopts || ',SYSTEM(CICS)' "CALL '"plicomp"(IEL0AA)' '"pliopts"'" The advantage of this technique is that it is easy to understand. The disadvantage is that all the PL/I source programs that use the builder must specify the same compiler options. This can be an advantage in enforcing your installation standards. SETTING PL/I COMPILER OPTIONS - FROM BUILDER DEFINITION Another technique for setting PL/I compiler options is to specify them in the PARAMETERS field when you define a builder. To specify compiler options on the builder, make the following changes: o In the definition of the builder(s), change the parameters to include PLIOPT(options). For example, for the mvspli builder, the parameters change From 'MVSRXPLI N N Y' To 'MVSRXPLI N N Y PLIOPT(INCLUDE,OPT(2),SOURCE)' o In mvsrxpli.rxp (Figure 8 on page 12), make the following changes: - Change the parse statement at comment (1) to: parse arg db2 cics plicmp pliopt otherparms VARIATIONS IN mvspli.jcl AND mvsrxpli.rxp 69 - After setting the required PL/I compiler options at comment (19), add logic to parse out the PL/I compiler options before calling the PL/I compiler. For example, change: From: pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,OPT(2),NOSOURCE' if cics = 'Y' then pliopts = pliopts || ',SYSTEM(CICS)' "CALL '"plicomp"(IEL0AA)' '"pliopts"'" To: pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,OPT(2),NOSOURCE' if cics = 'Y' then pliopts = pliopts || ',SYSTEM(CICS)' /* If PL/I options supplied to builder, let them replace defaults */ if substr(pliopt,1,7) = 'PLIOPT(' then do plioptl = length(pliopt) - 8 /* subtract pre/suffix */ if plioptl > 0 then pliopts = substr(pliopt,8,plioptl) end "CALL '"plicomp"(IEL0AA)' '"pliopts"'" The advantage of this technique is that it is clear from the builder definition which compiler options are being used. The disadvantage of this technique is that there is a fixed (about 100 bytes) amount of space allotted for the entire param- eter string for a builder. If the technique is extended to support both DB2 precompiler and CICS translator options, the parameter string for the builder might be too long. You could modify this technique to allow the builder to specify some options, while other options are hard-coded. SETTING PL/I COMPILER OPTIONS - BASED ON WORK AREA NAME You might need to vary the PL/I compiler options based on the work area and/or driver that is currently being built. For example, during unit and system test you might use the NOOPTIMIZE compiler option and during acceptance test you might use the OPTIMIZE(TIME) compiler option. 70 REXX and MVS Build Scripts To vary the compiler options based on the work area or driver that is being built and assuming that you did not make the changes described in "Setting PL/I Compiler Options - From Builder Definition" on page 69, make the following changes: o Change the parameters for the 4 builders (mvspli, mvsdb2pli, mvscicspli, and mvsdb2cicspli) that use mvspli.jcl as the build script. For example, for mvspli, change the parame- ters: From 'MVSRXPLI N N Y' To 'MVSRXPLI N N Y &TCWKAREA' This includes the work area or driver name as part of the parameter list. o In mvsrxpli.rxp (Figure 8 on page 12), do the following: - Change the parse statement at comment (1) to include the work area name. From parse arg db2 cics plicmp otherparms To parse arg db2 cics plicmp wkareanam otherparms - After setting the required PL/I compiler options at comment (19), add logic to modify the PL/I compiler options based on the work area name. For example, change: VARIATIONS IN mvspli.jcl AND mvsrxpli.rxp 71 From: pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,OPT(2),NOSOURCE' if cics = 'Y' then pliopts = pliopts || ',SYSTEM(CICS)' "CALL '"plicomp"(IEL0AA)' '"pliopts"'" To: pliopts = 'INCLUDE,MACRO,OBJECT,NODECK,MAP,NOSOURCE' if cics = 'Y' then pliopts = pliopts || ',SYSTEM(CICS)' /* Modify PL/I options based on work area name */ if wkareanam = 'INITWA' then pliopts = pliopts || ',NOOPTIMIZE' else pliopts = pliopts || ',OPTIMIZE(TIME)' "CALL '"plicomp"(IEL0AA)' '"pliopts"'" The work area name is translated to upper case when it is placed in the parameter list. This shows combining the use of the &TCWKAREA value in wkareanam with the cics parameter that was explicitly set in the builder to determine which PL/I compiler options should be used. &TCRELEAS can also be used in the builder parameter list. &TCRELEAS provides the name of the release for which the build is being done. The advantage of this technique is that it allows you to vary the compiler options based on the work area, driver, and/or release that is being built. The same technique can be used to set the names of the DB2 pre- compiler, CICS translator, or PL/I compiler libraries or anything else that might vary by work area, driver, and/or release. The disadvantage of this technique is that you must adhere to some naming convention for work areas and drivers so that mvsrxpli.rxp can distinguish between work areas and different drivers in order to set the PL/I compiler options. You must also establish naming conventions for releases if you need to vary options based on the release name. 72 REXX and MVS Build Scripts REDUCING THE NUMBER OF BUILD MESSAGES You might want to change the output messages that are passed back to TeamConnection. You can minimize the output messages by varying the DB2 precompiler, CICS translator, and PL/I compiler options. For example, specifying the NOSOURCE option for the CICS translator reduces the amount of information returned in the build messages. Alternatively, you might decide that you only want to see error messages. errorhndlr is used when an error occurs to copy the information for the failing step to the build messages (the ERRLIST DD statement in mvspli.jcl). To modify mvsrxpli.rxp so that the build messages are minimized and deal primarily with errors, replace the calls to TCOUThndlr with statements that free the output files. The following changes are needed: o In the precompile step at comment (10), change: From: call TCOUThndlr PRECOMPILE,precompile_rc,SYSTERM To: "FREE FI(SYSTERM)" o In the translate step at comment (15), change: From: call TCOUThndlr TRANSLATE,translate_rc,SYSPRINT To: "FREE FI(SYSPRINT)" o In the compile step at comment (21), change: From: call TCOUThndlr COMPILE,compile_rc,SYSPRINT To: "FREE FI(SYSPRINT)" VARIATIONS IN mvspli.jcl AND mvsrxpli.rxp 73 74 REXX and MVS Build Scripts HINTS AND TIPS FOR MVS BUILDS The following provide some debugging hints and tips for MVS build processors. NEED TO TRACE WHAT IS HAPPENING Do one or both of the following: o Add the -T parameter to the CALL state- ment in the RUNPGMT job. The -T provides a trace of the TeamConnection commands that are running. o Add TRACE INTERMEDIATES as the second line of mvsrxpli.rxp. This turns on tracing for the REXX command file. BUILD AGENT FAILS One cause for this is an error in the REXX command file, possibly due to: o Mismatched quotation marks. o Line length too long. Either of these can occur from a change you just made. Cancel the MVS build processor and examine the trace output to determine the cause of the problem. BUILD FAILS EVEN AFTER YOU HAVE "FIXED" THE BUILD SCRIPT. Check that you modified the properties for the build script and reentered the path and file name for the script. This is required to make TeamConnection pick up a fresh copy of the build script. YOU CANCELLED A BUILD, AND TRY TO START ANOTHER BUILD FOR THE SAME PART, BUT GET A MESSAGE THAT THERE IS ALREADY A BUILD FOR THE SAME PART ON THE JOB QUEUE. Change the TIMEOUT value for the builder to 1. Start the build agent for the pool for which the build was done. The build should (C) Copyright IBM Corp. 1997 75 now time out and remove the part from the job queue. Remember to change the TIMEOUT value back to the original value before starting the build again. YOU NEED 2 SETS OF IN-STREAM DATA, POSSIBLY ONE WITH JUST &TCINPUT AND ANOTHER WITH JUST &TCOUTPUT. Assuming that the 2 sets of in-stream data are at the end of the build script, use the following statements: //INLIST DD * &TCINPUT /* //OUTLIST DD * &TCOUTPUT // This results in both &TCINPUT and &TCOUTPUT being available. However, the following also occur and must be handled in the REXX command file: o /* appears as the last line of input for the INLIST DD statement. o A blank line appears as the first line of input for the OUTLIST DD statement due to the /* to end the INLIST DD statement. The following 2 techniques do NOT work: Technique 1 - fails because the first // ends the build script and the OUTLIST DD statement cannot be found by the REXX command file //INLIST DD * &TCINPUT // //OUTLIST DD * &TCOUTPUT // Technique 2 - fails because MSGLIST can not be found; processing is not transferred to the REXX command file //INLIST DD * &TCINPUT //MSGLIST DD TCEXT=MSG, .... //OUTLIST DD * &TCOUTPUT // 76 REXX and MVS Build Scripts NEED TO RUN 2 MVS BUILD PROCESSORS Be sure to: o Start 2 different build agents with dif- ferent socket numbers. o Use different job names for the MVS build processors, with each job specifying a different socket number that corresponds to the socket number specified by one of the build agents. o No data sets in the jobs have DISP=OLD o The job class being used supports suffi- cient initiators. Each build processor requires its own initiator. ABLE TO PING THE MVS MACHINE, BUT GET A TCP/IP ERROR TRYING TO RUN EITHER RUNPGM OR RUNPGMT. If the error message is similar to: RC=1011 on IUCV, IUCV CONNECT TO TCP/IP, FD=-254, PATH=0, IPR CODE=11, LUCV NAME=000de9a0 and in TeamConnection, you get something similar to: 0010-063 error edc8004i, request failed because of IUCV error when the TeamConnection server attempted to process the socket function check whether the TCP/IP naming conventions for your installation have been changed from the default values. If so, you might need a SYSTCPD DD statement to point to the data set that defines the different naming con- ventions. HINTS AND TIPS FOR MVS BUILDS 77 78 REXX and MVS Build Scripts APPENDIX A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK EDIT AND BIND This section describes how the builder definition, the build script, and the REXX command file work together to control the build for the load module. This build involves linking the object modules together as well as doing the binds for any DBRMs that correspond to the object modules. DEFINING THE BUILDER When IRXJCL is used in the build script, the parameters for the builder define which REXX command file is used during the build. For example, in the builder definition: Builder mvsplilnk Release release1 Script mvslnk.jcl Environment mvstso Comp. oper. == RC value 0 File type none Source file Parameters 'MVSRPLNK N N N NA NA &TCWKAREA' Timeout 4 the parameters are: MVSRPLNK Name of the REXX command file that is run by IRXJCL. IRXJCL always expects the first parameter to be the name of the REXX command file. N N N NA NA &TCWKAREA Correspond to the parameters expected by MVSRPLNK. This builder assumes that the build script, shown in Figure 28 on page 80, is stored on the MVS host. The TEAMPROC DD statement in RUNPGMT points to the partitioned data set in which mvslnk.jcl is stored. (C) Copyright IBM Corp. 1997 79 NOTES ON MVSLNK.JCL (THE BUILD SCRIPT) The following figure shows the build script that supports link edit and bind. +---------------------------------------------------------------+ | | | //REXX EXEC PGM=IRXJCL, | | // PARM=&TCPARM | | //* | | //* BUILD SCRIPT FOR EXECUTING A REXX PROGRAM | | //* | | //* TEAMPROC MUST RUN IN A TSO ADDRESS SPACE | | //* | | //* IRXJCL RUNS THE PROGRAM NAMED IN THE FIRST PARAMETER|OF &TCPARM | //* AS A REXX PROGRAM AND PASSES THE REMAINING PARAMETER| | //* | | //* IRXJCL LOOKS INTO SYSEXEC FOR THE REXX PROGRAM | | //* | | //SYSEXEC DD DSN=JERI.TEAMC.REXXCMDS,DISP=SHR | (1) | //DBRM DD TCEXT=DBR,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(32000,(30,10,5)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=6160) | | //OBJECT DD TCEXT=OBJ,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(32000,(30,10,5)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //LINKCTL DD TCEXT=LNK,DISP=(NEW,DELETE), | (2) | // UNIT=SYSDA,SPACE=(32000,(30,10)), | | // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) | | //SYSLMOD DD TCOUT=LKD,DSN=JERI.TEAMC.LOAD.&TCRELEAS.,D|SP=SHR (3) | //ERRLIST TCEXT=TCOUT,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(13300,(30,30)), | | // DCB=(RECFM=FB,LRECL=133,BLKSIZE=1330) | | //MSGLIST TCEXT=MSG,DISP=(NEW,DELETE), | | // UNIT=SYSDA,SPACE=(13300,(30,30)), | | // DCB=(RECFM=FB,LRECL=121,BLKSIZE=1210) | | //INLIST DD * | (4) | &TCINPUT | | /* | | //OUTLIST DD * | (5) | &TCOUTPUT | | // | | | +---------------------------------------------------------------+ Figure 28. mvslnk.jcl - Build Script for Link Edit and Bind 80 REXX and MVS Build Scripts The following notes correspond to the numbers in the right margin of the mvslnk.jcl build script, shown in Figure 28 on page 80. The notes explain concepts used in the build script. NOTE: 1. The SYSEXEC DD statement must point to the library where the REXX command file resides. In this example, the REXX command file (mvslnk.jcl) must be stored in JERI.TEAMC.REXXCMDS on the MVS host. 2. The LINKCTL DD statement is the temporary library where the link edit statements are stored. Because there should only be one link edit control statement for a link edit, this data set is allocated as a sequential file. This avoids having to determine the member name to specify in the command that allocates the SYSLIN file for the linkage editor. 3. The SYSLMOD DD statement is where the final load module is stored on the MVS host. &TCRELEAS is used to show how the data set name can be varied based on one of the TeamConnection parameters. &TCWKAREA is another TeamConnection parameter that can used in the build script as part of a data set name. Because the file type for the .lkd file is NONE when the part is defined to TeamConnection, the load module is not trans- ferred to TeamConnection for storage. This avoids trans- ferring large load modules back to TeamConnection. 4. The INLIST DD statement is used by mvsrplnk.rxp to obtain the names of the input parts. &TCINPUT results in multiple lines of in-stream data, with each line corresponding to one input part. The input parts included are based on the build tree. The file extensions are not included. Using a naming convention where the object module name and DBRM member have the same part name except for the file extension allows mvsrplnk.rxp to determine the name(s) of the DBRM member(s) that must be bound. For example, if the object module name is plidb2.obj, the corresponding DBRM name is plidb2.dbr. Because there are 2 DD statements for in-stream data (INLIST and OUTLIST), the INLIST DD statement is ended by the /*. Unlike normal in-stream data, the /* is included as the last line of input data. 5. The OUTLIST DD statement is used by mvsrplnk.rxp to obtain the names of the output parts. The load module (.lkd) is created with a file type of NONE. This avoids the overhead of bringing down the load module to the TeamConnection family. However, it also means that the .lkd part is not included with &TCOUTPUT. Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A81 The build trees for plidb2 and plidcic include a .msg part as an output from the build of the load module. See Figure 16 on page 29 for an example. Use a naming convention that the load module (.lkd), link edit control statements (.lnk), and message (.msg) parts all have the same part name except for the file extension. Unlike normal in-stream data, the /* that ends the INLIST DD statement causes a blank line to be included at the beginning of the OUTLIST input, before the first of the output parts is listed. The algorithm used by mvsrplnk.rxp to determine which parts must be bound is the following: o Using INLIST, build 2 arrays based on the input: - unique part name - number of times the unique part name appears in INLIST Every .obj / .dbr pair counts 2. If the .lnk part is named the same as the .obj / .dbr pair, then the count is 3. Exclude the /* from the list of unique part names o Using OUTLIST, find the part name for the .msg part. There should only be one part name listed within OUTLIST. Allow for any blank lines at the beginning of the OUTLIST in-stream data. o Find the part name from OUTLIST in the array of unique names that was built from INLIST. Subtract 1 from the number of occurrences for this unique name. o For each of the unique names in the array, if the number of occurrences is 2 or more, then the name represents a .obj / .dbr pair and a BIND needs to be done for the DBRM. A .lnk / .msg pair might have also existed with the same name, but the pair has been eliminated from the count. o If the number of occurrences is 0, this represents a .lnk / .msg pair, where the .msg part balanced out the .lnk part. o If the number of occurrences is 1, this represents a sit- uation where the .obj, .lnk, and .msg parts all have the same part name, but there is no DBRM. After the .lnk / .msg pair is eliminated from the count, only the .obj part remains. 82 REXX and MVS Build Scripts NOTES ON MVSRPLNK.RXP (THE REXX COMMAND FILE) The following figure shows the REXX command file that supports link edit and bind. Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A83 +---------------------------------------------------------------+ | | | /* REXX */ | | TRACE INTERMEDIATES | | | | parse arg db2 dli cics db2id db2col wkareanam otherparms| (1) | /*******************************************************|*************/ | /* INITIALIZATION | */ | /*******************************************************|*************/ | | (2) | wspc = 500 /* Space allocati|n default */ | | | dsnload = 'DSNA.DSNLOAD' /* DB2 libraries | */ | dfhload = 'CICS330.SDFHLOAD' /* CICS libraries| */ | | | plilib = 'SYS1.PLI.PLIBASE' /* PL/I libraries| */ | plilib2 = 'SYS1.PLI.SIBMBASE' | | plilib3 = 'SYS1.PLI.PLITASK' | | plilib4 = 'SYS1.PLI.SIBMLINK' | | | | reslib = 'SYS1.RESLIB' /* IMS libraries | */ | linklib = 'SYS1.LINKLIB' /* Linkage editor|library */ | | | say 'wkareanam =' wkareanam | | say 'otherparms=' otherparms | | | | /*******************************************************|*************/ | /* RETRIEVE DATASET NAMES FOR FILES DEFINED IN THE BUILD|SCRIPT */ | /*******************************************************|*************/ | | (3) | dsinfo = getdsn_last('DBRM') | | if dsinfo > 0 then | | call errorhndlr GETDBRM,dsinfo | | dbrmlib = SYSDSNAME | | | | dsinfo = getdsn_last('OBJECT') | | if dsinfo > 0 then | | call errorhndlr GETOBJECT,dsinfo | | objlib = SYSDSNAME | | | | dsinfo = getdsn_last('LINKCTL') | | if dsinfo > 0 then | | call errorhndlr GETLINKCTL,dsinfo | | linkctl = SYSDSNAME | | | +---------------------------------------------------------------+ Figure 29 (Part 1 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind 84 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | dsinfo = getdsn_last('SYSLMOD') | | if dsinfo > 0 then | | call errorhndlr GETSYSLMOD,dsinfo | | syslmod = SYSDSNAME | | | | /*******************************************************|*************/ | /* FORCE DB2, DLI, AND CICS PARAMETERS TO Y OR N | */ | /*******************************************************|*************/ | | (4) | if db2 <> 'Y' then | | db2 = 'N' | | if dli <> 'Y' then | | dli = 'N' | | if cics <> 'Y' then | | cics = 'N' | | | | /*******************************************************|*************/ | /* SET UP PL/I OPTIONS | */ | /*******************************************************|*************/ | | (5) | /* if wkareanam = 'INITWA' then | | < set options > | | else | | < set options > */ | | | | /*******************************************************|*************/ | /* CALL APPROPRIATE ROUTINES | */ | /*******************************************************|*************/ | | (6) | call link | | if db2 = 'Y' then | | do | | call getdbrmnams | | firstbind = 'y' | | do i = 1 to dbrmmbr.0 | | say dbrmmbr.i dbrmcnt.i /* SAY used for d|bugging */ | if dbrmcnt.i >= 2 then /* Need OBJ/DBR p|ir */ | do | | call bind | | firstbind = 'n' | | end | | end | | if firstbind = 'n' then /* Close .msg fil| */ | "execio * diskw MSGLISTX (finis)" | | end | | | | exit 0 | | | +---------------------------------------------------------------+ Figure 29 (Part 2 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A85 +---------------------------------------------------------------+ | | | link: | | /*******************************************************|*************/ | /* LINK THE OBJECT MODULES | */ | /*******************************************************|*************/ | | (7) | /* Order of link libraries varies based on whether CICS |s involved */ | if cics = 'Y' then | | do | | link_lib = "'"dfhload"'" "'"plilib"'" , | | "'"plilib2"'" "'"plilib3"'" "'"plilib4"'"| | if db2 = 'Y' then | | link_lib = link_lib "'"dsnload"'" | | if dli = 'Y' then | | link_lib = link_lib "'"reslib"'" | | end | | else | | do | | link_lib = "'"plilib"'" "'"plilib2"'" "'"plilib3"'" |'"plilib4"'" | if dli = 'Y' then | | link_lib = link_lib "'"reslib"'" | | if db2 = 'Y' then | | link_lib = link_lib "'"dsnload"'" | | end | | | | /* Optionally allocate files for program product librari|s here */ | | (8) | "ALLOC FI(SYSLIB) DA("link_lib") SHR REUSE" | | "ALLOC FI(SYSLIN) DA('"linkctl"') SHR REUSE" | | "ALLOC FI(OBJLIB) DA('"objlib"') SHR REUSE" | | "ALLOC FI(SYSLMOD) DA('"syslmod"') SHR REUSE" | | /* block sized changed from 800 to 1210 for SYSPRINT *| | "ALLOC FI(SYSPRINT) BLOCK(1210) SPACE("wspc","wspc") UNI|(SYSDA) REUSE" | "ALLOC FI(SYSUT1) BLOCK(1024) SPACE("wspc","wspc") UNI|(VIO) REUSE" | | (9) | "CALL '"linklib"(IEWL)' 'RENT,REUS,LET,LIST,XREF,MAP,", | | "AMODE(31),RMODE(ANY)'" | | link_rc = rc | | | | "FREE FI(SYSLIB,SYSLIN,OBJLIB,SYSLMOD,SYSUT1)" | | if link_rc < 0 | link_rc > 4 then | (10) | call errorhndlr LINK,link_rc,SYSPRINT | | else | | call TCOUThndlr LINK,link_rc,SYSPRINT | (11) | | | return | | | +---------------------------------------------------------------+ Figure 29 (Part 3 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind 86 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | bind: | | /*******************************************************|*************/ | /* BIND EXECUTES A DB2 BIND | */ | /*******************************************************|*************/ | | (12) | "ALLOC FI(DBRMLIB) DA('"dbrmlib"') SHR REUSE" | | "ALLOC FI(SYSPRINT) BLOCK(1210) SPACE("wspc","wspc") UNI|(SYSDA) REUSE" | "ALLOC FI(BINDIN) BLOCK(800) SPACE("wspc","wspc") UNIT|SYSDA) REUSE" | | (13) | drop bindctl bindbctl bindactl | | | (14) | /* The following assumes that packages are used and that|the bind */ | /* control statements can be in the REXX command file an| controlled */ | /* with parameters to the builder | */ | bindctl.1 = 'DSN SYSTEM('db2id')' | | bindctl.2 = 'BIND PACKAGE('db2col') -' | | bindctl.3 = ' MEMBER('dbrmmbr.i') -' | | bindctl.4 = ' ACT(REP) -' | | bindctl.5 = ' VALIDATE(BIND) -' | | bindctl.6 = ' ISOLATION(CS)' | | bindctl.7 = '* ENABLE(xxx)' /* Optional, if u|e fix * */ | bindctl.8 = '* OWNER(xxxxxxx)' /* comment & cont|nuation mark*/ | | | /* CLIST statements that must be included before the BIN| command */ | bindbctl.1 = 'SET BINDRC = 0' | | bindbctl.2 = 'ERROR DO' | | bindbctl.3 = ' SET BINDRC = &LASTCC' | | bindbctl.4 = ' IF &SYSPCMD = &SYSSCMD THEN GOTO BINDEXI|' | bindbctl.5 = ' ELSE RETURN' | | bindbctl.6 = 'END' | | | | /* CLIST statements that must be included after the BIND|command */ | bindactl.1 = 'END' | | bindactl.2 = 'BINDEXIT: ERROR OFF' | | bindactl.3 = 'EXIT CODE(&BINDRC)' | | | +---------------------------------------------------------------+ Figure 29 (Part 4 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A87 +---------------------------------------------------------------+ | | (15) | /* Build a CLIST that can run the BIND commands | */ | "EXECIO * DISKW BINDIN ( STEM bindbctl. )" | | "EXECIO * DISKW BINDIN ( STEM bindctl. )" | | "EXECIO * DISKW BINDIN ( STEM bindactl. OPEN FINIS )" | | dsinfo = getdsn_last('BINDIN') | | bindin_dsn = SYSDSNAME | | | (16) | /* Trap all output so that it goes to the bindout file | */ | drop bindout | | bindtrap = outtrap("bindout.") | | | (17) | /* Run the CLIST that was just created | */ | "EX '"bindin_dsn"'" | | bind_rc = rc | | bindtrap = outtrap(OFF) | | "execio * diskw SYSPRINT (stem bindout. open finis)" | | | | if firstbind = 'y' then | (18) | do | | dsinfo = getdsn_last('MSGLIST') | | if dsinfo > 0 then /* Save BIND messages |n MSGLIST DD*/ | call errorhndlr GETMSGLIST,dsinfo | | msglist = SYSDSNAME | | "ALLOC FI(MSGLISTX) DA('"msglist"') SHR REUSE" | | "execio * diskw MSGLISTX (open)" | | end | | "execio * diskw MSGLISTX (stem bindout.)" | | | | "FREE FI(BINDIN DBRMLIB)" | | if bind_rc < 0 | bind_rc > 4 then | (19) | call errorhndlr BIND,bind_rc,SYSPRINT | | else | | "FREE FI(SYSPRINT)" | (20) | | | return | | | +---------------------------------------------------------------+ Figure 29 (Part 5 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind 88 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | getdsn_last: procedure expose sysdsname sysmsglvl1 sysms|lvl2 | /*******************************************************|*************/ | /* DETERMINE DATA SET NAME OF A TEMPORARY FILE | */ | /*******************************************************|*************/ | parse arg ddname parm_rest | | getdsn ddname | | getdsn_rc = rc | | if getdsn_rc < 0 | getdsn_rc > 0 then | | sysdsname = '' | | else | | do | | last_dsn = sysdsname.0 | | sysdsname = sysdsname.last_dsn | | end | | return getdsn_rc | | | | | | getdbrmnams: procedure expose dbrmmbr. dbrmcnt. | (21) | /*******************************************************|*************/ | /* DETERMINE NAME OF OBJECT/DBRM MODULES FOR USE AS DBR| MEMBER NAME*/ | /*******************************************************|*************/ | dsinfo = getdsn_last('INLIST') /* List of .OBJ, |DBR, .LNK */ | if dsinfo > 0 then | | call errorhndlr GETINLIST,dsinfo | | inlist = SYSDSNAME | | | | dsinfo = getdsn_last('OUTLIST') /* List of .LKD (|hould be 1) */ | if dsinfo > 0 then | | call errorhndlr GETOUTLIST,dsinfo | | outlist = SYSDSNAME | | | | myinput. = '' /* Clear arrays | */ | myoutput. = '' | | dbrmmbr. = '' | | dbrmmbr.0 = 0 | | dbrmcnt. = 0 | | | | "ALLOC FI(INLISTX) DA('"inlist"') SHR REUSE" | | "execio * diskr INLISTX (stem myinput. open finis)" | | | +---------------------------------------------------------------+ Figure 29 (Part 6 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A89 +---------------------------------------------------------------+ | | | /* INLIST contains one line for each input in the build |ree. */ | /* Because the file extension is removed, the OBJ and DB|M outputs */ | /* and possibly the link edit command file cannot be dis|inguished. */ | /* Using the naming convention of xxxxx.OBJ and xxxxx.DB| for the */ | /* object module and corresponding DBRM allows you to de|ermine the */ | /* OBJ/DBR pairs. Using the naming convention that the |xxxx.LNK */ | /* xxxxx.LKD provide the link edit control statements an| */ | /* corresponding load module means that you can determin| which of */ | /* the lines in INLIST corresponds to the LNK part by lo|king at the */ | /* OUTLIST DD statement. OUTLIST should only have one l|ne in it -- */ | /* the line for the load module that is being built. | */ | | | do i = 1 to myinput.0 | | say myinput.i /* SAY used for d|bugging */ | | | if word(myinput.i,1) <> '/*' then /* skip eof marke| */ | do | | seenit = 'n' /* check if saw|name before */ | jmax = dbrmmbr.0 | | do j = 1 to jmax while seenit = 'n' | | say seenit /* SAY used for|debugging */ | say j dbrmmbr.j dbrmcnt.j /* SAY used for|debugging */ | if word(myinput.i,1) = dbrmmbr.j then /* Not new n|me */ | do | | dbrmcnt.j = dbrmcnt.j + 1 /* Bump count f|r this name */ | seenit = 'y' | | end | | end | | if seenit = 'n' then /* Not yet in d|rmmbr array */ | do | | say j /* SAY used for|debugging */ | dbrmmbr.0 = dbrmmbr.0 + 1 /* Bump unique |ames count */ | dbrmmbr.j = word(myinput.i,1) | | dbrmcnt.j = 1 /* Init count f|r this name */ | end | | end /* end check on|eof mark */ | end | | | | /* Get name of the load module from the OUTLIST DD state|ent */ | /* Do not count the name of the load module in determini|g if there */ | /* is an OBJ/DBR pair of inputs | */ | "ALLOC FI(OUTLISTX) DA('"outlist"') SHR REUSE" | | "execio * diskr OUTLISTX (stem myoutput. open finis)" | | | +---------------------------------------------------------------+ Figure 29 (Part 7 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind 90 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | seenit = 'n' | | do i = 1 to myoutput.0 while seenit = 'n' /* Loop til no|-blank line */ | loadmod = word(myoutput.i,1) /* Get name of lo|d module */ | say myoutput.i /* SAYs used for |ebugging */ | say loadmod | | if loadmod <> "" then | | seenit = 'y' | | end | | | | seenit = 'n' | | do j = 1 to dbrmmbr.0 while seenit = 'n' /* Go through p|ssible DBRMs*/ | if dbrmmbr.j = loadmod then | | do | | dbrmcnt.j = dbrmcnt.j - 1 | | seenit = 'y' | | end | | end | | | | return | | | | | | TCOUThndlr: procedure expose sysmsglvl1 sysmsglvl2 | | /*******************************************************|*************/ | /* ISSUE ERROR MESSAGE FOR FUNCTION, ERROR CODE, AND DA|A SET */ | /*******************************************************|*************/ | parse arg function, return_code, copyddname | | dsinfo = getdsn_last('ERRLIST') | | "ALLOC FI(ERROUT) DA('"SYSDSNAME"') MOD REUSE" | | if copyddname <> '' then | | do | | "execio * diskr "copyddname" (stem errvar. open fini|)" | "execio * diskw errout (STEM errvar. open finis)" | | "FREE FI("copyddname")" | | end | | else | | 'EXECIO 2 DISKW ERROUT (STEM sysmsglvl OPEN FINIS)' | | "FREE FI(ERROUT)" | | return | | | +---------------------------------------------------------------+ Figure 29 (Part 8 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A91 +---------------------------------------------------------------+ | | | errorhndlr: procedure expose sysmsglvl1 sysmsglvl2 | | /*******************************************************|*************/ | /* ISSUE ERROR MESSAGE FOR FUNCTION, ERROR CODE, AND DA|A SET */ | /*******************************************************|*************/ | parse arg function, return_code, copyddname | | dsinfo = getdsn_last('ERRLIST') | | "ALLOC FI(ERROUT) DA('"SYSDSNAME"') MOD REUSE" | | if copyddname <> '' then | | do | | "execio * diskr "copyddname" (stem errvar. open fini|)" | "execio * diskw errout (STEM errvar. open finis)" | | "FREE FI("copyddname")" | | end | | else | | 'EXECIO 2 DISKW ERROUT (STEM sysmsglvl OPEN FINIS)' | | "FREE FI(ERROUT)" | | exit(return_code) | | | +---------------------------------------------------------------+ Figure 29 (Part 9 of 9). mvsrplnk.rxp - REXX Command File Sup- porting Link Edit and Bind The following notes correspond to the numbers in the right margin of the mvsrplnk.rxp REXX command file, shown in Figure 29 on page 84. The notes explain concepts used in the REXX command file. NOTE: 1. The parameters for mvsrxpli.rxp are: DB2 Y/N flag indicating whether DB2 is involved DLI Y/N flag indicating whether any use of DL/I is involved. This includes both DL/I data bases and IMS data communications (IMS DC) calls. CICS Y/N flag indicating whether CICS is involved DB2ID DB2 subsystem ID to be used during the BIND DB2COL DB2 collection name to be used in creating a package from the DBRM WKAREANAM Name of the work area or driver for which the build is occurring OTHERPARMS Other parameters could be added in the future. 92 REXX and MVS Build Scripts 2. The initialization statements set the names of the MVS host libraries and other variables used in the REXX command file. You might need to change the names of the libraries to match the data set naming conventions for your organization. 3. Determine the names of the temporary data sets that were allocated to various DD statements. 4. Insure that the db2, dli, and cics parameters have only Y or N values. 5. You might need to include logic here to set the values of parameters that control the linkage editor and DB2 bind. These values can be set based on a combination of the work area name and the other parameters (db2, dli, cics and so on) that are received by mvsrplnk.rxp. 6. Call the correct (internal) subroutines based on the parame- ters that were passed to mvsrplnk.rxp. If DB2 is being used, call getdbrmnams to determine which parts have DBRMs. See "Notes on mvslnk.jcl (the Build Script)" on page 80. for an explanation of the algorithm used. For each part that has a DBRM, call the bind subroutine. After all DBRMs have been bound, close the MSGLIST file that contains all the results of the DB2 commands. 7. Build the concatenation sequence that is used for the linkage editor SYSLIB statement. The concatenation sequence varies depending on whether CICS, DL/I, and/or DB2 are used by the program(s) being linked. 8. Allocate data sets that are used by the linkage editor. The data sets allocated here correspond to the data sets that are used in your current JCL for the linkage editor. 9. Invoke the linkage editor, specifying the parameters to be used. The parameters are hard-coded in this example. 10. If there was an error, call the errorhndlr routine to format the linkage editor messages to go back to TeamConnection. 11. If there were no errors, call the TCOUThndlr routine to save the messages and other information that were written to the SYSPRINT file by the linkage editor. 12. Allocate data sets that are used by the DB2 BIND. The data sets allocated here correspond to the data sets that are used in your current JCL for a DB2 BIND. 13. Remove the values from any previous use of bindctl, bindbctl, and bindactl. These 3 arrays are used to build up the fol- lowing statements for a CLIST to run the BIND: Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A93 BINDCTL DSN and BIND statements BINDBCTL Statements in the CLIST that must run before the DSN and BIND statements BINDACTL Statements in the CLIST that must run after the DSN and BIND statements. A CLIST is used for the BIND because both the DSN and BIND statements have return codes and there needs to be a way of capturing and checking the return codes from each of the com- mands. 14. Build the arrays containing the statements needed for the CLIST. 15. Build the CLIST using the 3 arrays. 16. Set up to trap all the output from the CLIST in bindout. Bindout will contain the messages from both the DSN and BIND statements. 17. Run the CLIST. 18. If this is the first BIND, open the MSGLISTX data set that corresponds to MSGLIST in the mvslnk.jcl. Add the output from the DB2 commands to MSGLIST. MSGLISTX is closed by the main routine near note (6) after all DBRMs have been bound. 19. If there was an error, call the errorhndlr routine to format the DB2 messages to go back to TeamConnection. 20. If there were no errors, free the DB2 message output stored in SYSPRINT. 21. Use the INLIST and OUTLIST DD statements as a way of deter- mining which parts are DBRMs. See "Notes on mvslnk.jcl (the Build Script)" on page 80 for an explanation of the algorithm used. VARIATIONS IN LINK AND BIND The following sections describe variations in the basic technique that is described above. o "Combining mvsrxpli.rxp with mvsrplnk.rxp" on page 95 o "Using a BIND Command File" on page 96 o "Reducing the Number of Build Messages" on page 99 94 REXX and MVS Build Scripts Combining mvsrxpli.rxp with mvsrplnk.rxp ________________________________________ If each object module is always linked by itself and never linked into other modules, it should be possible to combine mvspli.jcl with mvslnk.jcl and mvsrxpli.rxp with mvsrplnk.rxp. This tech- nique has not been tested because mvsrplnk.rxp supports the more general case where it is necessary to: o Link several object modules together and bind their DBRMs at the same time o Link and bind on a different MVS system from where the pre- compile, translate, and compile are done. o Provide ability to ship object code and DBRMs as part of a product. If you decide to combine mvspli.jcl with mvslnk.jcl and mvsrxpli.rxp with mvsrplnk.rxp, consider the following: o Build Tree: - The .obj and .dbr parts might not need to be included in the build tree if there is no reason to keep them. - The .msg output file could be eliminated from the build tree -- it was added primarily as a means of matching the .lnk part to remove it from the list of unique part names when determining the DBRM names. o Merging mvslnk.jcl into mvspli.jcl - The DD statements for LINKCTL and SYSLMOD need to be added to mvspli.jcl - The DD statements for DBRM and OBJECT should be removed if the .obj and .dbr parts are removed from the build tree. It might be desirable to keep the 2 DD statements and use permanent data sets on the MVS host to save a copy of the object code and DBRM. - The DD statement for MSGLIST should be removed if the .msg part is removed from the build tree. - If the .obj, .dbr, and .msg parts are removed from the build tree, the OUTLIST DD statement should use &TCINPUT rather than &TCOUTPUT. This is because the .lkd part has a file type of NONE and thus does not contribute to &TCOUTPUT. Using &TCINPUT means that the .pli and .lnk parts are the only inputs. Use a naming convention that the .pli and .lnk part names must match except for the file extension. o Merging mvsrplnk.rxp into mvsrxpli.rxp Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A95 - The parameters for dli, db2id, and db2col should be added to mvsrxpli.rxp. - The variables plilib, plilib2, plilib3, plilib4, reslib, and linklib that are set in mvsrplnk.rxp should also be set in mvsrxpli.rxp. - The data set names for LINKLIB and SYSLMOD would need to be determined using the getdsn_last (internal) subrou- tine. - The dli parameter should be forced to a Y/N value. - There is no need to have a loop to handle multiple DBRMs because each PL/I module produces just one DBRM. - Logic would be needed to reallocate the object module from the compile step to the link edit step and the DBRM from the precompile step to the BIND step. Using a BIND Command File _________________________ Using &TCINPUT and &TCOUTPUT to determine which part names repre- sent a .obj / .dbr pair might not be applicable to your organiza- tion. For example, if you have other parts (for example, a PSB, CICS BMS source for a map, or IMS MFS source for a map), adding more parts like .msg to balance out these extra parts can be awkward. An alternative technique is to use a BIND command file that con- tains all the DB2 commands that are required to do all the binds for the DBRMs that are involved. This is similar in concept to using the .lnk file for the link edit control statements. To use a BIND command file, make the following changes: o Create the BIND command files in TeamConnection. For example, for the PL/I program with DB2 (plidb2.pli), create a corresponding BIND command file called plidb2.bnd that con- tains the following: BIND PACKAGE(TOOLCICS) - MEMBER(PLIDB2) - ACT(REP) - VALIDATE(BIND) - ISOLATION(CS) * ENABLE(xxx) /* Optional, if use fix * */ * OWNER(xxxxxxx) /* comment & continuation mark*/ where TOOLCICS is the DB2 collection ID 96 REXX and MVS Build Scripts o In the build trees shown in Figure 16 on page 29 and Figure 24 on page 34, add a bind control file (for example, plidb2.bnd or plidcic.bnd) as input to the .lkd part. o In mvslnk.jcl (Figure 28 on page 80), add the following: - Add a BINDCTL DD statement for a sequential file that looks like: //BINDCTL DD TCEXT=BND,DISP=(NEW,DELETE), // UNIT=SYSDA,SPACE=(32000,(30,10)), // DCB=(RECFM=FB,LRECL=80,BLKSIZE=3200) - Remove the INLIST and OUTLIST DD statements. o Modify the properties of the 4 builders that do link edits (mvsplilnk, mvsdb2plilnk, mvscicsplilnk, and mvsdb2cicsplilnk) to remove the DB2 collector id from the parameter list. For example, for mvsdb2plilnk, change the parameters on the builder definition: From: 'MVSRPLNK Y N N DSNA TOOLCICS &TCWKAREA' To: 'MVSRPLNK Y N N DSNA &TCWKAREA' o In mvsrplnk.rxp (Figure 29 on page 84), do the following: - Change the parse statement at comment (1) to remove the DB2 collection ID. The new parse statement looks like: parse arg db2 dli cics db2id wkareanam otherparms - In the section that retrieves the data sets names, near the end of comment (3), add the statements to retreive the data set name for the BINDCTL DD statement as follows: dsinfo = getdsn_last('BINDCTL') if dsinfo > 0 then call errorhndlr GETBINDCTL,dsinfo bindmbr = SYSDSNAME - Change the section that calls the appropriate routines at comment (6) to: call link if db2 = 'Y' then do call bind end Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A97 - Change the section that creates the bind control state- ments at comment (13) to read the statements from the BINDCTL DD statement rather than hard coding them. Change: From: drop bindctl bindbctl bindactl /* The following assumes that packages are used and that the bind */ /* control statements can be in the REXX command file and controlled */ /* with parameters to the builder */ bindctl.1 = 'DSN SYSTEM('db2id')' bindctl.2 = 'BIND PACKAGE('db2col') -' bindctl.3 = ' MEMBER('dbrmmbr.i') -' bindctl.4 = ' ACT(REP) -' bindctl.5 = ' VALIDATE(BIND) -' bindctl.6 = ' ISOLATION(CS)' bindctl.7 = '* ENABLE(xxx)' /* Optional, if use fix * */ bindctl.8 = '* OWNER(xxxxxxx)' /* comment & continuation mark*/ To: drop bindctl binddsn bindbctl bindactl /* The following assumes that the BIND control statements */ /* are in a part maintained within TeamConnection */ "ALLOC FI(BINDMBR) DA('"bindmbr"') SHR REUSE" */ "EXECIO * DISKR BINDMBR ( STEM bindctl. OPEN FINIS )" */ /* Create the DSN SYSTEM statement */ binddsn.1 = 'DSN SYSTEM('db2id')' - Change the statements that build the CLIST to run the BIND commands at comment (15) to also include the binddsn. array. The new statements should look like: /* Build a CLIST that can run the BIND commands */ "EXECIO * DISKW BINDIN ( STEM bindbctl. )" "EXECIO * DISKW BINDIN ( STEM binddsn. )" /* <=== new statement */ "EXECIO * DISKW BINDIN ( STEM bindctl. )" "EXECIO * DISKW BINDIN ( STEM bindactl. OPEN FINIS )" - Modify the statements that copy the BIND messages to the MSGLIST DD statement at comment (18). The new statements should look like: dsinfo = getdsn_last('MSGLIST') if dsinfo > 0 then /* Save BIND messages in MSGLIST DD*/ call errorhndlr GETMSGLIST,dsinfo msglist = SYSDSNAME "ALLOC FI(MSGLISTX) DA('"msglist"') SHR REUSE" "execio * diskw MSGLISTX (stem bindout. open finis)" 98 REXX and MVS Build Scripts The if logic to check on whether it is the first bind or not is no longer required because all the binds are done with a single call to DB2. - Modify the FREE statement just before comment (19) to also free the BINDMBR file. "FREE FI(BINDIN DBRMLIB BINDMBR)" - Remove the getdbrmnams routine that begins at comment (21). o If you use crtplibt.cmd as shown in Appendix B, "SAMPLE REXX TO CREATE BUILD TREES" on page 101, modify it so that it con- nects the .bnd part as input to the .lkd part. Reducing the Number of Build Messages _____________________________________ If you only want linkage editor messages to be returned when there is an error, replace the calls to TCOUThndlr with state- ments that free the output listing. The following change is needed to the link step at comment (11): From: call TCOUThndlr LINK,link_rc,SYSPRINT To: "FREE FI(SYSPRINT)" Appendix A. BUILDER, BUILD SCRIPT, AND REXX FOR LINK BIND A99 100 REXX and MVS Build Scripts APPENDIX B. SAMPLE REXX TO CREATE BUILD TREES The build trees shown in Figure 12 on page 27, Figure 16 on page 29, Figure 20 on page 32, and Figure 24 on page 34, follow 2 basic patterns - one without DB2 and one with DB2. Therefore, a REXX command file can be used to create the connections for the build tree. The syntax for the command is: crtplibt workareaName pgmname db2 where workareaName is the name of the work area in which you want to create the build tree pgmname is the name of the PL/I program for which you want to create the build tree db2 is a Y/N indicator that indicates whether DB2 is involved examples: crtplibt initwa plipgm n crtplibt initwa plidb2 y Figure 30 on page 102 shows a sample REXX command file to create the build trees shown in this document. (C) Copyright IBM Corp. 1997 101 +---------------------------------------------------------------+ | | | /*******************************************************|*******************/ | /* Create a build tree for a PL/I source part in TeamCon|ection */ | /*******************************************************|*******************/ | /* TRACE All */ | | | | /* This block of code gets the name of the command, for |ater use. */ | | | parse source . . cmdName | | cmdName = filespec("name",cmdName) | | cmdName = substr(cmdName,1,lastPos('.',cmdName)-1) | | | | /* Parse the command line and display usage, if needed. | */ | | | parse arg workareaName partname db2 | | | | if workareaName = "" | workareaName = "?" then | | do | | say 'usage: 'cmdName' workareaName partname db2' | | say "This procedure creates a build tree for the spe|ified part" | say "in the specified workarea. If the db2 paramete| is set to Y," | say "then the parts needed to support DB2 (the .dbr |nd .msg) parts" | say "are also connected to the build tree." | | say "Use just the part name without the extension (f|r example, plipgm)." | say "All necessary parts are assumed to exist." | | say "No error checking is included." | | say "Family and release are defaulted from the envir|nment variables." | exit 1 | | end | | | +---------------------------------------------------------------+ Figure 30 (Part 1 of 2). REXX Command File to Create Build Trees 102 REXX and MVS Build Scripts +---------------------------------------------------------------+ | | | /* Set family and release from the environment variables| */ | | | family = value('TC_FAMILY',,'OS2ENVIRONMENT') | | if family = '' then | | do | | say "The TeamConnection family was not set by the" | | say "TC_FAMILY environment variable." | | exit 1 | | end | | | | release = value('TC_RELEASE',,'OS2ENVIRONMENT') | | if release = '' then | | do | | say "The TeamConnection release name was not set by |he" | say "TC_RELEASE environment variable." | | exit 1 | | end | | | | /* Make the connections required to create the build tre| */ | | | 'teamc Part -connect 'partname'.pli -parent 'partname'|obj -input' , | '-release 'release ' -workarea 'workareaName ' -typ| TCPart' | 'teamc Part -connect mvsrxpli.rxp -parent 'partname'.o|j -input' , | '-release 'release ' -workarea 'workareaName ' -typ| TCPart' | 'teamc Part -connect 'partname'.obj -parent 'partname'|lkd -input' , | '-release 'release ' -workarea 'workareaName ' -typ| TCPart' | 'teamc Part -connect 'partname'.lnk -parent 'partname'|lkd -input' , | '-release 'release ' -workarea 'workareaName ' -typ| TCPart' | | | if db2 = 'y' then /* if db2 used, m|re connections */ | do | | 'teamc Part -connect 'partname'.dbr -parent 'partn|me'.obj -output' , | '-release 'release ' -workarea 'workareaName ' |type TCPart' | 'teamc Part -connect 'partname'.dbr -parent 'partn|me'.lkd -input' , | '-release 'release ' -workarea 'workareaName ' |type TCPart' | 'teamc Part -connect 'partname'.msg -parent 'partn|me'.lkd -output' , | '-release 'release ' -workarea 'workareaName ' |type TCPart' | end | | | | exit 0 | | | +---------------------------------------------------------------+ Figure 30 (Part 2 of 2). REXX Command File to Create Build Trees VARIATIONS IN CREATING THE BUILD TREES You could modify crtplibt.cmd to include the creation of the .obj, .dbr, and .msg parts. Creating these output parts would insure that they are created before the connections are made to create the build tree. Appendix B. SAMPLE REXX TO CREATE BUILD TREES 103 104 REXX and MVS Build Scripts APPENDIX C. GLOSSARY ACCESS AUTHORITY GROUP. An access authority group is a set of TeamConnection actions. ACCESS LIST. An access list is a list of TeamConnection users and their related access authority groups. The access list describes the actions a user can perform upon data controlled by the component or any descendant components. A user has explicit authority to perform these actions. Access can be inherited by other components. BUILD AGENT. A build agent is software on an OS/2 workstation that monitors the TeamConnection family's job queue for build events. A build agent removes build events from the job queue, sends the build script and input files to a build processor, and stores the returned outputs in the TeamConnection ObjectStore database. BUILD PROCESSOR. A build processor is software on a machine in a client/server network that waits for a build script and input files from a build agent. A build server runs the build script by passing control as needed to the tools specified in the build script. The build server then sends the outputs back to the build agent. BUILD SCRIPT. A build script specifies the command(s) to run to build a part. It is similar to one or more steps in an MVS job and can invoke translators such as a DB2 preprocessor, CICS translator, PL/I compiler, or a linkage editor. BUILD SERVER. Build agents and build processors always exist in pairs. A build agent/build processor pair is called a build server. BUILD TREE. The structure that represents the configuration of the parts of an application. BUILDER. A builder is a TeamConnection object that identifies a build script and the parameters to use when building a part. COMPONENT. A component organizes development data, controls access to the data, and notifies users when certain actions occur. Components can be used to organize the data by applica- tion, development team, type of data, or a combination. FAMILY. All data about an application is stored in a family. Families do not know about each other and cannot share data. FAMILY SERVER. The machine that runs the data base and stores/retrieves parts. It is a good idea to have a TeamConnection client on the family server. (C) Copyright IBM Corp. 1997 105 HOST LIST. A list of client machine addresses for access by a user ID. The host list provides the list of physical machines from which a particular user can log on. JCL. Job Control Language PARSER. A tool associated with a part that runs at build time and examines the part for dependencies (include statements, PL/I include members) PARTS. All data is stored in an object data base. Examples: source programs or include members. RELEASE. A release is a window into the data base. It controls the application development process. Parts can be linked or not linked between releases. Parts can have the same name in dif- ferent releases. SIBLING OUTPUTS. Two or more parts that are built together. The build tree diagram for the first shows the second part as an output. The build tree diagram for the second shows the first part as an output. The same builder and parameters apply to both parts. TEAMCONNECTION CLIENT. A machine that runs the TeamConnection client software. The user interface to TeamConnection is through a TeamConnection client. WORK AREA. A private view of the parts in a release. Developers make changes to parts that are checked out to work areas. 106 REXX and MVS Build Scripts