1. EGL – Calling COBOL on System z
Mark Evans

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

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

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

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

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

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

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

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. 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. Add Linkage Options Part1 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

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

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

16. System z Considerations

17. 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)

18. 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)

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

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

21. 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)

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

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

24. 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)

25. 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 V or
Enterprise Developer Server for z/OS V5.0 + PTFs
** See for more info on CICS Transaction Gateway

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

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

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

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

30. 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 “

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

32. 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 SG
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

33. Calling Stored Procedures

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

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

36. Create a Stored Procedure

37. Create a Stored Procedure

38. Backup Slides – System i

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

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

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

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

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

44. System i Lab Reference: WDSCInstallingandCalling.doc