The EntireX RPC Server under i5/OS enables you to call programs as servers, using ILE (Integrated Language Environment).
Note:
The EntireX RPC Server installation also includes sample programs
that demonstrate how to build and use an RPC Client environment on i5/OS. For
details, see the section Installation
Verification and the document
Using EntireX COBOL Wrapper.
This document describes how to install the RPC Server under i5/OS.
It covers the following topics:
See EntireX Platform Coverage for full platform information.
The Prerequisites for installing the RPC Server are described centrally.
The implementation under i5/OS is based on the UNIX code, therefore, use the UNIX parameters for the i5/OS environment, see Setting up a Broker under UNIX; however, some features provided under UNIX are not supported under i5/OS, see Features Currently not Supported.
Secure Sockets Layer (SSL) is not supported.
Locations Transparency is not supported.
Note:
vrsp stands for the current version,
release, system maintenance level and optionally a patch level.
Installation comprises the following steps:
A successful Broker ACI installation on your i5/OS is a prerequisite to install the RPC Server. Software AG recommends you to keep the RPC Server environment in the i5/OS library EXX, in which your Broker ACI was installed.
If this library does not yet exist, create it with the i5/OS command CRTLIB EXX.
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 i5/OS disk
Use the i5/OS command CRTSAVF to create an empty i5/OS *SAVF file, named EXP vrsp, on your AS/400 or iSeries 400 machine in a library of your choice.
Use FTP to transfer the unzipped PC file EXP vrsp to the corresponding i5/OS save file using the FTP option "binary".
To verify the contents of the *SAVF file
EXPvrsp
Use the i5/OS command DSPSAVF. The command should display the following objects:
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 i5/OS is now installed and ready to use.
The verification is based on the EntireX RPC calculation example CALC in the IDL file example.idl, which is common for all platforms. The i5/OS 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:
Note:
RPG source examples are currently not provided for the installation
verification.
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.
Before you can begin the verification, you must restore the i5/OS library EXAMPLE from the save file EXAMPLE that you downloaded to library EXX during the Installation Step 4.
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 | 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 | 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 C Server | ||||||||||||||||
| BIND_CALC | *PGM | COBOL Server | Procedure to compile and bind the COBOL Server | ||||||||||||||||
| BIND_CCALC | *PGM | 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 Server | Procedure to start the EntireX RPC Server | ||||||||||||||||
| X_DEXAMPLE | *SRVPGM | C Server | C Server generated stub service. To use it, rename to DEXAMPLE | ||||||||||||||||
| X_EXAMPLE | *SRVPGM | C Server | 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 | COBOL Client dialog screen | ||||||||||||||||
| CALC | *MODULE | COBOL Client | COBOL Server calculation engine | ||||||||||||||||
| QCBLLESRC | *FILE (PF-SRC) | all COBOL |
|
||||||||||||||||
| *FILE (PF-SRC) | all |
|
|||||||||||||||||
| QCSRC | *FILE (PF-SRC) | all C |
|
||||||||||||||||
| H | *FILE (PF-SRC) | all C | C header files. It contains the generated stub header CEXAMPLE.h | ||||||||||||||||
| QRPGLESRC | *FILE (PF-SRC) | all RPG |
|
||||||||||||||||
In your EntireX network environment, the RPC server program CALC must be available for calculating figures. Examples of a CALC server program are provide in C and in COBOL. You can also access the sample CALC programs installed on your i5/OS computer as described in Step 3 and Step 4 further down in this section.
To verify the COBOL Client
Add the sample library EXAMPLE to your library list
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
|
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 copy book |
| 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.
Note:
Program CALCCLIENT expects the server program CALC to be located in
a library named EXAMPLE (as specified in the client stub CCALC). If your CALC
program is located in a different library, you must adjust member
EXAMPLE/QCBLLESRC(CCALC). Modify all occurrences of the string "EXAMPLE" to
your library name and adapt the associated string length. Then compile and
rebind the CALCCLIENT program.
To verify the RPC Server under i5/OS, 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
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.
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 because of
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.
Using the i5/OS command WRKACTJOB, you should find a job named RPCSERVER in your active-job list. To monitor your server, you can also start the EntireX Control Center on a Windows PC. To do so, logon to the Broker that you specified in Step 1. A service named SRV1 should be listed.
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 i5/OS sample CALCCLIENT from your i5/OS as described in Step 2, Verifying 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 the section Administration of the EntireX RPC Server under i5/OS.
To terminate the RPC Server, select the SRV1 service on the EntireX Control Center and confirm the "Shutdown".
To verify the server sample written in C
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.
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 because of
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.
Using the i5/OS command WRKACTJOB, you should find a job named "RPCSERVER" in your active-job list. To monitor your server, you can also start the EntireX Control Center on a Windows PC. To do so, logon to the Broker that you specified in Step 1. A service named SRV1 should be listed.
Rename the C stub X_DEXAMPLE to DEXAMPLE and the C application X_EXAMPLE to EXAMPLE.
Note:
Under i5/OS, a service program of type *SRVPGM is equivalent to
the UNIX term "shared library".
For more details on the naming convention of servers and stubs written in C, see the section Using EntireX C Wrapper.
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 stub) and library which contains the program functions, e.g. CALC. In our sample case, library denotes EXAMPLE.
The section Administration of the EntireX RPC Server under i5/OS describes in detail how the RPC Server distinguishes between a shared library and a stubless COBOL or RPG program.
To terminate the RPC Server, select the SRV1 service on the EntireX Control Center and confirm the "Shutdown".
