®

IBM Software Group

© 2006 IBM Corporation

EGL Calling COBOL/C.I.C.S. Programs

This Learning Module shows how to use EGL to call COBOL C.I.C.S. programs, passing values in the DFHCOMMAREA

2

Topic

EGL Calls to Remote Programs (Overview)

Calling Java (terms and concepts)

Calling Java using ExternalType

Calling Java using JavaLib

Calling COBOL ProgramsCalling COBOL Programs

Calling RPG Programs

Sub-Topics:

EGL and Remote ProgramsEGL and Remote Programs

3

Calling COBOL Programs - Overview In this section you will learn how to call COBOL programs running on a System z as a CICS transaction (NotesNotes***)

This lab requires you to have open Internet (TCP/IP) access on your PC

You will be calling (up to) four COBOL/CICS transactions, running in an IBM mainframe in Dallas Texas

The steps you learn here should be generalize-able to your specific shop’s enablement

Here’s what you’ll do:1. (One-time step) Configure your WebSphere server for:

CICSECI calls (by using a CICSECI.RAR file) J2C connectivity

2. (For each CICS program to call) Create an EGL Linkage Part for your Build Files3. Create the business logic to call the CICS Program

Before you do the lab three important thingsBefore you do the lab three important things:1.1. This lab requires you to use WebSphere Application ServerThis lab requires you to use WebSphere Application Server – instead of Tomcatinstead of Tomcat.. This will mean that, if you’ve been using Tomcat for these workshops,

you’ll need to create a WebSphere project, as well as have installed or have access to a WebSphere server.

2. You should check with your I/T administrators, and find out if you can access the I/P address 192.195.29.60 192.195.29.60 – which is where the COBOL programs can be found (on a – which is where the COBOL programs can be found (on a mainframe in Dallas, TX)mainframe in Dallas, TX)

3.3. You need the You need the cicseci.rar cicseci.rar file, used to connect and make the calls. This file file, used to connect and make the calls. This file

EGL Logic Part…

Call cblpgm…

4

EGL – Access to Remote Programs (COBOL or Otherwise)EGL – Access to Remote Programs (COBOL or Otherwise) Standard EGL Call statement identifies the program

Call myprog (parm1, parm2);Call myprog (parm1, parm2);

No need to know how to make call

Parameters:

Can be individual data items, records or records containing an array 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)

EGL communications layer Provides the interface to various target specific communication protocols You do not need to know anything about how to make remote call

The details of making the connection to CICS from WebSphere are contained in an EGL “build file” in a linkage options part

5

EGL Requirements to Access Remote CICS Program EGL Requirements to Access Remote CICS Program

Note: There are two approaches to calling CICS from the client

1. The CTG client gateway (shown here)

2. Using CICSJ2C – not shown here, but conceptually equivalent. We will be using CICSJ2C

… Both approaches require the CTG Server software installed on the mainframe

6

EGL Communication/Configuration Options for Call EGL Communication/Configuration Options for Call (J2EE)(J2EE)

EGL (Call)EGL (Call)>Programs>Programs>PageHandlers>PageHandlers>Libraries>Libraries>Java Wrappers>Java Wrappers

EGL CommunicationsEGL Communications

• CICS (CTG CICS (CTG Client)Client)

Java Toolkit for AS400

System z

Windows/LinuxAIX, HP, Solaris

iSeries

Java CodeJava Code

USS(Java)

• EGL COBOLEGL COBOL• Native COBOLNative COBOL• RPGRPG• CLCL

CICSCICS• EGL COBOLEGL COBOL• Native COBOLNative COBOL• PL/IPL/I• AssemblerAssembler

IMSIMS

WebSphere Application Server

EGL TCP/IPListener

CTG Server

• IMSIMS

J2C AdaptersEXCI

TCP/IP

EGL TCP/IPEGL TCP/IPListenerListener

TCP/IP

TCP/IP

TCP/IP

Web Services Http

WEB

7

What Client (WAS or IDE) Software is Required for Remote Calls ? What Client (WAS or IDE) Software is Required for Remote Calls ? CICS CICS

J2EE - CICS Resource Adapter (CICSECI.RAR)– Supplied with J2EE Connector Tools *

– Optional Feature for Rational Application Developer

Non-J2EE - CICS Transaction Gateway – Just client jars (if CTG Gateway/server on a different machine)– Full Gateway if communicating directly to CICS from client machine– CTG V6.0.1 supplied as optional CD on Websphere Developer for z/OS *

• NOTE: For Development Use onlyNOTE: For Development Use only

IMSIMS IMS Connect Client side JAR files supplied with J2EE Connector Tools

iSeriesiSeries JT400 Toolkit Download from iSeries Operating System

8

What is Mainframe Software is Required for Remote Calls ? What is Mainframe Software is Required for Remote Calls ?

ServerServer CICS

CICS Transaction Server V2.2 (if no CTG server used on z/OS) CICS Transaction Gateway Server for z/OS (optional for pointers) – EGL COBOL Runtime for System z

IMS IMS/TM Connect Features EGL COBOL Runtime for System z

– To read message off of message queue– Converts parameters to pointers

iSeries EGL COBOL Runtime for iSeries - QEGL

– Stop and start commitment control– Converts parameters to pointers

9

Build Parts – Specifying the Call thru Linkage Options

A Linkage Options part specifies how: 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 OptionsLinkage Options are specified at: are specified at: 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, generated if genProperties=yes

10

Build Parts – Linkage Options Build Part EditorBuild Parts – Linkage Options Build Part EditorEGL Build File

Tabs for Build Parts in File

Switch Views between Linkage Option TypescallLink, asynchLink, transferLink, fileLink

Properties vary by type

Program callLink applies to

Type of callLink

Note: This is not the Build file, or Linkage Options part we will be using in our workshop.

This figure illustrates the different elements of Linkage Options

11

Key Linkage Options Parameters – J2EEKey Linkage Options Parameters – J2EE conversionTable = CSOE037CSOE037

This specifies the name of the conversion table to convert from Unicode on Windows and EBCDIC on z/OS

location = eis/eglcicseis/eglcics JNDI name of JCA resource defined to WebSphere Application Server

luwcontrol = SERVERSERVER Specifies to end the unit of work after each call and issue commit/rollback when returning

from the call.

parmform = COMMDATACOMMDATA Specifies whether the called program is expecting data as values or by reference.

COMMDATA is by value and COMMPTR is by reference

remoteComType = CICSJ2CCICSJ2C Tells the EGL Middleware that the call is to a CICS region and to use the CICS JCA

adapter

remotePgmType = EXTERNALLYDEFINEDEXTERNALLYDEFINED Specifies that the called program is a non-EGL program or an EGL generated Program

12

Key Linkage Options Parameters – Non-J2EE to CICS

conversionTable = CSOE037CSOE037 This specifies the name of the conversion table to convert from Unicode on Windows and EBCDIC on

z/OS ctgLocation = 127.0.0.1

This is the tcpip address of the gateway machine ctgPort = 20062006

This is the port the CTG gateway is listening on location = NRACICS3NRACICS3

Name of the CICS Region as defined to CICS Transaction Gateway luwcontrol = SERVERSERVER

Specifies to end the unit of work after each call and issue commit/rollback when returning from the call.

parmform = COMMDATACOMMDATA Specifies whether the called program is expecting data as values or by reference.

COMMDATA is by value and COMMPTR is by reference remoteComType = CICSECICICSECI

Tells the EGL Middleware that the call is to a CICS region and to use the ECI interface in CTG remotePgmType = EXTERNALLYDEFINEDEXTERNALLYDEFINED

Specifies that the called program is a non-EGL program or an EGL generated Program serverid = APMIAPMI

Specifies an alternate transaction for the CICS Mirror program if calling generated EGL COBOL as the transaction must have a TWASIZE of 1024 or greater.

Note: Non-J2EE access is for Java Batch, or the EGL debugger – Note: Non-J2EE access is for Java Batch, or the EGL debugger – notnot using WebSphere using WebSphere

13

EGL Statements – for Calling non-EGL Resources on z/OSEGL Statements – for Calling non-EGL Resources on z/OS

CALL statementCALL statementFor CICS or IMSFor CICS or IMSNo CommitsNo CommitsSame run unit (LUW)Same run unit (LUW)

TRANSFER to transaction TRANSFER to transaction For CICS or IMSFor CICS or IMS Commit, close files, close cursors and starts a new transactionCommit, close files, close cursors and starts a new transaction

TRANSFER to programTRANSFER to program Does not Commit/rollback but closes file, release locks and start a Does not Commit/rollback but closes file, release locks and start a program in the same run unitprogram in the same run unit

System function vglib.startTransaction() starts a run unit asynchronously.System function vglib.startTransaction() starts a run unit asynchronously. Does not affect the transferring program (databases, file, locks, etc..)Does not affect the transferring program (databases, file, locks, etc..)

Show statement (for textUI program or VGWebTransaction programs).Show statement (for textUI program or VGWebTransaction programs). Ends the program and shows data to the user.Ends the program and shows data to the user.

14

Available Materials (calling out to other resources)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

Proof of Technology Discovering the Value of Enterprise Generation Language (EGL)

to develop Java or COBOL Applications and implement SOA WDz based

Draft Whitepaper: Accessing CICS from the EGL Debugger - Install and Configuration Instructions

15

Lab – Big Picture and Steps – See Notes***

Here’s what you’ll do:1. (One-time step) Configure your WebSphere server for:

CICSECI calls (by using a CICSECI.RAR file) J2C connectivity You will use the WAS Console for this

2. (For each COBOL/CICS program to call) Modify your Build file Create a new Linkage Options part Add programs to the Linkage Options Add the Linkage Options part into the Build File

3. Create the EGL call the COBOL/CICS Program4. Create the Web Page to invoke the EGL – or show results

EGL Logic PartEGL Logic Part

call program…call program…

EGL Logic PartEGL Logic Part

call program…call program…

WebSphere WebSphere CICSECI.RAR fileCICSECI.RAR file

J2C connectivity J2C connectivity

CICS

COBOL Program

Linkage OptionsLinkage Options

Program entryProgram entry

See See ***Notes***Notes on Firewalls on Firewalls

16

1. Access the WebSphere Administration ConsoleWith your WebSphere Application Server started1. Right-click over the server entry in the Servers tab Select Run administrative console

If you are prompted to Login, just click Login – there is no password necessary

2. Expand the Resources entry, then the Resource Adapters entry and Click: Resource adaptersResource adapters

Notes:Notes: Setting up (installing and configuring) the CICS resource adapter is a one-time process, with multiple steps. First you will add (install) a new CICS resource adapter into WAS Then you will add a J2C Connection Factory to it – the J2C Connection Factory will have a JNDI name Finally, you will add custom properties to the Connection Factory, which point it to the CICS Server you will hit that runs CICS for your EGL calls .

17

Install the Resource Adapter (CICSECI.RAR) in the Server

Click the Install RARInstall RAR button Specify the local path location of the cicseci.rar file that exists in your project

<drive:\workspace>\EGLWeb\WebContent\images\cicseci.rar<drive:\workspace>\EGLWeb\WebContent\images\cicseci.rar

Click Click OpenOpen Click Click NextNext Click Click OKOK

18

Configure the J2C Connection Factory in the Server

You will be returned to the Resource adapters frame – and a new resource adapter will show in the list

ClickClick your new resource adapter

This will re-open the window with your new resource adapter. From there click: J2C connection factoriesJ2C connection factories

A new (empty) J2C connection factory entries will appear Click NewNew

A new Configuration screen will appear Add the two entries shown here:

See Notes***

Click ApplyApply

(From the top of the page) Click: SaveSave After saving, click: Custom properties (You will have to reselect/open the egl/eglcics connection)

1.1.

2.2.

eglcics

eis/eglcics

19

Specify Custom Properties for the J2C Connection Factory

From the Custom Properties list, you will enter four new custom properties as shown below: Click the property Name: example, click: TPNNameTPNName From the dialog window, enter the property Value: CPMICPMI

Enter these four custom properties – one at a time using the dialog windows:

1. TPNName: CPMICPMI2. ConnectionURL: tcp://192.195.29.60tcp://192.195.29.603. ServerName: CICSACB3CICSACB34. PortNumber: 20062006

Click: ApplyApply – and then from the top of the window, click: SaveSave Close Close the WebSphere Administrative Consolethe WebSphere Administrative Console

1.1.

2.2.3.3.

4.4.

20

2. Create a Linkage Options Part – 1 of 3 From Project Explorer,

Open EGLWeb.eglbld using the EGL Build Parts Editor From the Window menu, open an Outline View From the Outline View (bottom left corner of the Workbench)

Right-click over EGLWeb.eglbld, select Add Part… Select Linkage Options and click: Next Name the part: externalProgramsexternalPrograms click: FinishFinish

From the externalPrograms part:part: Click: Add AddIn the CallLink Elements:

Name the program: CBLCLSP1 CBLCLSP1 Type: remoteCall remoteCall

Enter the following properties: conversionTable (type): CSOE037CSOE037 location (type): eis/eglcicseis/eglcics luwControl (select): SERVERSERVER parmForm (select): COMMDATACOMMDATA remoteBind: GENERATIONGENERATION remoteComType (select): CICSJ2CCICSJ2C remotePgmType (select): EXTERNALLYDEFINEDEXTERNALLYDEFINED

Close Close and Save Save your Linkage Options – and Close/Save Close/Save the Build File Build File

21

2. Replicate the Linkage Options for Additional Programs – 2 of 3 From Project Explorer, Right-Click over EGLWeb.eglbld and select Open with Text editor Scroll down to the line <remoteCall pgmName=“CBLSP1”… Click your mouse at the beginning of the line (to set focus) Press Shift/End – to select the entire line (see below) Press Ctrl/C – to copy the line Enter a new line, and press Ctrl/V 3 times – to copy/paste the entire line three times Modify the pgmNames in the new line pgmNames:

CBLCLSP2CBLCLSP2

CBLCLSP3CBLCLSP3

CBLZPCKCBLZPCK

Note: each <remoteCall<remoteCall …… line must terminate with: "EXTERNALLYDEFINED"/>"EXTERNALLYDEFINED"/> </callLink></callLink> should terminate all four <remoteCall <remoteCall …… lines

22

2. Replicate the Linkage Options for Additional Programs – 3 of 3

Close and save your edits to the Linkage Options

Open EGLWeb.eglbld with the EGL Build Parts Editor Un-check: Show only specific options From the linkage Option, open the drop-down list and

select:externalPrograms

Close and save your Build file Right-click over your EGLWeb project and Generate

23

3. Create a New Page to Test Your COBOL Program Calls

Before creating the page you need to generate the new Build-file entries to Java Right-click over the \EGLSource\ folder and select GenerateGenerate

Now let’s create a page that calls your COBOL programs Right-click over \WebContent\ and select, New > Web Page Name the page: callCBL.jspcallCBL.jsp Change the boiler-plate page heading text as shown here…

Right-click and edit the Page CodeFrom inside the JSFHandler

Select and replace all of the boiler-plate code with the code in the Notes section of this slide Note that there is a lot of source code, as the four COBOL programs are included as comments at

the bottom Details of the program calls are covered on the next slide

24

3. EGL COBOL Program Calls

So – you can see from this example, that there is nothing complex whatsoever about calling COBOL/CICS programs from EGL. This JSFHandler has several different scenarios:

Passing individual parameters to COBOLPassing individual parameters to COBOL Passing a single recordPassing a single record Passing a record that contains an arrayPassing a record that contains an array

Here are the record definitions (nothing new…hope you’re not disappointed )

Press Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler

25

4. Create the Page Results

From Page Designer: From Page Data – drag csReccsRec

on to the page Make the top three fields input Make ShipCost output From options, specify no Submit

buttons (un-check) From Page Data – select all three

(callCBLCLSP1, callCBLCLSP2 and callCBLCLSP3) functions, and drag them onto the page, to create three submit buttons.

You can optionally add an HTML Horizontal Rule between the controls

From Page Data – drag csRecArraycsRecArray onto the page Make the first three columns

Input Text type Make ShipCostShipCost outputTextoutputText

26

Run the Page – and Call COBOL/CICS

Run the page on the server.

Enter the values as per the screen instructions.

Click one the buttons.

Note that callCBLCLSP2callCBLCLSP2 passes the same data (using a fixed record instead of individual parms).