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:
  • The service project, which is a web project, includes the following components, which are used to develop the code that accesses the IBM® i program:
    • An external type, stereotype HostProgram, which includes function prototypes that mirror the signatures of functions in the IBM® i program of interest
    • EGL structured Record parts that are referenced by parameters and return values in the function prototypes
    • A deployment descriptor with an entry that includes the following details: a URI for accessing the service, a reference to the external type, and a set of connection parameters for accessing the program from IBM® WebSphere® Application Server or Apache Tomcat.
    • A Program Call Markup Language (PCML) file, as noted later.
  • The client project, which is a Rich UI project, includes the following components, which are used to develop the EGL Rich UI application that accesses the service:
    • An Interface part that is like the external type that is placed in the service project
    • A set of non-structured Record parts that are referenced by parameters and return values in the function prototypes of the Interface part. The fields in those Record parts are equivalent to the bottommost (leaf) fields in the structured Record parts
    • A deployment descriptor with an entry that accesses the service
Some IBM® i (non-EGL) host programs are stateful:
  • A stateful program retains information between invocations so that the user and program can participate in a multistep conversation.
  • When you provide access to a stateful host program and you set up the deployment descriptor of the web project that includes the external type, you must specify that the service is a REST service, not a SOAP service. To indicate that the host program is stateful, customize the deployment descriptor in the deployment descriptor editor by selecting the Stateful check box.
  • The stateful aspect of host-program access is made possible by a session cookie that is provided by the service. The cookie holds an identifier for the HTTP session. When you are working in Rich UI, you identify the session cookie when you declare a variable that is based on the Interface part.
  • After you invoke the service for the last time in your application, to release runtime resources, invoke the serviceLib.endStatefulServiceSession() function.
  • Note:
    Any code that requires HTTP session operations cannot run or be debugged unless the code is deployed on an application server.

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®: https://www.ibm.com/docs/en/rdfi/9.6.0?topic=deprecated-pcml-data-type-values-languages-web-components.

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)