EGL and Remote Programs on IBM i

1© 2008 IBM Corporation

Topic

EGL Calls to Remote Programs (Overview)EGL Calls to Remote Programs (Overview)

Calling RPG program

Calling a CL program

Invoking a command

Calling a procedure in RPG Service Program

Getting a list of records from RPG program

Accessing a DataArea

Sub-Topics:

EGL and Remote Programs on IBM iEGL and Remote Programs on IBM i


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…


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


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 i5 on i5 module installation, and module installation, and on calling an external RPG on calling an external RPG program and Firewalls.program and Firewalls.

If calling COBOL on the iIf calling COBOL on the i

If If calling calling

RPG RPG DirectlyDirectly

remotePgmType:remotePgmType:StatelessStateless

or Stateful or Stateful


Topic

EGL Calls to Remote Programs (Overview)

Calling RPG programsCalling RPG programs

Calling CL program

Invoking a command



Accessing a Dataarea

Sub-Topics:



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


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


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.demos.ibm.comiseriesd.demos.ibm.com luwControl (select): SERVERSERVER remoteBind: GENERATIONGENERATION remoteComType (select): JAVA400JAVA400 remotePgmType (select): STATELESSSTATELESS

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

Note: if you specify remotePgmType stateless or stateful you will not need QEGL on IBM i



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


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


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


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


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


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


Topic


Calling RPG programs

Calling a CL programCalling a CL program

Invoking a command




Sub-Topics:



Here’s what you’ll do:The steps for calling a CL program are the same as for

calling an RPG program, but the linkage part needs to point the CL program


For this step, follow the instructions for calling an RPG program

Once for each CL 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:


Calling CL Programs – Steps

***Notes***Notes


Add to the Build File’s Linkage Option

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



From the externalPrograms part:part: Click: Add Add

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

Enter the following properties: Alias: (the CL program name is CLZIPCK,

therefore no alias entry is needed) conversionTable (type): CSOE037CSOE037 Library: Library: EGLPOTEGLPOT location (type): iseriesd.demos.ibm.comiseriesd.demos.ibm.com luwControl (select): SERVERSERVER remoteBind: GENERATIONGENERATION remoteComType (select): JAVA400JAVA400 remotePgmType (select): STATELESSSTATELESS

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

***Notes***Notes


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


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


Select and replace all of the boiler-plate code with the code in the Notes section of this slide Note that there is a bit of source code, as the CL program is included as comments at the bottom There is nothing complex in this code There is nothing complex in this code Press Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler



From Page Designer: From Page Data – drag the fieldsthe fields

1.1. StateAbrvStateAbrv2.2. zipCodezipCode3.3. Message Message

on to the page (see below) Make the top two fields input Make Message output From options, specify no Submit buttons (un-check)

From Page Data – select the (callBLZIPCHK)) function, and drag it onto the page, to create a submit button.


Run the Page – and Call CL

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


Topic




Invoking a commandInvoking a command




Sub-Topics:



Here’s what you’ll do:The steps for invoking commands on IBM i is similar as for

calling a program, but the linkage part needs to point theQCMDEXC program.



Once for a program to be called- Add an EGL Linkage Part for the QCMDEXC program

For each call to QCMDEXC- Code the logic to add the command string as a parameter and to call the QCMDEXC Program, from an EGL “client” logic part:


Invoking IBM i comands – Steps

***Notes***Notes



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



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

Name the program: COMANDONI COMANDONI Type: remoteCall remoteCall

Enter the following properties: Alias: QCMDEXC conversionTable (type): CSOE037CSOE037 Library: %LIBL%Library: %LIBL% location (type): iseriesd.demos.ibm.comiseriesd.demos.ibm.com luwControl (select): SERVERSERVER remoteBind: GENERATIONGENERATION remoteComType (select): JAVA400JAVA400 remotePgmType (select): STATEFULSTATEFUL

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


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


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


Select and replace all of the boiler-plate code with the code in the Notes section of this slide Note that there is a bit of source code, as the CL program is included as comments at the bottom There is nothing complex in this code There is nothing complex in this code We added a try and onException statement for exception handlingWe added a try and onException statement for exception handlingPress Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler



From Page Designer: From Page Data, drag: addthisaddthis on to the page

Make the field input From options, specify no Submit buttons (un-check)

From Page Data – select the invokeCMD()invokeCMD() function, and drag it onto the page to create a submit button.


Run the Page – and Call CL

Run the page on the server. Enter the values shown below – and click the button. Click the button again, to get the error message that the library already exists.

***Notes***Notes


Topic




Invoking a command

Calling a procedure in RPG Service ProgramCalling a procedure in RPG Service Program



Sub-Topics:



Invoking an RPG procedure in a Service Program – Steps

Here’s what you’ll do:The steps for invoking procedures are different than for

calling a program, no linkage part is need instead you will use a deployment descriptor instead.

No Call statement is needed instead you invoke the procedure like a function, the procedure interface is described in an EGL interface.



Once for each procedure to invoke- Add an EGL deployment descriptor entry

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

- Service- Interface- JSFHandler- Program- Library

***Notes***Notes



From Project Explorer, in the EGLSource folder: Open the .egldd file using the EGL Build Parts Editor

Select the Service Client Bindings Tab From the Service Bindings Configuration dialog

Click the ADD button Select the Native binding Radio button

On the Add Native Binding DialogEnEnter the following attributes: conversionTable (type): CSOE037CSOE037 Library: Library: EGLPOTEGLPOT location (type):

iseriesd.demos.ibm.comiseriesd.demos.ibm.com Userid(type): EGL4RPG Password(type): EGL4YOU

Press the Finish buttonPress the Finish button Close Close and Save Save your Deployment

Descriptor –


3. Create a New Page to Test Your Procedure invocation


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


Select and replace all of the boiler-plate code with the code in the Notes section of this slide Note that there is a bit of source code, as the RPG program is included as comments at the bottom There is nothing complex in this code There is nothing complex in this code Press Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler




1.1. CustnoiCustnoi2.2. FdbackFdbackon to the page Make the top field input Make fdback output From options, specify no Submit

buttons (un-check)

Make some space between the fieldsMake some space between the fields

From Page Data – select the gestcustproc()gestcustproc() function, and drag it onto the page, to create a submit button.

Insert 2 blank lines underneath the error messages

From Page data – Drag Drag Myds onto the page Myds onto the page


4. Create the Interface and record definition for procedure invocation

First create the record definition for the data to be returned Right-click over the \EGLSource\ folder and select New New Package Package

Package name: basicrecordsPackage name: basicrecords Right-click on package basicrecords and select New ->EGL source fileNew ->EGL source file

EGL source file name: custrpgrecordsEGL source file name: custrpgrecords

From inside the source file Select and replace all of the boiler-plate code with the code in the Notes section of this

slide

Before finishing the project you need to create the EGL interface Right-click over the \EGLSource\ folder and select New New Interface Interface

Package name: InterfacesPackage name: Interfaces EGL source file name: getdssol EGL source file name: getdssol

From inside the getdssol source file Select and replace all of the boiler-plate code with this code :

package Interfaces;import basicrecords.cstruc;// interfaceinterface getdssolfunction getrecord(custnoi char(7),myds cstruc, fdback char(20)) ;end


Run the Page – and invoke the RPG procedure

Run the page on the server. Enter the value for customer number shown below – and click the button.

***Notes***Notes


Topic




Invoking a command


Getting a list of records from RPG programGetting a list of records from RPG program


Sub-Topics:



Calling an RPG Program returning multiple records

Here’s what you’ll do:

One time step- The setup steps are the same as in the previous RPG samples

Things that make life easier- If you have external defined data structures that you use to exchange data between RPG and EGL, make sure to specify in the EGL workbench preferences for SQL character types to use EGL char type.

- The default string will not work when exchanging parameter data between EGL and RPG.

- Use the data access wizard to create the EGL record layout

This will create a dynamic record layout, you will need to change this to a fixed record by prefixing the column(field) with a level number

- Remember to add the JT400.jar file to your project



Create a new dynamic Web project named call_getrec

Change the linkage info in the .eglbld file

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

Enter the following properties: Alias: GETREC (or blank, since the program name

is the same) conversionTable (type): CSOE037CSOE037 Library: Library: EGLPOTEGLPOT location (type): iseriesd.demos.ibm.comiseriesd.demos.ibm.com luwControl (select): SERVERSERVER remoteBind: GENERATIONGENERATION remoteComType (select): JAVA400JAVA400 remotePgmType (select): STATEFUL (important, you depend on having a STATEFUL (important, you depend on having a

stateful RPG program that continues to read records from the table. stateful RPG program that continues to read records from the table. Close Close and Save Save your Linkage Options – and Close/Save Close/Save the Build File Build File


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


Now let’s create a page that calls your RPG programs Right-click over \WebContent\ and select, New > Web Page Name the page: getcust.jspgetcust.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 RPG program is included as comments at the bottom Details of the program calls are covered on the next slide


3. EGL RPG Program Calls

Like in the previous samples the call environment is not very complex.

The RPG program returns up to 10 records

Parameters are:1. A fixed array of fixed records2. A boolean variable eof that indicates whether we

have reached the last record. We use this to disable the push button that allows to get more records.

3. An integer value that returns the actual number of records read in the RPG program.

Records used1. Single record with a fixed array of records to pass as

parameter This has to be defined this way since EGL doesn’t have a concept of fixed arrays and RPG doesn’t understand dynamic arrays

2. Fixed record of the customer file3. A dynamic array of records that receives and stores

the records to be displayed on the page. This array custsubf acts similar to a subfile in the 5250 environment.

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



From Page Designer/From Page Data Drag custsubfcustsubf array on to the page Make all fields output

From Page Data - Actions Drag function getCustomerRecordsgetCustomerRecords onto the page Enhance the text on the button


Customizing button

To disable the button when at the end of file …from Page Designer:

Select the button go to properties and

select to show all attributes

From the list of properties

Find disabled Select the pulldown Select compute From the tree view Expand Data Select the eofeof

boolean Click Ok

Save and try


Run the Page – and call same RPG program a couple of times

Run the page on the server. Press the push button, the table will get filled Press the push button a couple of more times until it gets disabled


Topic




Invoking a command



Accessing a DataAreaAccessing a DataArea

Sub-Topics:



Accessing a DataArea on IBM i – Steps

Here’s what you’ll do:The steps for accessing a data area are as follows One time steps

As in the Call examples you will nee the jt400.jar file in your project In addition:

You will need to specify when you create the EGL project that you want to add capabilities to access IBM i resources (DataAreas or data queues). This is done in the New project wizard or in the project properties by checking the EGL with i5/OS objects supportEGL with i5/OS objects support checkbox .

this will put the 2 iseriesobjects packages in EGL source

-

For each dataarea, code the logic using the iseriesobjects package.

- from an EGL “client” logic part:- Service- Interface- JSFHandler- Program- Library


Specify system definitions and dataarea definitions

You use the record Systemdefinition to define:You use the record Systemdefinition to define: the location of the dataarea the location of the dataarea systeminfo.systemName = “iseriesd.demos.ibm.com" The userid to sign on to the IBM i system The userid to sign on to the IBM i system systeminfo.userId = “EGL4RPG"; The password to sign on to the IBM i system The password to sign on to the IBM i system systeminfo.password = EGL4YOU";

You use record DataAreaDefinition to define:You use record DataAreaDefinition to define: Areaname Areaname dataarea1.areaname ="QESTELE"; Libname Libname dataarea1.libname ="QUSRSYS"; NoBytes NoBytes dataarea1.noBytes = 200; Areatype , one of these: Char, numeric, or logical Areatype , one of these: Char, numeric, or logical

DATA_AREA_TYPE_CHAR DATA_AREA_TYPE_DEC

DATA_AREA_TYPE_LOG dataarea1.areaType = iJavalib.DATA_AREA_TYPE_CHAR;

systemDef (from above) systemDef (from above)

Access the dataarea by writng an assignment statementAccess the dataarea by writng an assignment statement

datacontent = iJavaLib.getDataArea(dataarea1); (Datacontent is of type string)(Datacontent is of type string)

***Notes***Notes


3. Create a New Page to Test the data area access

Create a new project with jsf support Create a new project eglDtaara Remember to specify EGL with i5/OS object support on the

EGL Settings wizard page

Now let’s create a page that writes to dataareas and reads from dataareas Right-click over \WebContent\ and select, New > Web Page Name the page: eglDtaara.jsptaara.jsp Change the boiler-plate page heading text as shown here…


Select and replace all of the boiler-plate code with the code in the Notes section of this slide Note that there is a bit of source code, as the RPG program is

included as comments at the bottom There is nothing complex in this code There is nothing complex in this code Press Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler




1.1. datacontentidatacontenti2.2. datadeccontentidatadeccontenti3.3. datalgleontentidatalgleontention to the page Make all fields input From options, specify no Submit buttons (un-

check) Make some space between the fieldsMake some space between the fields From Page Data – select the

(get_dataara_content)) function, and drag it onto the page, to create a submit button.

From Page Data – drag the fields

1. datacontento

2. datadeccontento

3. datalglcontento


Run the Page – and access the data area

Run the page on the server. Press the button, Change the values and press the button.


Topic



Calling CL program

Invoking a command




Accessing members in database files Accessing members in database files

Sub-Topics:



Accessing Members in Database Files How to access members in database files :How to access members in database files :

Create an SQL AliasCreate an SQL Alias Use an SQL statement in your EGL …or… Use SQL on i to create the alias

Alias is an Alias is an Example: SQL Alias create statement:Example: SQL Alias create statement:

CREATE ALIAS QLINK FOR WFLABXX/MYFILE(mymember)CREATE ALIAS QLINK FOR WFLABXX/MYFILE(mymember) SQL name also works WFLABXX.MYFILE(mymember)WFLABXX.MYFILE(mymember)

Alias will show in RSE as well as OPS NavigatorAlias will show in RSE as well as OPS Navigator

Use SQL Select statement with Alias name•select * from WFLABXX/QLINK


Create Sample Application to Access Source Members

Create a new project with JSF supportCreate a new project: multimem1Change the project properties EGL Runtime Data Source

to a Data Source name that points to iseriesd.demos.ibm.com or your own system.

Now let’s create a page that allows to enter a member nameRight-click over \WebContent\\WebContent\ and select, New > Web PageName the page: lookatmember.jsp.jspChange the boiler-plate page heading text as shown here…

Right-click and edit the Page Code

From inside the JSFHandlerSelect and replace all of the boiler-plate code with the code in the Notes section of this

slideThere is nothing complex in this code There is nothing complex in this code Press Ctrl/S (save) your JSFHandlerPress Ctrl/S (save) your JSFHandler



From Page Designer: From Page Data – drag the fieldthe field

membernamemembername - - on to the page Make all fields input From options, specify no Submit buttons (un-

check)

Make some space between the fieldsMake some space between the fields

From Page Data/Actions select the getNewMember()getNewMember() function, and drag it onto the page, to create a submit button.

From Page Data – drag the fields

qddsqdds - onto the page


Run the Page – and look at members

Run the page on the server.

Press the button, You can see

source in member QDSIGNON2

Switch to the other member the is by default in QDDSSRC QDSIGNON


Some Notes for accessing DB2 on i

In the jdbc data source for your EAR file properties:Specify these properties:

dateformat : iso timeformat: iso

For working with the library list, use Naming: system

Setting a date to 0001-01-01Assign an EGL date variable value to: “01/01/0001” ; use double-quotes Or assign NULL to Null out the date field:

– dateVar date? = nulldateVar date? = null;

EGL and Remote Programs on IBM i

Documents

Transcript of EGL and Remote Programs on IBM i