Accessing IBM i programs as Web services

You can use EGL to expose the logic in an IBM® i called program or service program by way of an EGL external type. The EGL generator uses that external type to create an EGL REST or SOAP service so that an application that is acting as a service requester can access any of the following kinds of IBM i programs: rpgle, cbl, cblle, sqlrpgle, sqlcbl, and sqlcblle.
To access an IBM i program:
  1. Create an external type (type HostProgram)
  2. In the Services deployment section of the EGL deployment descriptor editor, select that external type and enter other appropriate information.
  3. Deploy the resulting Web service to a JEE-compliant application server.
It is difficult to design the Record parts that will become the basis of the records used during service invocation. However, if you use IBM Rational® Business Developer for i for SOA Construction, you can use a wizard to create content in two projects:
Some IBM i (non-EGL) host programs are stateful, as described here:

External type that provides access to an IBM i program

This example shows an external type that provides access to an IBM i program.
ExternalType GETREC type HostProgram {platformData=[@i5OSProgram{ programName="GETREC", 
                         programType=NATIVE, isServiceProgram=false, libraryName="*LIBL"}]}
   function GETREC(CUST CUSTa10, EOF char(1), COUNT decimal(2,0)){ hostName="GETREC"};
end
The platformData property accepts an array. In this example, the array has a single entry for the @i5OSProgram complex property. The property fields for @i5OSProgram are as follows:
programName
The name of the program on IBM i. The default is the name of the external type.
programType
Either EGL (for a program written in EGL) or native (for a program written in COBOL or RPG). The default is NATIVE.
isServiceProgram
A Boolean that indicates whether the program is an IBM i service program. The default is false.
libraryName
The IBM i library. The default is *LIBL.

The hostName property is available for a function prototype and identifies the name of the program function. The default is the name of the function prototype.

Correspondence in data types between IBM i and EGL record fields

The workbench converts the IBM i data types from the host source into a Program Call Markup Language (PCML) definition. The workbench then uses that definition to create the external type and records.

The PCML file is retained for two reasons. First, you can update the file for use as the input in subsequent runs of the wizard. For example, you might put together a PCML definition that corresponds to entry points in several programs; if you use that definition as an input file, the external type that is created by the wizard can reflect all the entry points. Second, IBM support personnel can use the retained PCML file as a debugging tool, if necessary.

The following table lists the corresponding data types in IBM i structured records and EGL structured records.

Table 1. Corresponding data types in IBM i structured records and EGL structured records
IBM i Rules EGL data type in the EGL external type
char charType = single byte CHAR (PCML length)
charType = double byte UNICODE (PCML length)
int 2 byte signed precision != 16, length=2 SMALLINT
2 byte unsigned precision = 16, length = 2 INT
4 byte signed precision != 32, length = 4 BIGINT
4 byte unsigned precision = 32, length = 4 BIGINT
8 byte signed length = 8 BIGINT
packed     DECIMAL (PCML length, PCML precision)
zone     NUM (PCML length, PCML precision)
float   length = 4 SMALLFLOAT
  length = 8 FLOAT
byte     HEX (PCML length * 2)

You might need to update workbench-created EGL record fields that correspond to IBM i types that are not supported by EGL or are not converted by PCML. Details about PCML are available in the online information center for IBM WebSphere Development Studio Client for iSeries®: http://publib.boulder.ibm.com/infocenter/iadthelp/v7r0/topic/com.ibm.etools.iseries.webtools.doc/topics/rdtcattr.html.

Some host structures do not have corresponding EGL types. Here is a COBOL example:
01 P1 PIC 9(5) USAGE BINARY.
01 P2.
       02 P2A PIC X(5) OCCURS 1 to 10 TIMES 
                       DEPENDING ON P1.

Correspondence in data type between equivalent EGL record fields

The following table lists the corresponding data types in structured and non-structured records. You might need to update workbench-created non-structured record fields that are of type HEX or INTERVAL.

Table 2. Corresponding data types in structured and non-structured records
Data Type in Structured Record Data Type in Non-Structured Record
BOOLEAN BOOLEAN
CHAR, DBCHAR, MBCHAR, STRING, UNICODE STRING
HEX HEX
DATE DATE
TIME TIME
TIMESTAMP TIMESTAMP
INTERVAL INTERVAL
DECIMAL, BIN(length), BIGINT, INT, MONEY, NUM, SMALLINT, SMALLFLOAT Corresponding numeric types
BIN(length, decimalPlaces) where decimalPlaces > 0 NUM(length, decimalPlaces)
NUMC(length, decimalPlaces) NUM(length, decimalPlaces)
PACF(length, decimalPlaces) NUM(length, decimalPlaces)

Feedback