The EntireX RPC Server for IBM i enables you to call server programs written in all ILE-based languages, for example C, COBOL, RPG. This document describes how to install this (deprecated) RPC server under IBM i and covers the following topics:

• Features Currently not Supported

• Installation Steps

• Installation Verification

See Platform Coverage for full platform information.

The implementation under IBM i is based on the UNIX code, therefore, use the UNIX parameters for the IBM i environment, see Setting up Broker Instances. However, some features provided under UNIX are not supported under IBM i, see Features Currently not Supported.

---

Features Currently not Supported

Secure Sockets Layer (SSL) is not supported with this deprecated RPC server. For SSL transport we recommend using the new RPC Server for AS/400 instead. See Using SSL/TLS with the RPC Server in the RPC Server for AS/400 documentation.

Installation Steps

Installation comprises the following steps:

• Step 1: Check the Product Library

• Step 2: Copy the Installation Kit to Disk

• Step 3: Verify the Contents of the *SAVF File

• Step 4: Restore the *SAVF File

Step 1: Check the Product Library

A successful Broker ACI installation on your IBM i machine is a prerequisite to install the RPC server. Software AG recommends you to keep the RPC server environment in the library EXX, in which your Broker ACI was installed.

If this library does not yet exist, create it with the command CRTLIB EXX.

Step 2: Copy the Installation Kit to Disk

The product is delivered in a data set with the name ../OS400/EXPvrsp on your EntireX installation DVD.

To copy the installation file to your IBM i disk

1. Use the command CRTSAVF to create an empty IBM i *SAVF file, named EXP vrsp, on your IBM i machine in a library of your choice.

2. Use FTP to transfer the unzipped PC file EXP vrsp to the corresponding IBM i save file using the FTP option "binary".

Step 3: Verify the Contents of the *SAVF File

To verify the contents of the *SAVF file EXPvrsp

• Use the IBM i command DSPSAVF. The command should display the following objects:

Object	Type	Description
XSERVER	*PGM	RPC server program.
STR_RPCSRV	*PGM	Sample RPC server starting procedure.
EXPCRTLOG	*PGM	Sample procedure to create the physical log file.
EXPRUNTIME	*SRVPGM	RPC server runtime module.
EXPMSG	*MSG	EntireX Messages.
H_EXP	*FILE (PF-SRC)	Header include files for sample C programs. Rename to H before use.
QCLSRC	*FILE (PF-SRC)	Sources of build procedures . Member Description SERVER_CFG RPC server configuration to be used by the server startup procedure. STR_RPCSRV Sample procedure to submit/start an RPC server. EXPCRTLOG Procedure to create the physical log file.
EXAMPLE	*SAVF	Save file containing RPC server and RPC client examples.

Step 4: Restore the *SAVF File

To restore the *SAVF file

• Use the command RSTLIB:

RSTLIB SAVLIB(EXPvrsp) DEV(*SAVF) SAVF(yoursavlib/EXPvrsp) RSTLIB(EXX)

where yoursavlib denotes the library into which you transferred the save file during Step 2.

In addition to the Broker ACI installation, the product library EXX should now contain the objects listed in Step 3.

Software AG recommends you not having user objects in this library. Copy modified samples to the user libraries. Source samples mentioned here may change, therefore check all associated program objects for the latest version.

The EntireX RPC server for IBM i is now installed and ready to use.

Installation Verification

The verification is based on the EntireX RPC calculation example CALC in the IDL file example.idl, which is common for all platforms. The IBM i library EXAMPLE provides programs that allow you to test a COBOL RPC client and to run the RPC server with a COBOL or a C application service.

The verification comprises the following steps:

• Step 1: Restore the EXAMPLE Library

• Step 2: Verify the RPC COBOL Client

• Step 3: Verify the RPC Server using COBOL

• Step 4: Verify the RPC Server using C

Prerequisite for all verifications:

The service program EXA (type *SRVPGM, the Broker ACI/stub) must be available in your library list. You can accomplish this task by adding EXX, where the Broker ACI and the RPC server are usually installed, to your library list.

Step 1: Restore the EXAMPLE Library

Before you can begin the verification, you must restore the IBM i library EXAMPLE from the save file EXAMPLE that you downloaded to library EXX during Step 3.

To restore the *SAVF example file, use the command RSTLIB:

RSTLIB SAVLIB(EXAMPLE) DEV(*SAVF) SAVF(EXX/EXAMPLE) RSTLIB(EXAMPLE)

The newly created library EXAMPLE should contain the following objects:

Object	Type	Used by example	Description
CALC	*PGM	COBOL server, see Step 3: Verify the RPC Server using COBOL	COBOL server calculation engine (created with BIND_CALC).
CALC_RPG	*PGM	RPC server	RPG Server calculation engine (created with BIND_RCALC).
CALCCLIENT	*PGM	COBOL client, see Step 2: Verify the RPC COBOL Client	COBOL client calculation dialog (created with BINDCCALC). Contains the modules CCALCMAIN, CCALCMENU, CCALC and RPCSRVI.
CRT_CBLMOD	*PGM	all COBOL	Procedure to compile/create COBOL modules.
CRT_C_SRV	*PGM	all C	Procedure to create modules and service programs of DEXAMPLE and EXAMPLE for the RPC Server for C. It demonstrates how to compile the interface object (for example DEXAMPLE in our sample), compile a server (for example EXAMPLE in our sample)
BIND_CALC	*PGM	COBOL server, see Step 3: Verify the RPC Server using COBOL	Procedure to compile and bind the COBOL server.
BIND_CCALC	*PGM	COBOL client, see Step 2: Verify the RPC COBOL Client	Procedure to compile and bind the COBOL client.
BIND_RCALC	*PGM	RPG Server	Procedure to compile and bind the RPG Server.
STR_RPCSRV	*PGM	all servers	Procedure to start the EntireX RPC server.
X_DEXAMPLE	*SRVPGM	C Server, see COBOL client, see Step 4: Verify the RPC Server using C	C Server interface object. To use it, rename to DEXAMPLE.
X_EXAMPLE	*SRVPGM	C Server, see COBOL client, see Step 4: Verify the RPC Server using C	C Server implementation file. This service contains the application logic of the programs CALC, HELLO and POWER. To use it, rename to EXAMPLE.
CCALCMENU	*FILE (DSPF)	COBOL client, see Step 2: Verify the RPC COBOL Client	COBOL client dialog screen.
CALC	*MODULE	COBOL client, see Step 2: Verify the RPC COBOL Client	COBOL server calculation engine.
QCBLLESRC	*FILE (PF-SRC)	all COBOL	COBOL sources for Client and Server. Member Description CALC COBOL server calculation engine. CCALCMENU COBOL client display file. CCALCMAIN COBOL client dialog program. CCALC COBOL client stub derived from CobolClient1.tpl. RPCSRVI COBOL client Broker Service derived from CobolClient2.tpl. ERXCOMM RPC Communication Area copybook to be copied by CALCMAIN, CCALC and RPCSRVI.
	*FILE (PF-SRC)	all	CL procedures for compiling, binding and building. Member Description BIND_CALC Procedure to compile and bind the COBOL server. BIND_CCALC Procedure to compile and bind all COBOL client modules. BIND_RCALC Procedure to compile and bind the RPG server. CRT_C_SRV Procedure to create modules and service programs of DEXAMPLE and EXAMPLE for the C server. CRT_CBLMOD Compile COBOL modules.
QCSRC	*FILE (PF-SRC)	all C	Sources for C Server. Member Description DEXAMPLE Server interface object for C Server. EXAMPLE C server implementation file.
H	*FILE (PF-SRC)	all C	C header files. It contains the generated header CEXAMPLE.h.
QRPGLESRC	*FILE (PF-SRC)	all RPG	RPG sources for server. Member Description CALC_RPG RPG server calculation engine.

Step 2: Verify the RPC COBOL Client

In your EntireX network environment, the RPC server program CALC must be available for calculating figures. Examples of a CALC server program are provided in COBOL. You can also access the sample CALC programs installed on your IBM i computer as described in Step 3 and Step 4 below.

To verify the COBOL client

1. Add the sample library EXAMPLE to your library list.

2. Call program CALCCLIENT.

   A menu similar to the following will be displayed:

   Calculator Menu                                       
   ----------------------------------------------------- 
                                                         
   Operation: + (type + - * / to calculate or 
                            type .       to terminate)   
   Operand 1:    _____                                        
                                                         
   Operand 2:    _____                                            
                                                         
   Result:  ___________                                             
                                                         
                                                         
   Broker-ID: localhost:1971    Server: SRV1

3. Specify the ID of the remote Broker and the name of the server that provides the CALC program. Specify the figures you want to compute and press Enter. If the Broker connection fails, you will receive an appropriate error message.

The following modules/files are bound to program CALCCLIENT:

Object	Description
CCALCMAIN	The main program logic.
CCALCMENU	The menu display file.
CCALC	The client stub derived from CobolClient1.tpl.
RPCSRVI	The client runtime derived from CobolClient2.tpl.
ERXCOMM	RPC communication area copybook.
EXA	The Broker ACI (stub).

All sources are located in the file EXAMPLE/QCBLLESRC.

Use the procedure BIND_CCALC to recompile and rebind the modules.

Step 3: Verify the RPC Server using COBOL

To verify the RPC server under IBM i, you can use the COBOL server program CALC located in library EXAMPLE. When requested by a client process, it provides the four basic arithmetic operations addition, subtraction, multiplication and devision.

To verify the Server sample written in COBOL

1. Edit the RPC server configuration file EXAMPLE/QCLSRC(RPCSRV_CFG).

   You must at least modify the BrokerID=Localhost:1971 of the remote Broker where you want to register your server and the ServerName=SRV1 that identifies your service.

2. Start the procedure EXAMPLE/STR_RPCSRV. It will submit the RPC server named XSERVER to a batch queue.

   If you want to extend the SBMJOB parameters, you can modify/recompile the procedure EXAMPLE/QCLSRC(STR_RPCSRV).

   Note:
   The RPC server can only be started as a batch job for multithreading reasons. ALWMLTTHD=*YES is a very important parameter for allowing multiple threads. The configuration file RPCSRV_CFG described in the previous step will be passed to the XSERVER.

3. Using the IBM i command WRKACTJOB, you should find a job named RPCSERVER in your active-job list.

4. Use a calculator client process to send a request to your server. As remote client you can run a Java test generated from the Workbench example.idl. Or run the IBM i sample CALCCLIENT from your IBM i machine as described in Step 2: Verify the RPC COBOL Client.

   The RPC server will find and access the COBOL based sample program CALC in your library EXAMPLE and pass the computed result back to the client. Server stubs are not required for application servers written in COBOL and RPG.

   For more details on the server access logic, see Administering the RPC Server.

Step 4: Verify the RPC Server using C

To verify the server sample written in C

1. Edit the RPC server configuration file EXAMPLE/QCLSRC(RPCSRV_CFG).

   You must at least modify the BrokerID=Localhost:1971 of the remote Broker where you want to register your server and the ServerName=SRV1 that identifies your service.

2. Start the procedure EXAMPLE/STR_RPCSRV. It will submit the RPC server named XSERVER to a batch queue.

   If you want to extend the SBMJOB parameters, you can modify/recompile the procedure EXAMPLE/QCLSRC(STR_RPCSRV).

   Note:
   The RPC server can only be started as a batch job for multithreading reasons. ALWMLTTHD=*YES is a very important parameter for allowing multiple threads. The configuration file RPCSRV_CFG described in the previous step will be passed to the XSERVER.

3. Using the IBM i command WRKACTJOB, you should find a job named "RPCSERVER" in your active-job list.

4. Rename the C server interface object X_DEXAMPLE to DEXAMPLE and the C application X_EXAMPLE to EXAMPLE.

   Note:
   under IBM i, a service program of type *SRVPGM is equivalent to the UNIX term "shared library".

   For more details on the naming convention of servers and interface objects written in C, see Using the C Wrapper.

5. Use a calculator client process to send a request to your server. As remote client you can run a Java test program generated from the Workbench example.idl.

   The RPC server will search for the shared libraries Dlibrary (the server interface object) and library which contains the program functions, e.g. CALC. In our sample case, library denotes EXAMPLE.

   The section Administering the RPC Server describes in detail how the RPC server distinguishes between calling a shared library with a server interface object and a COBOL or RPG program.