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:
- Create an external type (type HostProgram)
- In the Services deployment section of the EGL deployment descriptor
editor, select that external type and enter other appropriate information.
- 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:
- The service project (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 (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 similar to the external type 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, as described here:
- 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.
- Access of a stateful program is available to a Rich UI application
but not to other EGL-generated code.
- The stateful aspect of host-program access is made possible by
a session cookie that is provided by the service to the EGL Rich UI
Proxy. The cookie holds an identifier for the HTTP session. You identify
the session cookie when you declare a variable that is based on the
Interface part.
- The EGL Rich UI Proxy retains the session ID in between service
invocations. After you invoke the service for the last time in your
application, to release runtime resources, invoke the serviceLib.endStatefulServiceSession() function.
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 recordsIBM 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 recordsData 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) |