CA8B: CICS Transaction Server for OS/390 - BMS Map CWI conversion utility. Version 1.0

Transcription

1 CA8B: CICS Transaction Server for OS/390 - BMS Map CWI conversion utility Version 1.0 Issued: 01 December 1998 Revision Date: 01 December 1998 Previous Revision Date: None Review Date: As required Robert Harris The Netcics Developer IBM UK Limited Hursley Park Winchester Hampshire England Telephone : Office:... HARRISR@IBMGB Internet:..Robert_Harris@ibmuk.ibm.com

2 Notices Change Control Version Date Change made to supportpac /12/98 Initial release Edition Notice This edition applies to version 1.0 of CA8B: CICS Transaction Server for OS/390 - BMS Map CWI conversion utility and to all subsequent releases and modifications until otherwise indicated in new editions. Please address comments to the author, or to: IBM United Kingdom Limited, Transaction Systems Marketing Support (MP187), Hursley Park, Hursley, Winchester, Hampshire, England. When you s information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you. You may continue to use the information that you supply. Copyright International Business Machines Corporation All rights reserved. Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corporation. Notice The following paragraph does not apply in any country where such provisions are inconsistent with local law. INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore this statement may not apply to you.references in this publication to IBM products, programs, or services do not imply that IBM ints to make these available in all countries in which IBM operates. Any reference to an IBM licensed program or other IBM product in this publication is not inted to state or imply that only IBM s program or other product may be used. Any functionally equivalent program that does not infringe any of the intellectual property rights may be used instead of the IBM product. Evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, is the user s responsibility. IBM may have patents or ping patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can s license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, New York 10594,USA. The information contained in this document has not be submitted to any formal IBM test and is distributed AS IS. The use of the information or the implementation of any of these techniques is a customer responsibility and deps on the customer s ability to evaluate and integrate them into the customer s operational environment. While each item has been reviewed by IBM for accuracy in a specific situation, there is no guarantee that the same or similar results will be obtained elsewhere. Customers attempting to adapt these techniques to their own environments do so at their own risk. Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States and/or other countries: CICS MQSeries OS/390 MVS/ESA IBM Page ii

3 Preface What is this SupportPac This SupportPac contains a REXX for MVS Exec that scans Partitioned Datasets for CICS Transaction Server for OS/390 Release 1.2 BMS Maps and Mapsets. It returns a list of members in the PDS that are BMS Maps or Mapsets which can then be used to process the BMS Maps and Mapsets for CWI conversion. Example execs are included to demonstrate Mapset decompilation, CICS Web Interface template generation and repetitive editing. This SupportPac, therefore, is an aid to automating the repetitive and manual tasks required to enable BMS Maps for the CICS Web Interface for CICS Transaction Server for OS/390 Release 1.2. The Audience This SupportPac is designed for people who: Want to enable existing BMS based applications for the CICS TS 1.2 Web environment Want to uncompile BMS Mapsets to recover the source for Web enablement Want to repetitively edit BMS Source Users should have a general familiarity with Rexx programming and the CICS Transaction Server for OS/390 Release 1.2 Web Interface (especially the tasks required for web enablement of BMS Applications). Other SupportPacs Other SupportPacs that may be of interest are: CA86 An enhanced CICS Web Interface analyser Software Pre-requisites CICS Transaction Server for OS/390 Release 1.2 OS/390 Release 2.5 Bibliography You will need to be very familiar with the content of SC CICS Internet and External Interfaces Guide to use this SupportPac. You may also need to consult SC TSO/E REXX Reference, SC TSO/E Command Reference, GC IBM BatchPipes/MVS BatchPipeWorks Users Guide and GC IBM BatchPipes/MVS Users Guide and Reference. Page iii

4 Table of Contents Chapter 1: Introduction...5 The Concept... 5 Chapter 2: Installation...6 Unpacking the ZIP file... 6 Installation... 6 Accessing GETMEMS... 6 Chapter 3: Using GETMEMS...7 Syntax... 7 Examples:... 8 Chapter 4: Customising GETMEMS...9 How GETMEMS works... 9 Avoiding False Positives and False Negatives... 9 Specifying installation naming conventions Chapter 5: Using GETMEMS...11 Generating BMS Templates Uncompiling BMS Mapsets Adding HTML Customisation to BMS Source Page iv

5 Chapter 1: Introduction The Concept In order to enable existing BMS-based applications for the CICS Web Interface environment in CICS Transaction Server for OS/390 Release 1.2, a lot of manual work has to be performed: If the BMS source is not available, all the BMS compiled Mapsets have to be decompiled to recover the source DFHMDX statements must be added to all the BMS source to control HTML template generation All the BMS Maps may need to be recompiled to add ADT definitions All the BMS Maps must be compiled to generate the HTML templates This SupportPac provides a TSO/E Rexx exec which extracts the names of members from a PDS that contains Mapsets and Maps (amongst other things). The list of members can then be fed into other execs which automate these functions. Consequently, a lot of manual and repetitive work can be removed by using this SupportPac. The exec within this SupportPac will process: Loadlibs contains compiled BMS Mapsets Source PDSs containing BMS Map source The DFHHTML PDS containing generated Mapset templates Code snippets are included within this document to illustrate these processes. 1 Introduction Page 5 of 16

6 Chapter 2: Installation Unpacking the ZIP file Unzip CA8B.ZIP. It contains: CA8BEXEC.TXT - the exec for this SupportPac Installation Copy CA8BEXEC.TXT to a suitable MVS PDS (perhaps one that already contains REXX execs) as member GETMEMS. This PDS must be known to TSO if running at a terminal. This documentation assumes that you have put CA8BEXEC.TXT into the PDS as member GETMEMS. If you alter the member name, you call the function via this other name. Accessing GETMEMS Once the Exec is placed in a CLIST PDS, then you can run with it under TSO/E at a terminal or in Batch mode. It will usually be simpler to use batch mode, so you will use JCL like: //TSO EXEC PGM=IKJEFT01,REGION=4096K //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSEXEC DD DSN=pds.containing.getmems,DISP=SHR //SYSTSIN DD * rexx commands END /* 2 Installation Page 6 of 16

7 Chapter 3: Using GETMEMS Syntax GETMEMS is called as a REXX function which returns a Return Code string via: rcc = getmems(pdsname, operation, trace) where: pdsname Is the name of the PDS to be scanned. This is the Fully Qualified name of the file without quotes. In other words, specify the name of the file as in JCL. If the length of this parameter is 8 characters or less, then the name is not the DSN of a PDS but a DDName which refers to a PDS. operation Is the operation requested, which includes the type of the PDS: LB -> Scan a loadlib for BMS Mapsets BS -> Scan a source PDS for BMS Maps BH -> Scan the DFHHTML PDS for Maps trace Is the tracing required N -> No tracing required Y -> Trace operation rcc Is the result of the operation, in blank delimited words: 0 pdsdsn number_of_members member1 member rc error_message If the first word is 0, then GETMEMS succeeded scanning the PDS named in word 2 returning the number of members selected in word 3; words 4 and subsequent are the matched member names If the first word is 4, then GETMEMS failed with the return code in word 2; words 3 and subsequent contain an error message. 3 Using GETMEMS Page 7 of 16

8 Examples: Scanning the SDFHLOAD PDS for BMS Members via: rcc = getmems( CTS120.CICS520.SDFHLOAD, LB, N ) sets rcc to 0 CTS120.CICS520.SDFHLOAD 29 CAUMAP1 CAUMAP2 CAUMAP3 CAUMAP4 DFH IGB DFH IGC DFH IGS DFH IGX DFH IG1 DFH IG2 DFHCMCM DFHCTRH DFHCTRM DFHDBDE DFHDBIE DFHDBIK DFHDBMS DFHDBNE DFHDBNK DFHEDFM DFHRP0 DFHRP0H DFHSNLE DFHSNLK DFHSNSE DFHSNSK DFHWB0 DFHWB0H DFHXMSG The same result would be obtained if a //INLIB DD DSN=CTS120.CICS520.SDFHLOAD,DISP=SHR statement was in the JCL, and GETMEMS was execed via: rcc = getmems( INLIB, LB, N ) Note that the correct DSN for the DDName was placed in the output. Putting an unknown file will result in an error like: ListDsi failure of rc 16 Scanning a BMS Source file referred to by DDName INPUT is executed via: rcc = getmems( INPUT, BS, N ) And processing the DFHHTML PDS for Map templates occurs via: rcc = getmems( DFHHTML, BH, N ) 3 Using GETMEMS Page 8 of 16

9 Chapter 4: Customising GETMEMS How GETMEMS works GETMEMS has three functions, and works differently according to what type of PDS is being scanned. To scan the DFHHTML PDS to extract maps (the BH operation), all members are selected apart from those ing in HEAD or FOOT as these are template definitions for transactions. In scanning a source PDS for BMS Maps (the BS operation), all members of the PDS are read, and only those containing a call to the DFHMSD macro in column 10 are extracted. This extraction is done by MVS Pipes, and it is merely the presence of one of more lines in the member matching this criteria that governs selection. You may need to alter this selection if labels distort the column position. To extract a BMS Mapset from a loadlib (the LB operation), advantage is taken of the fact that a BMS Mapset is compiled as a table, and that the name of the mapset starts a record which has X 32 in a given position. This selection is done via MVS Pipes. To avoid confusion with a proper table, some customisation logic may need to be coded to link up the member name with that encoded in the mapset. False selection may also occur as well as invalid omission. Avoiding False Positives and False Negatives A False Negative result is obtained when the scan fails to detect a valid member. A False Positive result is where a member should not have been detected, but is selected. Unfortunately, the algorithm for detecting Maps and Mapsets (particularly for the LB operation which scans Loadlibs for BMS Mapsets) cannot be globally correct. Therefore, false positive and false negative conclusions may rer the results of GETMEMS inaccurate. Consequently, GETMEMS has facilities for avoiding these circumstances. To avoid false omissions or selections, add member names into the po.lb.n, po.lb.y, po.bs.y, po.bs.n, po.bh.n and po.bh.y variables. The.y items cope with false negatives and the.n items cope with false positives. Members are specified in Upper Case as blank-delimited words. When a member from the PDS is scanned, these variables are examined, and if the member name is found within the relevant.y variable, it will be taken to be selected (whatever the subsequent matching process might determine). Similiarly, if the member is found within the.n variable, it will be excluded from the list of matching members. As shipped, only po.lb.y is set to cope with a special case Mapset within CICS. 4 Customising GETMEMS Page 9 of 16

10 Specifying installation naming conventions The names of BMS Mapsets as specified in a PDS member may be different from that encoded in the compiled Mapset. The supplied code will cope with conventions like: the member name is the same as the Mapset name the member name is suffixed with a M in the Mapset the member name is prefixed with a M in the Mapset the Mapset has a trailing M which is not in the member name the Mapset has a leading M which is not in the member name If your naming convention is more complex, then you can code up your rules for selection. Edit the GETMEMS source after the default s8 settings, and set s8 to be Upper Case blank-delimited words that the Mapset could contain as a result of generation. 4 Customising GETMEMS Page 10 of 16

11 Chapter 5: Using GETMEMS The GETMEMS exec will be embedded within a calling exec. This section shows how you would use it for various tasks involved with BMS Maps for Web enablement.. Generating BMS Templates To generate a BMS Template into the DFHHTML PDS, an assembly has to be performed. In this example, the conversion runs as a new job submitted by the exec. The BMS source and destination HTML PDSs are specified statically. The things to observe are how the selected member name is embedded in the JCL (jcl.9), the way a new Queue is used to hold the generated job (newstack) before it is submitted and the use of a pipe to trap TSO/E command output. /* Rexx - html exec */ inlib = RHARRI1.BMSTEMP html = RHARRI1.BMSHTML rcc = getmems(inlib, BS, N ) if ( word(rcc,1) <> 0 ) then do say Getmems failure with rc rcc exit say Converting word(rcc,3) members in inlib to html if ( word(rcc,3) = 0 ) then exit jobmask = ABCDEFGHIJKLMNOPQRSTUVWXYZ jobmaskn = 1 do i = 1 to word(rcc,3) j = i + 3 mem = strip(word(rcc,j), B ) jcl.0 = 20 jcl.1 = //ASMTEMPL EXEC PGM=ASMA90, jcl.2 = // PARM= SYSPARM(TEMPLATE),DECK,NOOBJECT jcl.3 = //SYSPRINT DD SYSOUT=* jcl.4 = //SYSLIB DD DSN=CTS120.CICS520.SDFHMAC,DISP=SHR jcl.5 = // DD DSN=SYS1.MACLIB,DISP=SHR jcl.6 = //SYSUT1 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) jcl.7 = //SYSUT2 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) jcl.8 = //SYSUT3 DD UNIT=SYSDA,SPACE=(CYL,(5,5)) jcl.9 = //SYSIN DD DSN= inlib ( mem ),DISP=SHR jcl.10 = //SYSPUNCH DD DSN=&&PUNCH,DISP=(NEW,PASS), jcl.11 = // UNIT=SYSDA, jcl.12 = // SPACE=(CYL,(5,5)) 5 Using GETMEMS Page 11 of 16

12 jcl.13 = /* jcl.14 = //UPDTEMPL EXEC PGM=IEBUPDTE,PARM=NEW jcl.15 = //SYSPRINT DD SYSOUT=* jcl.16 = //SYSIN DD DSN=&&PUNCH,DISP=(OLD,DELETE) jcl.17 = //SYSUT2 DD DSN= html,disp=shr jcl.18 = /* jcl.19 = // jcl.20 = ## jc = substr(jobmask,jobmaskn,1) jobmaskn = jobmaskn + 1 if ( jobmaskn > length(jobmask) ) then jobmaskn = 1 drop tsol. tsol.0 = 0 newstack do k = 1 to jcl.0 queue jcl.k pipe (stagesep ;), tso submit * (##) jobchar( jc ) nonotify ;, stem tsol. ; hole delstack if ( ( tsol.0 <> TSOL.0 ), & ( tsol.0 <> ), & ( tsol.0 <> ), & ( tsol.0 <> 0 ), & ( tsol.0 > 1 ) ) then do say For mem (prefix jc ) submit returned do k = 2 to tsol.0 ; say tsol.k ; exit /* End of HTML Exec */ The same technique can be used to generate BMS Mapset compilations. 5 Using GETMEMS Page 12 of 16

13 Uncompiling BMS Mapsets To uncompile a BMS Mapset, you must have previously defined a PDS for the source. In this example, the conversion runs within the exec. The source loadlib and destination text PDSs are specified statically. The things to note about this sample is the way the required DDNames of DFHRPL and BMSOUT are dynamically allocated and deallocated before the conversion is executed within the Exec. This exec also shows how the constant tag is changed to the member name by use of an MVS Pipe after the decompilation has produced the BMS Source. /* Rexx - uncomp exec*/ loadlib = UTL.RHARRI1.LOAD pds = RHARRI1.BMSTEMP rcc = getmems(loadlib, LB, N ) if ( word(rcc,1) <> 0 ) then do say Getmems failure with rc rcc exit say Converting word(rcc,3) members in loadlib to pds if ( word(rcc,3) = 0 ) then exit drop tsol. tsol.0 = 0 pipe (stagesep ;), tso alloc ddname(dfhrpl), dsname( loadlib ) shr ;, stem tsol. ; hole if ( ( tsol.0 <> TSOL.0 ), & ( tsol.0 <> ), & ( tsol.0 <> ), & ( tsol.0 <> 0 ) ) then do rcc = Could not allocate DFHRPL do k = 1 to tsol.0 ; say tsol.k ; exit do i = 1 to word(rcc,3) j = i + 3 mem = strip(word(rcc,j), B ) pipe (stagesep ;) tso free ddname(bmsout) ; hole 5 Using GETMEMS Page 13 of 16

14 do i = 1 to word(rcc,3) j = i + 3 mem = strip(word(rcc,j), B ) pipe (stagesep ;) tso free ddname(bmsout) ; hole drop tsol. tsol.0 = 0 pipe (stagesep ;), tso alloc ddname(bmsout), dsname( pds ( mem ) ) shr ;, stem tsol. ; hole if ( ( tsol.0 <> TSOL.0 ), & ( tsol.0 <> ), & ( tsol.0 <> ), & ( tsol.0 <> 0 ) ) then do rcc = Could not allocate BMSOUT pds ( mem ) do k = 1 to tsol.0 ; say tsol.k ; exit say Converting mem call CTS120.CICS520.SDFHLOAD(DFHBMSUP) mem say Converted mem pipe (stagesep ;) tso free ddname(bmsout) ; hole mn = left(mem,8) pipe (stagesep ;), change 1-8 /@ / mn / ;, > pds ( mem ) ;, hole pipe (stagesep ;) tso free ddname(dfhrpl) ; hole /* End of UNCOMP */ 5 Using GETMEMS Page 14 of 16

15 Adding HTML Customisation to BMS Source To enable a BMS Map for HTML customisation, a special macro has to be added to the source. In this example, the exec shows how a repetitive edit can be performed. The special things about this exec are the way TSO/E Editor statements are supplied in their own stack and the alignment requirements for inserted Macro code. /* Rexx - BMSEDIT Exec */ inlib = RHARRI1.BMSTEMP rcc = getmems(inlib, BS, N ) if ( word(rcc,1) <> 0 ) then do say Getmems failure with rc rcc ; exit ; say Editing word(rcc,3) members in inlib if ( word(rcc,3) = 0 ) then exit do i = 1 to word(rcc,3) j = i + 3 mem = strip(word(rcc,j), B ) edt.0 = 10 edt.1 = FIND DFHMSD 9 edt.2 = UP 1 edt.3 = INSERT * Start of Automatic insertion edt.4 = INSERT copies(,10) MACRO edt.5 = INSERT copies(,10) DFHMSX edt.6 = INSERT copies(,10) DFHMDX MAPSET=*,MAP=*,PF24=Help edt.7 = INSERT copies(,10) MEND edt.8 = INSERT * End of Automatic insertion edt.9 = SAVE edt.10 = END NOSAVE drop tsol. tsol.0 = 0 newstack do k = 1 to edt.0 ; queue edt.k ; pipe (stagesep ;), tso edit inlib ( mem ) text nonum ;, stem tsol. ; hole delstack if ( ( tsol.0 <> TSOL.0 ), & ( tsol.0 <> ), & ( tsol.0 <> ), & ( tsol.0 <> 0 ) ) then do say For mem edit returned do k = 1 to tsol.0 ; say tsol.k ; exit /* End of BMSEDIT Exec */ 5 Using GETMEMS Page 15 of 16

16 >>>>>>>>>>>>>>>END of document<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< 5 Using GETMEMS Page 16 of 16