EGL – Calling COBOL on System z Mark Evans evansm@us.ibm.com

© 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.

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

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

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

Agenda – Calls to Remote Resources Calls in EGL Language Linkage Options System z Considerations Infrastructure What’s required? System z linkage options COBOL <-> Data Mapping Lab: Calling System z Calling Stored Procedures

EGL Communication/Configuration Options for Call - (J2EE) Windows/Linux AIX, HP, Solaris J2EE WEB WebSphere Application Server EGL TCP/IP Listener Java Code Web Services Http EGL (Call) >Programs >PageHandlers >Libraries >Java Wrappers EGL Communications zSeries TCP/IP TCP/IP EGL TCP/IP Listener USS (Java) iSeries J2C Adapters C.I.C.S. EGL COBOL Native COBOL PL/I Assembler EXCI CTG Server Java Toolkit for AS400 C.I.C.S. (CTG Client) TCP/IP EGL COBOL Native COBOL RPG CL TCP/IP IMS IMS

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

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 Pass up to 30 parameters in EGL. On mainframe, all combined cannot be > 32K data. The details of making the connection to the remote system WebSphere are contained in an EGL “build file” in a linkage options part

Calling Remote Programs – COBOL Data Type Mapping EGL Datatype COBOL 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) int PIC S9(9) BINARY | COMP |COMP-4 smallint PIC S9(4) BINARY | COMP |COMP-4 bigint PIC 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) float COMP-2 date* PIC X(8) time* PIC X(6) timestamp* PIC X(14) money PIC S9(15)V9(2) * Has a predefined internal format – see helps

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

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

Add Linkage Options Part 1 2 3 Select build file and click right mouse to linkage options to current build file from outline view Choose Add part to add a new linkage options part Choose the linkage options Provide a name and click Finish 4

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

Linkage Options Build Part Editor – Specifying the linkage option EGL Build File 1 Program callLink applies to Type of callLink 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 Properties vary by type

System z Considerations

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

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

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

Key Linkage Options Properties – J2EE pgmname Program being called conversionTable Name of conversion table CSOE037 is conversion to US English (EBCDIC) ctgLocation Not Needed - in WAS resource definition ctgPort location JNDI Name entry in WAS Resource entries (case sensitive) Region name defined in WAS resource definition luwControl Tells EGL runtime to commit/rollback at end of each call (on return) parmForm Data is passed by value (COMMDATA) or pointer (COMMPTR) remoteBind Linkage information is set at generation time remoteComType Tell EGL communications layer what protocol to use CICSJ2C remotePgmType Specifies called program is EGL or non-EGL serverID Not Needed – in WAS resource definition

Key Linkage Options Properties – non-J2EE pgmname Program being called conversionTable Name of conversion table CSOE037 is conversion to US English (EBCDIC) ctgLocation Host name of the CTG Gateway/Server machine ctgPort Port CTG Gateway/Server is listening on location CICS Entry associated with CICS Region to call in CICS Gateway/Server INI files luwControl Tells EGL runtime to commit/rollback at end of each call (on return) parmForm Data is passed by value (COMMDATA) or pointer (COMMPTR) remoteBind Linkage information is set at generation time remoteComType Tell EGL communications layer what protocol to use CICSECI or CICSSSL remotePgmType Specifies called program is EGL or non-EGL serverID Transaction Started in CICS (must define TWASIZE of 1024)

What is required for Remote Calls – CICS ? Client (IDE – Debug - CICSECI) Access to CTG client code - ctgclient.jar Must be added to lib directory of WEB-INF Use import->File System OR Add to Debug Preference Classpath

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

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)

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 Gateway

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

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

Key Linkage Options Properties – J2EE pgmname Program being called conversionTable Name of conversion table CSOE037 is conversion to US English (EBCDIC) location JNDI Name entry in WAS Resource entries (case sensitive) Region name defined in WAS resource definition remoteBind Linkage information is set at generation time remoteComType Tell EGL communications layer what protocol to use IMSJ2C remotePgmType Specifies called program is EGL or non-EGL serverID Defines Transaction ID to invoke in IMS Region

Key Linkage Options Properties – J2EE pgmname Program being called conversionTable Name of conversion table CSOE037 is conversion to US English (EBCDIC) location IMS Connect hostname and port Datastore name in IMS Connect configuration luwControl Commits and Rollbacks at end of each call remoteBind Linkage information is set at generation time remoteComType Tell EGL communications layer what protocol to use IMSTCP (direct to IMS) remotePgmType Specifies called program is EGL or non-EGL serverID Defines Transaction ID to invoke in IMS Region

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”

Setting up IMS Resource Adapter (quick cheatsheet): Logon WAS Admin Console Expand Resources and select Resource Adapters Select Install RAR 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) Enter a Name for the adapter and optionally a description, then select Apply Under Additional Properties, select J2C connection factories Select New 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 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. Select Apply Under Additional Properties, select Custom properties For HostName enter the hostname of the machine where IMS Connect is running For PortNumber, enter the port number configured in IMS Connect. The default is 4000 Enter the datastore Name. It must match the ID parameter of the Datastore statement that is specified in the IMS Connect configuration member 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) Enter a Password to be used by default. Select OK to complete configuration. For more information, see redbook listed on previous page

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 Whitepaper/Docs: Accessing CICS from the EGL Debugger - Install and Configuration Instructions

Calling Stored Procedures

Create a Stored Procedure EGL Control Logic Drop the Stored Procedure Handle not found or error condition. Create your stored procedure

Create A Stored Procedure Drop the Stored Procedure Test for an SQL -204 (not found) condition.

Create a Stored Procedure

Create a Stored Procedure

Backup Slides – System i

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

Key Linkage Options Properties – System i pgmname Program being called conversionTable Name of conversion table CSOE037 is conversion to US English (EBCDIC) library System i library containing the called program (note: must also contain copy of QVGNRNCL) location Host name of the system I machine luwControl Tells EGL runtime to commit/rollback at end of each call (on return) remoteBind Linkage information is set at generation time remoteComType Tell EGL communications layer what protocol to use remotePgmType Specifies called program is EGL or non-EGL

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

What is required for Remote Calls – System i ? Getting the Java Toolkit for the 400 or With WDSC, in the following directory <% Install directory %> \rwdi_shared\eclipse\plugins\com.ibm.etools.iseries.toolbox_6.0.1\runtime From the System i directories \QIBM\ProdData\HTTP\Public\j4400\lib

Calling a Program – Setting Userid/Password Use syslib.setRemoteUser – built in function Can be set with literals or variables

System i Lab Reference: WDSCInstallingandCalling.doc