1. ® 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. 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 Programs  Calling RPG Programs Sub-Topics: EGL and Remote Programs

3. 3 Calling 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 project 2. (For each RPG program to call) Add to the EGL Linkage Part for your Build File 3. Create the business logic to call the RPG Program First we will start with an overview of the system architecture and process  EGL Logic Part call program… call program…

4. 4 Calling RPG Programs - Overview call “myProgram” (parm1, parmN);  Calling a RPG, COBOL, CL, or other program on the System i from EGL is as simple as coding: call “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. 5 Calling RPG Programs – System Architecture JT400.JAR  Your EGL application calls RPG through a series of Qxxx system modules, via the JT400.JAR (Java) toolbox See ***Notes on calling an external RPG program and Firewalls. If calling COBOL on the i IfcallingRPGdirectly

6. 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. 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-INF  Lib folder.  Switch to the Resource perspective  Expand Web Content  WEB-INF  lib folder –Drag jt400.jar into this folder  Drag Here

8. 8  Add to the Build File’s Linkage Option – 1 of 2 EGLWeb  From Project Explorer, Open EGLWeb.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) part: From the externalPrograms part: Add  Click: Add In the CallLink Elements: RPG1  Name the program: RPG1 remoteCall  Type: remoteCall Enter the following properties:  Alias: RPGCLSP1 CSOE037  conversionTable (type): CSOE037  Library: EGLPOT iseriesd.dfw.ibm.com  location (type): iseriesd.dfw.ibm.com SERVER  luwControl (select): SERVER GENERATION  remoteBind: GENERATION JAVA400  remoteComType (select): JAVA400 EXTERNALLYDEFINED  remotePgmType (select): EXTERNALLYDEFINED  Close SaveClose/Save Build File  Close and Save your Linkage Options – and Close/Save the Build File

9. 9  Add to the Build File’s Linkage Option – 2 of 2 Open with Text editor  From Project Explorer, Right-Click over EGLWeb.eglbld and select: Open 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: RPG2RPGCLSP2 RPG2RPGCLSP2 RPG3RPGCLSP3 RPG4RPGZIPCK  Close and save your edits

10. 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. 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 Generate  Right-click over the \EGLSource\ folder and select Generate Now let’s create a page that calls your COBOL programs  Right-click over \WebContent\ and select, New > Web Page callRPG.jsp  Name the page: callRPG.jsp  Change the boiler-plate page heading text as shown here…  Right-click and edit the Page Code From 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. 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 RPG  Passing a single record  Passing a record that contains an array  Here are the record definitions (nothing new…hope you’re not disappointed ) Press Ctrl/S (save) your JSFHandler

13. 13 4. Create the Page Results From Page Designer: csRec  From Page Data – drag csRec 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 csRecArray  From Page Data – drag csRecArray onto the page   Make the first three columns Input Text type ShipCostoutputText  Make ShipCost outputText

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

15. 15 Course The EGL Programming Model – Terms/Concepts  The 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 Applications  Appendices Topics: RBD/EGL Programming

16. 16 Unit Batch Processing  Batch 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 Applications

17. 17 EGL and Batch Processing Because it is a fully-operational procedural language, EGL can be used effectively for Batch processing, which includes the following use cases: 1.Report programs 2.File read/write 3.Master file update 4.Match-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 libraries, services, etc. The programs use a combination of EGL Record types, and data access language abstractions (get/add/etc.)  Build-file customization – with specifications of  J2EE: NO  System – set for either Java or COBOL Generation  ResourceAssociation entries  The input and output files and databases Input Sequential File Output Sequential File EGL Program … Record type serialRecord Build File Resource Association File Elements Output Report Relational Database

18. 18 Use Case #1 – Simple File Read/Write Programs You’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. 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. 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: res  Add an entry to your Resource Associations for your batch build file, for an output file with the logical name of: res (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. 21 Use Case #2 – EGL Control Break Logic Program When you run, your report will look something like the following…

22. 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 DB2 SAMPLE database ***Notes  Create a batch build file that utilizes the DB2 SAMPLE database – note that we have included a text-based entry for that in the slide ***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