®

IBM Software Group

© 2006 IBM Corporation

EGL Calling RPG Programs

This Learning Module shows how to use EGL to call RPG programs, running on System i

2

Topic

EGL Calls to Remote Programs (Overview)

Calling Java (terms and concepts)

Calling Java using ExternalType

Calling Java using JavaLib

Calling COBOL Programs

Calling RPG ProgramsCalling RPG Programs

Sub-Topics:

EGL and Remote ProgramsEGL and Remote Programs

3

Calling RPG ProgramsCalling RPG Programs

In this section you will learn how to call RPG programs running on an IBM iSeries server.

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

You will be calling (up to) four RPG transactions,running in an IBM System i in Toronto, Canada.

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

Here’s what you’ll do:1. Add the iSeries JT400 toolkit to your project2. (For each RPG program to call) Add to the EGL Linkage Part for your Build File3. Create the business logic to call the RPG Program

First we will start with an overview of the system architecture and process

EGL Logic PartEGL Logic Part

call program…call program…

EGL Logic PartEGL Logic Part

call program…call program…

4

Calling RPG Programs - Overview

Calling a RPG, COBOL, CL, or other program on the System i from EGL is as simple as coding:

callcall “myProgram” (parm1, parmN); “myProgram” (parm1, parmN);

The facility is however extremely flexible and supports the many options that may be required to support many possible options and configurations. EGL takes into account the many possible runtime options that may affect how you run your jobs and call the RPG programs.

EGL uses the System i Toolbox for Java™ to call programs on the System i. The toolbox in turn uses the i5/OS Remote Command server that is a part of the i5/OS Host Servers.

The Remote Command server in i5/OS consists of a server daemon program that listens for TCP/IP requests from “clients”. This program is QZRCSRVSD which runs in the QSYSWRK sub-system.

When the Remote Command Server starts, it starts a number of “worker” jobs that process requests in the QUSRSYS sub-system. These jobs are all named QZRCSRVS.

The next slide describes this process in graphical and technical (in the Notes section) detail

5

Calling RPG Programs – System Architecture Your EGL application calls RPG through a series of Qxxx system modules, via the JT400.JARJT400.JAR

(Java) toolbox

See See ***Notes***Notes on on calling an external calling an external RPG program and RPG program and Firewalls.Firewalls.

If calling COBOL on the iIf calling COBOL on the i

If If calling calling

RPG RPG directlydirectly

6

Calling RPG Programs – Steps (Revisited)

Here’s what you’ll do:

One time step- Add the iSeries JT400 toolkit to your project and Java Build Path

Once for each RPG program to call- Add an EGL Linkage Part for the program

For each call- Code the business logic to call the RPG Program, from an EGL “client” logic part:

- Service- JSFHandler- Program- Library

7

Add to the JT400 Toolkit to your Project

Calling RPG programs on an iSeries box requires the JT400 toolkit in your build path. There are 2 ways to do this (you only need to do one of these)

1. Add the file to the build path Right-click over your project and select Properties In the window that pops up, select Java Build Path on the left side of the screen Select Add External Jars… Find the jt400.jar file on your pc, select Open, Select OK to close the

properties window.

2. Put the file in the WEB-INFLib folder. Switch to the Resource perspective Expand Web Content WEB-INF lib folder

– Drag jt400.jar into this folder

Drag Here

8

Add to the Build File’s Linkage Option – 1 of 2

From Project Explorer, Open EGLWebEGLWeb.eglbld using the EGL Build Parts Editor From the Window menu, open the Outline View

(It should be located at the bottom left corner of the tool, next to “Page Data” View) From the Outline View, select “externalPrograms”

(you should have created this during the calling Cobol workshop)

From the externalPrograms part:part: Click: Add Add

In the CallLink Elements: Name the program: RPG1 RPG1 Type: remoteCall remoteCall

Enter the following properties: Alias: RPGCLSP1 conversionTable (type): CSOE037CSOE037 Library: Library: EGLPOTEGLPOT location (type): iseriesd.dfw.ibm.comiseriesd.dfw.ibm.com luwControl (select): SERVERSERVER remoteBind: GENERATIONGENERATION remoteComType (select): JAVA400JAVA400 remotePgmType (select): EXTERNALLYDEFINEDEXTERNALLYDEFINED

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

9

Add to the Build File’s Linkage Option – 2 of 2

From Project Explorer, Right-Click over EGLWeb.eglbld and select: Open with Text editorOpen with Text editor Scroll down to the line <remoteCall pgmName=“RPG1”… Click your mouse at the beginning of the line (to set focus) Press Shift/End – to select the entire line (see reverse video line 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 pgmName’s and Alias’ in the new lines to:

RPG2RPG2 RPGCLSP2RPGCLSP2

RPG3RPG3 RPGCLSP3RPGCLSP3

RPG4RPG4 RPGZIPCKRPGZIPCK

Close and save your editsClose and save your edits

10

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

11

3. Create a New Page to Test Your RPG 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: callRPG.jspcallRPG.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 RPG programs are included as comments at the

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

12

3. EGL RPG Program Calls

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

Passing individual parameters to RPGPassing individual parameters to RPG 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

13

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

(callRPG1, callRPG2 and callRPG3)) functions, and drag them onto the page, to create three submit buttons.

You can optionally add HTML Horizontal Rule tags between the

controls

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

Input Text type Make ShipCostShipCost outputTextoutputText

14

Run the Page – and Call RPG

Run the page on the server. Enter the values shown below – and click the buttons.

Note that callRPG2 passes the same data (just using a fixed record instead of individual parms) Note also that you must fill in the input values in the array and click callRPG3 to return the 4 ShipCosts

***Notes***Notes

15

Course

The EGL Programming Model – Terms/ConceptsThe EGL Programming Model – Terms/Concepts

EGL Data Parts and Assignment Statements

EGL Conditional and Looping Statements

The EGL Built-in Functions and Date Math

EGL/SQL and Data Access Programming

EGL and Services (SOA)

Calling External Languages from EGL

EGL and Batch ApplicationsEGL and Batch Applications

Appendices

Topics:

RBD/EGL ProgrammingRBD/EGL Programming

16

Unit

Batch ProcessingBatch Processing

Reports using EGL

TUI Reports

BIRT Reports

Other Batch Processing Patterns

Reading and Writing to External Files

Master File Update

Topics:

EGL and Batch ApplicationsEGL and Batch Applications

17

EGL and Batch ProcessingBecause it is a fully-operational procedural language, EGL can be used effectively for Batch processing, which includes

the following use cases:

1.1. Report programsReport programs

2.2. File read/writeFile read/write

3.3. Master file updateMaster file update

4.4. Match-merge logicMatch-merge logic

All of these EGL use cases, include the following elements: EGL program part – as the main or entry-point into your business logic. Programs, in turn, could invoke EGL program part – as the main or entry-point into your business logic. Programs, in turn, could invoke

libraries, services, etc. The programs use a combination of EGL Record types, and data access language libraries, services, etc. The programs use a combination of EGL Record types, and data access language abstractions (get/add/etc.)abstractions (get/add/etc.)

Build-file customization – with specifications of Build-file customization – with specifications of J2EE: NOJ2EE: NO System – set for either Java or COBOL GenerationSystem – set for either Java or COBOL Generation ResourceAssociationResourceAssociation entriesentries

The input and output files and databasesThe input and output files and databases

InputSequential

File

OutputSequential

File

EGL Program……Record type serialRecord

Build File

ResourceAssociationFile Elements

Output Report

RelationalDatabase

18

Use Case #1 – Simple File Read/Write ProgramsYou’ve already finished (we hope) a simple sequential file access program (fileWriter.egl) – so you should be familiar with all of the technical elements

Which include: For each input/output file (that is not a relational or IMS database):

Define the Resource Association / Add File element(s), for the file in the Build-File Define the EGL Record type associated with file:

serialRecord – Sequential/QSAM files CSVRecord – Excel spreadsheet files IndexedRecord – VSAM files relativeRecord – VSAM files MQRecord – WebSphere MQ files

(typically) Fixed-length structure records Use char(xxx) not String datatypes

Code the EGL I/O statements (see next slide for more details) ADD – Insert records Get/Get Next/etc. – Read records Replace/Delete – for VSAM file update processing

Code the EGL business logic Generate Test:

Using EGL program debug – if JavaGeneration On the mainframe – if COBOL Generation

Please return in this PowerPoint to the slide titled: Sequential File I/O - Using a Program to Write to a Sequential File – if you want to review these steps with the fileWriter.egl program

19

EGL Traditional (non-RBDMS) File Access Verbs

These are the data access abstractions available (Operation) shown relative to the record types of the various external files. Note that CSVRecords behave like Serial records.

20

Use Case #2 – EGL Control Break Logic Program – 1 of 2

You may wish to use EGL to write control-break style print reports.

Here is a working example (the code is in the slide ***Notes) of a batch report program that: Reads all customer records (ordered by State), and formats a control break report when the state changes

It follows standard or traditional control break processing algorithms, with: A generic output record Several different header records A detail record A single “hold area” that controls when to “break” between states

You will need to: Add an entry to your Resource Associations for your batch build

file, for an output file with the logical name of: resres (see the fileName= property of the serialRecord declaration)

Create a new EGL program, named: reportProgram Generate the program Debug or run to see the results (next slide)

21

Use Case #2 – EGL Control Break Logic Program

When you run, your report will look something like the following…

22

Use Case #3 – EGL Master File Update Logic

You may decide to use EGL to write “master-file” update logic – where a “transaction file” is read one record at a time, values are accumulated and then applied against a Master file – which could be a new sequential file, an existing VSAM file, DL/I database or DB2 table.

Here is a working example (the code is in the slide ***Notes) of a program that: Reads a Payroll file, uses a employee-number value in each record to find a matching DB2 (“master-file”) table row (from the Employee table), then determines if the employees Salary data should be added to/or deducted from and then updates the row.

It follows standard or traditional master-file update logic processing algorithms, with a Payroll (transaction) file – which we are supplying you with in the ***Notes

You will need to: Create the payRoll file Create a batch build file that utilizes the DB2 SAMPLE DB2 SAMPLE

databasedatabase – note that we have included a text-based entry for that in the slide ***Notes***Notes – note that our example contains the resourceAssociation entry for c:\payData.dat

Change the name of the table schema (currently: jsayles) to your ID

Create a batch EGL program named: masterFileUpdateProgram

Associate this program with the batch/DB2 build file Generate, Debug or run View the changes to the SAMPLE database/Employee table