Accessing IBM i programs as web services: overview

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 an application server that is compliant with Java™ EE.
  4. In the requester, code a call statement to access the IBM i code.
For detailed instructions, see “Accessing IBM i programs as web services: keystroke details.”
It is difficult to design the Record parts that will become the basis of the records that are used during service invocation. However, you can use the Rational® Developer for Power Systems Software™: RPG and COBOL Development Tools for IBM i. In that case, you can use a wizard to create content in two projects:
Some IBM i (non-EGL) host programs are stateful:

The HTTP session detail is retained on the service-access variable. The lifespan of the session of the requester depends on where the variable is declared. For example, if the variable is declared in a function invocation, the session of the requester lasts as long as the function is in scope. If the variable is declared on a library, the session of the requester is retained until the library goes out of scope. If you are accessing an EGL stateful REST service, declare the variable in such a way that the variable does not go out of scope prematurely.

Example: An external type that provide 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.

Data types in 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 technical-support representatives 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 the 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.

Data types in EGL record fields

The following table lists the corresponding data types in structured and non-structured records. You might need to update the 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