Upload
bruno
View
91
Download
4
Embed Size (px)
DESCRIPTION
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. EGL and Remote Programs. Topic. Sub-Topics:. EGL Calls to Remote Programs (Overview) Calling Java (terms and concepts) - PowerPoint PPT Presentation
Citation preview
®
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).