This document covers the following topics:
The EntireX RPC Server for IBM i of EntireX version 7.1.1 running under IBM i (AS/400) is no longer supported. We strongly recommend using the new RPC Server for AS/400 or the EntireX Adapter. See also Connection Parameters for AS/400 Connections.
This section describes how to build a server application using the IBM i
ILE language RPG. The server will be named CALC_RPG. Its functionality and
implementation is based on the ILE COBOL server CALC as described in the
section Using the COBOL Wrapper.
The function CALC_RPG is a calculator that can add, subtract, multiply
and divide two binary values PIC S9(8) BINARY and return a
result.
This section tells you how to
The PLIST in the RPG program is a good source of type information for the interface when you create the Software AG IDL file:
... D OPERATOR S 1A D OPERAND_1 S 10I 0 D OPERAND_2 S 10I 0 D FCT_RESULT S 10I 0 * C *ENTRY PLIST C PARM OPERATOR C PARM OPERAND_1 C PARM OPERAND_2 C PARM FCT_RESULT ....
The assumption is made that the program is implemented in library
EXAMPLE. Convert the linkage section function above to Software AG IDL syntax as
follows:
Library 'EXAMPLE' Is Program 'CALC_RPG' Is Define Data Parameter 1 Operator (A1) In 1 Operand_1 (I4) In 1 Operand_2 (I4) In 1 Function_Result (I4) Out End-Define
Note:
A 10-digit RPG integer takes 4 bytes, so it must be mapped to an
(I4) IDL field definition.
For details on how IDL field definitions are mapped to RPG elementary field items, see Software AG IDL to RPG Mapping.
The server is implemented as an ILE RPG program of type *PGM.
For our IDL example CALC, the implemented server looks similar to the example below.
*-------------------------------------------------- * Member CALC_RPG * Description Calculation Engine. * * Author (c) Software AG * Platform OS/400 * * UUU YYYY-MM-DD History * HBA 2003-05-20 Created * *--------------- CALC Interface ------------------------------ D OPERATOR S 1A D OPERAND_1 S 10I 0 D OPERAND_2 S 10I 0 D FCT_RESULT S 10I 0 *------------------------------------------------------------- C *ENTRY PLIST C PARM OPERATOR C PARM OPERAND_1 C PARM OPERAND_2 C PARM FCT_RESULT C CLEAR FCT_RESULT * C SELECT C WHEN OPERATOR = '+' C EVAL FCT_RESULT = OPERAND_1 + OPERAND_2 C WHEN OPERATOR = '-' C EVAL FCT_RESULT = OPERAND_1 - OPERAND_2 C WHEN OPERATOR = '*' C EVAL FCT_RESULT = OPERAND_1 * OPERAND_2 C WHEN OPERATOR = '/' C IF OPERAND_2 <> *ZERO C EVAL FCT_RESULT = OPERAND_1 / OPERAND_2 C ENDIF C ENDSL * C PGM_EX TAG C MOVE *ON *INLR
Compile the server source using the IBM i command CRTRPGMOD (create
bound RPG module) and bind it as a dynamically callable program of type *PGM
using the command CRTPGM. Make sure your server fulfills all requirements to be callable by the IBM i host server.
As an alternative to the commands CRTRPGMOD and CRTPGM,
you can use the command CRTBNDRPG to compile and bind RPG sources in one step.
Name the resulting server program like the program name in the IDL file and put it in a library whose name corresponds to the library name in the IDL file.
If a client performs an RPC which is based on the IDL program CALC_RPG
in the IDL library EXAMPLE, the RPC Server for AS/400 or the EntireX Adapter (see Connection Parameters for AS/400 Connections) will dynamically try to
execute the ILE program CALC_RPG in the IBM i library EXAMPLE.
If no corresponding program can be found, the access fails.
To verify the server program CALC_RPG, use the EntireX IDL Tester when the RPC Server for AS/400 and EntireX Broker are used.
To verify the server
Confirm that an EntireX Broker and an RPC Server for AS/400 are available in your network.
Make sure the IBM i host is started on your IBM i machine.
Create a Software AG IDL File using the IDL Editor as described under Create the Client/Server Interface.
Start the IDL Tester using the IDL file created in step 3.
Note:
When using the EntireX Adapter, use the perspective of the Software AG Designer for testing.
This section describes the specific mapping of Software AG IDL data types, groups, arrays and structures to the RPG programming language. See also hints and restrictions on the Software AG IDL data types valid for all programming language bindings under IDL Data Types in the IDL Editor documentation..
The following topics are covered here:
In the table below, the following metasymbols and informal terms are used for the IDL.
The metasymbols "[" and "]" enclose optional lexical entities.
The informal term number (or in some cases number1.number2) is a sequence of numeric characters, for example 123.
| Software AG IDL | Description | RPG Data Type | See Notes |
|---|---|---|---|
Anumber |
Alphanumeric | numberA |
|
AV |
Alphanumeric variable length | not supported | |
AV[number] |
Alphanumeric variable length with maximum length |
numberA |
|
Bnumber |
Binary | numberB |
|
BV |
Binary variable length | not supported | |
BV[number] |
Binary variable length with maximum length |
numberB |
|
D |
Date | 8U |
1 |
F4 |
Floating point (small) | not supported | |
F8 |
Floating point (large) | not supported | |
I1 |
Integer (small) | 3I 0 |
|
I2 |
Integer (medium) | 5I 0 |
|
I4 |
Integer (large) | 10I 0 |
|
Knumber |
Kanji | numberA |
|
KV |
Kanji variable length | not supported | |
KV[number] |
Kanji variable length with maximum length |
numberA |
|
L |
Logical | not supported | |
Nnumber1[.number2] |
Unpacked decimal | number1S number2 |
3 |
NUnumber1[.number2] |
Unpacked decimal unsigned | number1S number2 |
3 |
Pnumber1[.number2] |
Packed decimal | number1P number2 |
3 |
PUnumber1[.number2] |
Packed decimal unsigned | number1P number2 |
3 |
T |
Time | 15U |
2 |
See also hints and restrictions on the Software AG IDL data types valid for all programming language bindings under IDL Data Types in the IDL Editor documentation.
Notes:
YYYYMMDD.
15U (unpacked
decimal unsigned). The value contained has the form YYYYMMDDHHIISST.
number1+number2) is 18.
This is lower than the maximum of 99 supported by EntireX.
See IDL Data Types.
If you connect two endpoints, the total number of digits used must be lower or equal than the maxima of both endpoints. For the supported total number of digits for endpoints, see the notes under data types N, NU, P and PU in section Mapping IDL Data Types to target language environment C | CL | COBOL | DCOM | .NET | Java | Natural | PL/I | RPG | XML.
Do not use the special characters '#', '$', '&', '+', '-', '.', '/' and '@' within names of programs and libraries in the IDL file. These characters are not allowed within names of server programs and libraries created on IBM i.
Fixed arrays within the Software AG IDL file are mapped to fixed RPG
tables. See the array-definition under Software AG IDL Grammar in the IDL Editor documentation
for the syntax on how to describe fixed arrays within the Software AG IDL file and
refer to fixed-bound-array-index.
Unbounded arrays without a maximum are not supported.
Groups within the Software AG IDL file are mapped to RPG tables.
See the group-parameter-definition under Software AG IDL Grammar in the IDL Editor documentation
for the syntax on how to describe groups within the Software AG IDL file.
Example
The following IDL definition shows a simple group structure:
Library 'EXAMPLE' Is
Program 'GROUP' Is
Define Data Parameter
1 MYGROUP
2 PART1 (A10) In Out
2 PART2 (A10) In Out
End-Define
The following source file excerpt from a sample RPG program named GROUP
shows the corresponding field definitions and the entry parameter list:
CL0N01Factor1+++++++Opcode&ExtFactor2+++++++Result++++++++Len++D+ * D MYGROUP DS D PART1 10 D PART2 10 * ************************************************ * C *ENTRY PLIST C PARM MYGROUP *
Structures within the Software AG IDL file are mapped to RPG tables like groups. See the structure definition for the syntax on how to describe structures within the Software AG IDL file.
The IDL syntax allows you to define parameters as IN parameters, OUT
parameters, or IN OUT parameters (which is the default if nothing is
specified). This direction specification is reflected in the stubless call of
the RPC Server as follows:
Direction attributes do not change the call interface because parameters are always treated as "called by reference".
Usage of direction attributes may be useful to reduce data traffic between RPC client and RPC server.
Parameters with the IN attribute are sent from the RPC client to the
RPC server.
Parameters with the OUT attribute are sent from the RPC server to the
RPC client.
Parameters with the IN and OUT attribute are sent from the RPC client
to the RPC server and then back to the RPC client.
Note that only the direction information of the top-level fields (Level 1) is relevant. Group fields always inherit the specification from their parent. A different specification is ignored.
See the attribute-list under Software AG IDL Grammar in the IDL Editor documentation for
the syntax on how to describe attributes within the Software AG IDL file and refer
to direction-attribute.