1. IBM Software Group © 2007 IBM Corporation Rational Residency Training EGL – Calling RPG, COBOL on System i and System z Mark EvansLinda Cole evansm@us.ibm.comlcole@ca.ibm.com

2. IBM Software Group | Rational Software © 2003 IBM Corporation 2 –© Copyright IBM Corporation 2007. All rights reserved. –The information contained in these materials is provided for informational purposes only, and is provided AS IS without warranty of any kind, express or implied. IBM shall not be responsible for any damages arising out of the use of, or otherwise related to, these materials. Nothing contained in these materials is intended to, nor shall have the effect of, creating any warranties or representations from IBM or its suppliers or licensors, or altering the terms and conditions of the applicable license agreement governing the use of IBM software. References in these materials to IBM products, programs, or services do not imply that they will be available in all countries in which IBM operates. –This information is based on current IBM product plans and strategy, which are subject to change by IBM without notice. Product release dates and/or capabilities referenced in these materials may change at any time at IBM’s sole discretion based on market opportunities or other factors, and are not intended to be a commitment to future product or feature availability in any way. –IBM, the IBM logo, the on-demand business logo, Rational, the Rational logo, and other IBM Rational products and services are trademarks or registered trademarks of the International Business Machines Corporation, in the United States, other countries or both. Other company, product, or service names may be trademarks or service marks of others.

3. IBM Software Group | Rational Software © 2003 IBM Corporation 3 Remote Resources: The big picture  Two Scenarios for EGL Developers: –Page Handlers/libraries executing under WAS or as native Java at runtime –EGL IDE and debugger when program targeted for COBOL execution  Both possibly need access to –Data –Called programs (non-EGL and EGL) – Basic capabilities and setup are the same for both scenarios – Coding does not change based on remote vs local

4. IBM Software Group | Rational Software © 2003 IBM Corporation 4 Web/Services Development Iterative Debug DB2 CICS/IMS COBOL RPG PLI EGL/non-EGL RAD/WDz WAS z/OS Selects, Updates,… Call Program Page Handlers/libraries executing under WAS or as native Java at runtime Scenario 1 – EGL Web/Services need access to mainframe resources System i

5. IBM Software Group | Rational Software © 2003 IBM Corporation 5 Scenario 2 – TUI Development -> need access to host during Debug 3270 EGL Development Iterative Debug DB2 CICS/IMS COBOL RPG PLI EGL/non-EGL RAD/WDz z/OS Generation Selects, Updates,… Call Program Using EGL IDE and debugger when program targeted for COBOL execution System i

6. IBM Software Group | Rational Software © 2003 IBM Corporation 6 Agenda – Calls to Remote Resources  Calls in EGL Language  Linkage Options  System i considerations –Infrastructure –What’s required? –System i linkage options –RPG EGL data mapping  Lab: Calling System I  System z Considerations –Infrastructure –What’s required? –System z linkage options –COBOL Data Mapping  Lab: Calling System z  Calling Stored Procedures

7. IBM Software Group | Rational Software © 2003 IBM Corporation 7 EGL Communication/Configuration Options for Call - (J2EE) EGL (Call) >Programs>PageHandlers>Libraries >Java Wrappers EGL Communications C.I.C.S. (CTG Client)C.I.C.S. (CTG Client) Java Toolkit for AS400 zSeries Windows/Linux AIX, HP, Solaris iSeries Java Code USS (Java) EGL COBOLEGL COBOL Native COBOLNative COBOL RPGRPG CLCL C.I.C.S. EGL COBOL EGL COBOL Native COBOL Native COBOL PL/I PL/I Assembler Assembler IMS WebSphere Application Server EGL TCP/IP Listener CTG Server IMSIMS J2C Adapters EXCI TCP/IP EGL TCP/IP Listener TCP/IP Web Services Http WEB J2EE

8. IBM Software Group | Rational Software © 2003 IBM Corporation 8 EGL Communication/Configuration Options for Call - (non-J2EE) EGL (Call) >Programs>Libraries >Java Wrappers >During Debug of TUI programs EGL Communications CTG Client Java Toolkit for AS400 zSeries Windows/Linux AIX, HP, Solaris iSeries Java Code USS (Java) EGL COBOLEGL COBOL Native COBOLNative COBOL RPGRPG CLCL C.I.C.S. EGL COBOL EGL COBOL Native COBOL Native COBOL PL/I PL/I Assembler Assembler IMS EGL TCP/IP Listener CTG Server IMS Connect * EXCI TCP/IP EGL TCP/IP Listener TCP/IP Web Services Http WEB CTG Server *Note: IMS Calls not currently supported from EGL debugger Non-J2EE

9. IBM Software Group | Rational Software © 2003 IBM Corporation 9 EGL – Access to Remote Programs  Standard EGL Call statement identifies the program  Call myprog parm1, parm2;  Parameters:  Can be items and/or records (up to 30)  Passed as values across network  Converted to pointers on mainframe as needed  Data converted on Client side before sending to mainframe  All are treated as in/out parameters (sent both ways)  CICS and IMS…total record can only be 32K in length  Data received using normal “linkage” methods for target program  EGL communications layer  Provides the interface to various target specific communication protocols  Developer does not need to know anything about:  APIs to make the remote call  How the call is physically implemented  Anything about conversions The details of making the connection to the remote system WebSphere are contained in an EGL “build file” in a linkage options part

10. IBM Software Group | Rational Software © 2003 IBM Corporation 10 Calling Remote Programs – COBOL Data Type Mapping EGL DatatypeCOBOL Data Type CHAR(n)PIC X(n) NUM(n) or NUMC(n)PIC S9(n) or PIC 9(n) NUM(n,d) or NUMC(n,d)PIC S9(n-d)V9(d) or PIC 9(n-d)V9(d) intPIC S9(9) BINARY | COMP |COMP-4 smallintPIC S9(4) BINARY | COMP |COMP-4 bigintPIC S9(18) BINARY | COMP |COMP-4 decimal(n) or pack(n) or pacf(n)PIC S9(n) PACKED-DECIMAL | COMP-3 decimal(n,d) or pack(n,d) or pacf(n,d)PIC S9(n-d)V9(d) PACKED-DECIMAL | COMP-3 hex(n)PIC X(n/2) Unicode(n)PIC N(n) NATIONAL dbchar(n)PIC G(n) DISPLAY-1 mbchar(n)PIC X(n) floatCOMP-2 date*PIC X(8) time*PIC X(6) timestamp*PIC X(14) moneyPIC S9(15)V9(2) * Has a predefined internal format – see helps

11. IBM Software Group | Rational Software © 2003 IBM Corporation 11 Specifying how to make the CALL - Linkage Options  A Linkage Options part specifies how : –Generated Java or COBOL program: Calls other generated code or non-generated code –Generated COBOL program Is called by other generated code –The EGL debugger resolves how to call other programs or non-EGL programs Example: Data Format Communications type Host transaction Id  Linkage options are specified through the build descriptors : –Generation time for COBOL or Java –Debug time (via Debug Build Descriptors) –Runtime for Java if build descriptor option remoteBind=runtime Options read from properties file if genProperties=yes

12. IBM Software Group | Rational Software © 2003 IBM Corporation 12 Build Parts – Linkage Options  There are linkage option elements –callLink Linkage information used for a given call to another program  Each linkage option element has several properties  Build descriptor option: “linkage” –Identifies the Linkage Options part to use –Use is optional and no default if not specified

13. IBM Software Group | Rational Software © 2003 IBM Corporation 13 Add Linkage Options Part 1 2 3 4 1.Select build file and click right mouse to linkage options to current build file from outline view 2.Choose Add part to add a new linkage options part 3.Choose the linkage options 4.Provide a name and click Finish

14. IBM Software Group | Rational Software © 2003 IBM Corporation 14 Linkage Options Build Part Editor - Adding Programs EGL Build File Tabs for Build Parts in File Switch Views between Linkage Option Types callLink, asynchLink, transferLink, fileLink Properties vary by type Program callLink applies to Type of callLink 1 2 3 1.Add a program name to match program name on “call statement” Can be a wildcard, example: pgm* to match all programs starting with pgm 2.Choose whether call is to be local or remote 3.Properties of the call 4.Search through list is first found based on order. Can move names up and down. 4

15. IBM Software Group | Rational Software © 2003 IBM Corporation 15 Linkage Options Build Part Editor – Specifying the linkage option EGL Build File Properties vary by type Program callLink applies to Type of callLink 1 1.Build Descriptor must associate the linkage options to use (this does not happen by default!) So can be different ones for debugging vs deployment if you have different build descriptors

16. IBM Software Group © 2007 IBM Corporation System i Considerations Reference: WDSCInstallingandCalling.doc

17. IBM Software Group | Rational Software © 2003 IBM Corporation 17 iSeries – i5 Machine QSYSWRK SBS QZRCSRVSD (Remote Command Server - daemon) TCP/IP QUSRWRK SBS QZRCSRVS Pre-start Jobs QZRCSRVS Evoked Jobs QEGLYourLIB EGL Client EGL Program EGL Communications QVGNSVR QVGNRNCLQVGNSETPYourPgm Source File: QVGNSAMP EGL Calling System i Programs 1 2 Java Toolbox Class 3 4 5 6 7 1.Call statement issued (call YourPgm) 2.EGL Java400 comm layer does data conversions and invokes JT400 APIs 3.JT400 Toolkit invokes iSeries Remote Command Server 4.iSeries Remote Command Services is used (prestarted jobs first) 5.EGL Catcher program (QVGNSRVR) is invoked from QEGL library 6.QVGNSETP invoked to set library list if needed (CAN BE CUSTOMIZED) 7.QVGNRNCL is invoked from user library (REQUIRED TO BE COPIED THERE) to set commitment control 8.Called program is invoked from user library 8

18. IBM Software Group | Rational Software © 2003 IBM Corporation 18 Key Linkage Options Properties – System i pgmnameProgram being called conversionTableName of conversion table CSOE037 is conversion to US English (EBCDIC) librarySystem i library containing the called program (note: must also contain copy of QVGNRNCL) locationHost name of the system I machine luwControlTells EGL runtime to commit/rollback at end of each call (on return) remoteBindLinkage information is set at generation time remoteComTypeTell EGL communications layer what protocol to use remotePgmTypeSpecifies called program is EGL or non-EGL

19. IBM Software Group | Rational Software © 2003 IBM Corporation 19 What is required for Remote Calls – System i ?  Client (WAS or IDE) –Java Toolkit for 400 Toolkit Java version – if Client is not on iSeries Native Version – If Client on iSeries machine –like WAS on i See next chart for info on how to obtain –Must be added to lib directory of WEB-INF Use import->File System  Server (iSeries) –EGL COBOL Runtime for iSeries Obtained through WDSC-AE V6 or Working to make call support code downloadable for free –iSeries Remote Command Server

20. IBM Software Group | Rational Software © 2003 IBM Corporation 20 What is required for Remote Calls – System i ?  Getting the Java Toolkit for the 400 or  With WDSC, in the following directory – \rwdi_shared\eclipse\plugins\com.ibm.etools.iseries.toolbox_6.0.1\runtime or  From the System i directories –\QIBM\ProdData\HTTP\Public\j4400\lib

21. IBM Software Group | Rational Software © 2003 IBM Corporation 21 Calling a Program – Setting Userid/Password  Use syslib.setRemoteUser – built in function –Can be set with literals or variables

22. IBM Software Group © 2007 IBM Corporation System i Lab Reference: WDSCInstallingandCalling.doc

23. IBM Software Group © 2007 IBM Corporation System z Considerations Reference(s): - InstallingandConfiguringCICSClientwEGL.doc - CICS_SetupScreenShots.doc

24. IBM Software Group | Rational Software © 2003 IBM Corporation 24 Configuration - Calling remote CICS Progams – J2EE WAS server EGL Communications Layer z/OS EGL/JSF J2C Config Distributed CICS Called Program) Tcpipservice port CTG Gateway Daemon CTG Server TCP/IP CTG Client Daemon Choice VTAM w/AnyNET TCP62 (LU62 within TCP/IP) LU62 MRO/EXCI TCP/IP (CICSJ2C)

25. IBM Software Group | Rational Software © 2003 IBM Corporation 25 Configuration - Calling remote CICS Progams – Non-J2EE IDE Debug Native Java EGL Communications Layer z/OS EGL Logic J2C Config Distributed CICS ELACSV (only when called PGM pointers) Tcpipservice port CTG Gateway Daemon CTG Server TCP/IP CTG Client Daemon Choice VTAM w/AnyNET TCP62 (LU62 within TCP/IP) LU62 MRO/EXCI TCP/IP EGL or native Program (CICSECI)

26. IBM Software Group | Rational Software © 2003 IBM Corporation 26 CTG Gateway/Server TID1 DFHMIRS TID2 DFHMIRS As Needed EGL COBOL Runtime YourLIB EGL Client EGL Program EGL Communications ELACSV YourPgm EGL Calling CICS Programs 1 2 CTG Client 3 4 5 7 1.Call statement issued (call YourPgm) 2.EGL CICSxxx comm layer does data conversions and invokes CTG APIs 3.CTG Client communicates with CTG Gateway/Server 4.CTG Server invokes TID1 (associated with DFHMIRS…required CICS prog) 5.DFHMIRS links to called program. Directly when data is to be sent as values (COMMDATA) 6.DFHMIRS links to ELACSV (as specified by EGL communications) when data is to be received as pointers or uses dynamic arrays. 7.ELACSV allocates storage and calls and passes data to called program CICS Region 6

27. IBM Software Group | Rational Software © 2003 IBM Corporation 27 Key Linkage Options Properties – J2EE pgmnameProgram being called conversionTableName of conversion table CSOE037 is conversion to US English (EBCDIC) ctgLocationNot Needed - in WAS resource definition ctgPortNot Needed - in WAS resource definition locationJNDI Name entry in WAS Resource entries (case sensitive) Region name defined in WAS resource definition luwControlTells EGL runtime to commit/rollback at end of each call (on return) parmFormData is passed by value (COMMDATA) or pointer (COMMPTR) remoteBindLinkage information is set at generation time remoteComTypeTell EGL communications layer what protocol to use CICSJ2C remotePgmTypeSpecifies called program is EGL or non-EGL serverIDNot Needed – in WAS resource definition

28. IBM Software Group | Rational Software © 2003 IBM Corporation 28 Key Linkage Options Properties – non-J2EE pgmnameProgram being called conversionTableName of conversion table CSOE037 is conversion to US English (EBCDIC) ctgLocationHost name of the CTG Gateway/Server machine ctgPortPort CTG Gateway/Server is listening on locationCICS Entry associated with CICS Region to call in CICS Gateway/Server INI files luwControlTells EGL runtime to commit/rollback at end of each call (on return) parmFormData is passed by value (COMMDATA) or pointer (COMMPTR) remoteBindLinkage information is set at generation time remoteComTypeTell EGL communications layer what protocol to use CICSECI or CICSSSL remotePgmTypeSpecifies called program is EGL or non-EGL serverIDTransaction Started in CICS (must define TWASIZE of 1024)

29. IBM Software Group | Rational Software © 2003 IBM Corporation 29 What is required for Remote Calls – CICS ?  Client (IDE – Debug - CICSECI) –Access to CTG client code - ctgclient.jar 1.Must be added to lib directory of WEB-INF –Use import->File System OR 2.Add to Debug Preference Classpath

30. IBM Software Group | Rational Software © 2003 IBM Corporation 30 What is required for Remote Calls – CICS ?  Client (WAS) –CICS Resource Defined to WAS – uses CICSECI.RAR –Referenced by JNDI Name (e.g. eis/NRACICS3) Connection information to host is in Connection Factory definition –More in referenced docs and lab

31. IBM Software Group | Rational Software © 2003 IBM Corporation 31 What is required for Remote Calls – CICS ?  Getting CICS Transaction Gateway CLIENT Code –EGL V6 CICS Transaction Gateway for Multi-platforms V6 or later –Purchase license (multiple ways to license) –If using WebSphere developer for z/Series, then is extra CD in media pack (Development License only) Purchase CICS Transaction Gateway for z/OS V6 or later (MLC license) Use/Download ctgclient.jar (non-J2EE) or CICSECI.rar (J2EE) Install Optional RAD J2EE Connectors Feature through Rational Product Updater Use CICSECIxxx.rar (contains ctgcient.jar if expanded)

32. IBM Software Group | Rational Software © 2003 IBM Corporation 32 What is required for Remote Calls – CICS ?  Getting CICS Transaction Gateway GATEWAY/SERVER Code CICS Transaction Gateway for Multi-platforms V6 or later –Purchase license (multiple ways to license) –If using WebSphere developer for z/Series, then is extra CD in media pack >Licensed for Development purposes only Purchase CICS Transaction Gateway for z/OS V6 or later (MLC)  For Direct TCP/IP Connection to CICS CICS Transaction Server V2.2 or later  To support Calls where called program requires pointers EGL COBOL Runtime –IBM Rational COBOL Runtime for zSeries V6.0.1 or –Enterprise Developer Server for z/OS V5.0 + PTFs ** See www.ibm.com/cics/ctg for more info on CICS Transaction Gatewaywww.ibm.com/cics/ctg

33. IBM Software Group | Rational Software © 2003 IBM Corporation 33 Calling a Program CICS – Setting Userid/Password  Use syslib.setRemoteUser – built in function (as in iSeries)  If J2EE/WAS J2C Resource, setup WAS Security entries –See labs and documents  If non-J2EE and using EGL Debugger: –Use EGL Debug Preferences – Remote Userid and Password –If using local CTG Gateway Daemon/Client daemon, can set to request prompt of userid and password

34. IBM Software Group | Rational Software © 2003 IBM Corporation 34 EGL V6 – SOA Integration with Enterprise Servers WAS server EGL Generated Web Service code Call Programx DB2 z/OS Client WAS web Services J2C Config AIX/Linux/zOS CICS EGL Generated ProgramX Or Native COBOL Programx Tcpipservice port  Web Service is created using EGL wizard based on already created EGL Programx  No additional coding needed by programmers…just develop called program and generate needed artifact CTG Server

35. IBM Software Group | Rational Software © 2003 IBM Corporation 35 Future: – Exploiting CICS Web Services with EGL –EGL will generate CICS required files WSBind File WSDL Pipeline Resource Definition WebService Resource Definition –Notes: CICS Support team will need Web Services setup/infrastructure skills Requires CICS V3.1 EGL Generated Service Receives parms and issues … Call Programx DB2 z/OS Client CICS Web Services Support CICS EGL Generated ProgramX Or Native Programx

36. IBM Software Group | Rational Software © 2003 IBM Corporation 36 IMS Connector EGL COBOL Runtime YourLIB EGL Client EGL Program EGL Communications ELAISVN YourPgm EGL Calling IMS Programs 1 2 IMS Connect Client J2C or TCP direct 3 4 5 1.Call statement issued (call YourPgm) 2.EGL CICSxxx comm layer does data conversions and invokes IMS Connector APIs 3.IMS Connector Client code communicates with IMS Connect on host 4.IMS Connect invokes transaction associated with ELAISVN (provided by EGL COBOL Runtime) See EGL Helps for more information 5.ELAISVN - Reads messages off of queue - Converts data into pointers - Calls “YourPGM” IMS-TM Region * NOTE: In EGL V6, cannot call from Debugger to IMS

37. IBM Software Group | Rational Software © 2003 IBM Corporation 37 Key Linkage Options Properties – J2EE pgmnameProgram being called conversionTableName of conversion table CSOE037 is conversion to US English (EBCDIC) locationJNDI Name entry in WAS Resource entries (case sensitive) Region name defined in WAS resource definition remoteBindLinkage information is set at generation time remoteComTypeTell EGL communications layer what protocol to use IMSJ2C remotePgmTypeSpecifies called program is EGL or non-EGL serverIDDefines Transaction ID to invoke in IMS Region

38. IBM Software Group | Rational Software © 2003 IBM Corporation 38 Key Linkage Options Properties – J2EE pgmnameProgram being called conversionTableName of conversion table CSOE037 is conversion to US English (EBCDIC) locationIMS Connect hostname and port Datastore name in IMS Connect configuration luwControlCommits and Rollbacks at end of each call remoteBindLinkage information is set at generation time remoteComTypeTell EGL communications layer what protocol to use IMSTCP (direct to IMS) remotePgmTypeSpecifies called program is EGL or non-EGL serverIDDefines Transaction ID to invoke in IMS Region

39. IBM Software Group | Rational Software © 2003 IBM Corporation 39 What is required for Remote Calls - IMS?  Client (WAS/J2C) IMS Connector for Java Resource adapter and configured –Client side JAR files supplied with J2EE Connector Feature >see CICS slides on how to find >Development time license only  Client (TCP Direct – non-J2EE) IMS Connector for Java –Needed Jar files in project classpath >ccf2.jar >connector.jar >Imsico.jar  Server IMS/TM IMS Connect Features for IMS/TM EGL COBOL Runtime for zSeries –IBM Rational COBOL Runtime for z/Series V6.0.1 or –Enterprise Developer Server for z/OS V5.0 + PTFs  Additional Documentation/links –IBM Connect Redbook “ http://www.redbooks.ibm.com/abstracts/sg246794.html?Open”

40. IBM Software Group | Rational Software © 2003 IBM Corporation 40 Setting up IMS Resource Adapter (quick cheatsheet): 1.Logon WAS Admin Console 2.Expand Resources and select Resource Adapters 3.Select Install RAR 4.Under Path, select Local path and use the Browse button to Navigate to the IMS Connect rar file for IMS Connect for Java (imsico.rar) 5.Enter a Name for the adapter and optionally a description, then select Apply 6.Under Additional Properties, select J2C connection factories 7.Select New 8.Enter some Name, and the JNDI name that you will specify for the location field of the called program's entry in a Linkage table part. Maybe eis/SERVERNAME  must match the location linkage property 9.Under Container-managed authentication, Authentication preference, can leave BASIC_PASSWORD for now. In a real system you would define a JAAS Authentication Alias and specify that in the Component-managed authentication alias drop down. 10.Select Apply 11.Under Additional Properties, select Custom properties 12.For HostName enter the hostname of the machine where IMS Connect is running 13.For PortNumber, enter the port number configured in IMS Connect. The default is 4000 14.Enter the datastore Name. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member 15.Enter a UserName to be used by default when making a connection. (The setRemoteUser() system function can be used to specify a different user ID and password) 16.Enter a Password to be used by default. 17.Select OK to complete configuration. For more information, see redbook listed on previous page

41. IBM Software Group | Rational Software © 2003 IBM Corporation 41 Available Materials (calling out to other resources)  White Papers on Developerworks –Calling Legacy COBOL/CICS Programs using EGL and J2EE Connectors (Reginaldo Barosa) WDz based –EGL integration with Java using Rational Application Developer V6 (Reginaldo Barosa)  Redbooks –Legacy Modernization with WebSphere Studio Enterprise Developer SG24-6806 Older but some good concepts on setup of EGL  POTs –Discovering the Value of Enterprise Generation Language (EGL) to develop Java or COBOL Applications and implement SOA WDz based  Whitepaper/Docs: –Accessing CICS from the EGL Debugger - Install and Configuration Instructions

42. IBM Software Group © 2007 IBM Corporation Calling Stored Procedures

43. IBM Software Group | Rational Software © 2003 IBM Corporation 43 EGL Control Logic Drop the Stored Procedure Handle not found or error condition. Create your stored procedure Create a Stored Procedure

44. IBM Software Group | Rational Software © 2003 IBM Corporation 44 Drop the Stored Procedure Test for an SQL -204 (not found) condition. Create A Stored Procedure

45. IBM Software Group | Rational Software © 2003 IBM Corporation 45 Create a Stored Procedure

46. IBM Software Group | Rational Software © 2003 IBM Corporation 46 Create a Stored Procedure