This document covers the following topics:
Note:
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 CL. The sample server will be named SENDMESS. Using the IBM i command SNGPGMMSG (send program message), it sends a message to a given IBM i user and returns a confirmation to the RPC client.
This section tells you how to
Using the Designer on your PC, create a Software AG IDL file similar to the following:
Library 'EXAMPLE' Is Program 'SENDMESS' Is Define Data Parameter 1 UserID (A10) In 1 Message_Text (A70) In 1 Confirmation (A40) Out End-Define
Section Software AG IDL to CL Mapping describes how IDL data types are mapped to CL data items.
The server is implemented as an ILE CL program of type *PGM.
For our IDL example SENDMESS, the implemented server looks similar to the example below:
PGM PARM(&USER &MESSTEXT &CONFIRM) /*--------------------------------------------------------------------*/ DCL VAR(&USER) TYPE(*CHAR) LEN(10) /* the user ID */ DCL VAR(&MESSTEXT) TYPE(*CHAR) LEN(70) /* the text */ DCL VAR(&CONFIRM) TYPE(*CHAR) LEN(40) /* returned text */ /*--------------------------------------------------------------------*/ CHGVAR VAR(&CONFIRM) VALUE(' ') /* clean it */ SNDPGMMSG MSG(&MESSTEXT) TOUSR(&USER) MSGTYPE(*COMP) MONMSG MSGID(CPF0000) EXEC(GOTO CMDLBL(BAD)) CHGVAR VAR(&CONFIRM) + VALUE('Message sent to user' *BCAT &USER) GOTO CMDLBL(DONE) /* sending was ok */ /*---------------------------------------------------------------------*/ BAD: CHGVAR VAR(&CONFIRM) + VALUE('Message sending failed') DONE: ENDPGM
Because servers are running in a multithreaded environment, your application programs must be thread-safe. This implies that all commands and subprograms accessed in your servers must allow multithreads.
Compile the server source using the IBM i command
CRTBNDCL
(create bound CL program).
The following example procedure demonstrates how to compile and bind an ILE CL program:
PGM /* Compile and Bind a CL Server program */ /*------------------------------------------------------------------*/ DCL VAR(&MODNAME) TYPE(*CHAR) LEN(10) VALUE(SENDMESS) DCL VAR(&LIBL) TYPE(*CHAR) LEN(10) VALUE(EXAMPLE) DCL VAR(&SRCF) TYPE(*CHAR) LEN(10) VALUE(QCLSRC) DCL VAR(&OPTL) TYPE(*CHAR) LEN(10) VALUE(*NONE) DCL VAR(&DBGV) TYPE(*CHAR) LEN(10) VALUE(*ALL) /*------------------------------------------------------------------*/ MONMSG MSGID(CPF6801) EXEC(GOTO CMDLBL(DONE)) /* If PF12 is pressed */ CRTBNDCL ??PGM(&LIBL/&MODNAME) ??SRCFILE(&LIBL/&SRCF) + ??SRCMBR(&MODNAME) DFTACTGRP(*NO) + ACTGRP(*CALLER) OUTPUT(*PRINT) + OPTIMIZE(&OPTL) DBGVIEW(&DBGV) MONMSG MSGID(LNC9001) EXEC(GOTO CMDLBL(ERRXT)) GOTO CMDLBL(DONE) /*------------------------------------------------------------------*/ ERRXT: SNDPGMMSG MSG('MSG: Program Linkage Failed') DONE: RETURN ENDPGM
Important:
When linking/binding servers, the binding parameter
ACTGRP(*CALLER)
must be specified. This guarantees that
the server application runs in the same activation group as the calling RPC
Server.
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 a request that is based on the IDL program SENDMESS in the IDL library EXAMPLE, the ILE server program SENDMESS in the IBM i library EXAMPLE is executed. If no corresponding program can be found, the access will fail.
Note:
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.
To verify the server program SENDMESS
, 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 server 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.
Note:
When using the EntireX Adapter, use the Service Development perspective of the Software AG Designer for testing.
This section describes the specific mapping of Software AG IDL data types to the CL programming language. Please note also the remarks and hints on the Software AG IDL data types valid for all language bindings under section Software AG IDL File.
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 | CL Data Type | See Notes |
---|---|---|---|
An |
Alphanumeric | TYPE(*CHAR) LEN(n) |
|
P(n - p)[.p] |
Packed decimal | TYPE(*DEC) LEN(n [p]) |
1 |
See also the hints and restrictions valid for all language bindings under IDL Data Types.
Notes:
P10.2
corresponds to TYPE(*DEC) LEN(12 2)
Other IDL data types have no appropriate equivalent in the CL language.
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.
Arrays, Groups and Structures are not supported for the CL language.
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
.