This document describes how to install the Broker stub under IBM i. It covers the following topics:
See Platform Coverage for full platform information.
The prerequisites for installing the stub are described centrally. See IBM i Prerequisites.
The implementation on 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 below.
Secure Sockets Layer (SSL) is currently not supported.
Note:
vrsp stands for the current version,
release, service pack, and optionally a patch level.
The installation comprises the following steps:
We recommend that you keep the EntireX Broker environment in an IBM i library named EXX.
If this library does not yet exist, create it with the IBM i command
CRTLIB EXX.
The product is delivered in a data set with the name
../OS400/EXAvrsp and is stored
on your EntireX installation DVD. The data set must be transferred to a
*SAVF file on your machine. To do this, use the
command CRTSAVF to create the empty save file EXAvrsp in a library of your
choice. Then use FTP to transfer the unzipped PC data set to the save file
using the FTP option "binary".
To verify the content of the *SAVF file EXAvrsp, use the command
DSPSAVF. This command will display the following objects:
| Object | Type | Description |
|---|---|---|
EXA |
*SRVPGM |
EntireX Broker ACI (stub). |
EXXZCOMP |
*SRVPGM |
EntireX Compression Version 7.1.1. |
TRANPOT |
*SRVPGM |
EntireX TCP/IP Transport Version 7.1.1. |
X_SECUEXIT |
*SRVPGM |
EntireX Security Version 7.1.1 (to use, rename it). See Using the Security Exit. |
ZLIB |
*SRVPGM |
zlib compression. |
BCOC, BCOCCBL, BCOCRPG |
*PGM |
Client example programs in C, COBOL and RPG. |
BCOS, BCOSCBL, BCOSRPG |
*PGM |
Server example programs in C, COBOL and RPG. |
EXABCOC |
*PGM |
Start BCOC client sample program (edit first; read the note
under Test Procedures).
|
EXABCOCSEC |
*PGM |
Start BCOC client sample program with Security (edit first;
read the note under Test Procedures).
|
EXABCOS |
*PGM |
Start BCOS server sample program (edit first; read the note
under Test Procedures).
|
EXABCOSSEC |
*PGM |
Start BCOS server sample program with Security (edit first;
read the note under Test Procedures).
|
CRT_CBLMOD |
*PGM |
Compile a COBOL source to an ILE module. |
CRT_CMOD |
*PGM |
Compile a C source to an ILE module. |
CRT_RPGMOD |
*PGM |
Compile an RPG source to an ILE module. |
EXABNDPGM |
*PGM |
Sample: Bind user main program with the EXA service program (the Broker ACI). |
EXASETENV |
*PGM |
Sample: Set environment variables for EXA. |
EXACRTLOG |
*PGM |
Create a physical LOG file. |
BCOC, BCOCCBL, BCOCRPG |
*MODULE |
Client example modules in C, COBOL and RPG. |
BCOS, BCOSCBL, BCOSRPG |
*MODULE |
Server example modules in C, COBOL and RPG. |
EXASRC |
*FILE (PF-SRC) |
Example source file (sample programs and procedures). |
H_EXA |
*FILE (PF-SRC) |
Include files for sample C programs. Rename to H before
use.
|
QCBLLESRC |
*FILE (PF-SRC) |
COBOL copybooks for sample COBOL programs. |
QRPGLESRC |
*FILE (PF-SRC) |
RPG copybooks for sample RPG programs. |
QSRVSRC |
*FILE (PF-SRC) |
Export definitions for data and procedures. |
To restore the *SAVF file use the command RSTLIB:
RSTLIB SAVLIB(EXAvrsp) DEV(*SAVF) SAVF(EXAvrsp) RSTLIB(EXX)
After you have restored the save file, the product library EXX should at least contain the objects listed in step 3.
Software AG recommends you not putting user objects in this library. Copy modified samples to the user libraries. CL samples mentioned here may change, therefore check all associated program objects for the latest version.
The EntireX Broker ACI for IBM i is now installed and ready to be bound to a user-developed application environment.
This package contains test programs (BCOS, BCOC) and example programs
for binding (LINKPGM).
There are two types of programs to test the connection to the remote Broker.
BCOS, BCOSCBL and BCOSRPG
These programs act as servers. When they have been registered with
the remote Broker, they wait for incoming calls from the client programs BCOC,
BCOCCBL and BCOCRPG, respectively, and respond immediately.
BCOC, BCOCCBL and BCOCRPG
These programs act as clients. They attach in non-conversational mode
to one service and send data to the registered server programs BCOS, BCOSCBL
and BCOSRPG, respectively.
The file EXASRC contains the sources of the programs listed above; they are available in C, COBOL (...CBL) and RPG (...RPG).
Prerequisite for the test is a running remote Broker. To proceed, you
need to know the Broker ID (brokerid), the port number (portno) and,
optionally, the API (ACI) version of your Broker kernel (APIversion).
In two interactive sessions, set the *CURLIB to library EXX.
Check that the log file in library EXX exists. If it does not exist,
create it using the example program EXACRTLOG.
In session 1, execute the command:
Call BCOS ('-b brokerid: portno ' '- APIversion ')
In session 2, execute the command:
Call BCOC ('-b brokerid: portno ' '- APIversion ')
The steps above use the C samples, the samples for COBOL and RPG (see the program names above) can be used with the same parameters. The COBOL and RPG samples have less screen output than the C sample.
With Broker Kernel API Version 6 and the Broker ID Localhost, the screen
output of BCOC will look similar to this:
CLIENT: ETB Version 2 CLIENT: Number of repeats (10) CLIENT: Broker ID Localhost:3930 CLIENT: Broker ID pcbal2:6099 CLIENT: Using default class ACLASS CLIENT: Using default server ASERVER CLIENT: Using default service ASERVICE CLIENT: Maximum stub ACI version: 7 CLIENT: Maximum kernel ACI version: 6 CLIENT: Kernel Version 6.2.1.00 Platform UNIX CLIENT: Using ACI version: 6 Request issued (9, 2037) Request issued (8, 2037) Request issued (7, 2037) Request issued (6, 2037) Request issued (5, 2037) Request issued (4, 2037) Request issued (3, 2037) Request issued (2, 2037) Request issued (1, 2037) Request issued (0, 2037) CLIENT: Test successfully performed Press ENTER to end terminal session.
The screen output of BCOS will look similar to this:
SERVER: ACI Version 6 SERVER: Number of repeats (10) SERVER: Broker ID Localhost:3930 SERVER: Using default class ACLASS SERVER: Using default server ASERVER SERVER: Using default service ASERVICE SERVER: Maximum stub ACI version: 7 SERVER: Maximum kernel ACI version: 6 SERVER: Kernel Version 6.2.1.00 Platform UNIX SERVER: Using ACI version: 6 Incoming data (2037, 9) Incoming data (2037, 8) Incoming data (2037, 7) Incoming data (2037, 6) Incoming data (2037, 5) Incoming data (2037, 4) Incoming data (2037, 3) Incoming data (2037, 2) Incoming data (2037, 1) Incoming data (2037, 0) SERVER: Test successfully performed Press ENTER to end terminal session.
If it does, the test with the remote Broker was successful.
To perform the test programs, you can also modify and use the sample procedures located in the source file EXASRC:
| Procedure | Description | Programs called. |
|---|---|---|
EXABCOC |
Client test procedure | BCOC, BCOCCBL,
BCOCRPG.
|
EXABCOCSEC |
Client test procedure with Security parameters | BCOC only.
|
EXABCOS |
Server test procedure | BCOS, BCOSCBL,
BCOSRPG.
|
EXABCOSSEC |
Server test procedure with Security parameters | BCOS only.
|
Note:
By default, all procedures call
the "C" flavor of the client and server programs, i.e. BCOC and
BCOS.
To call the relevant COBOL (BCOCCBL, BCOSCBL) or RPG (BCOCRPG, BCOSRPG)
programs, you must modify the procedures listed above accordingly. After having
adjusted the Broker ID, Broker Version and Security parameters, you must
compile the sources and bind the created modules to executable *PGM programs.
For compiling, use the procedure CRT_CMOD, CRT_CBLMOD or CRT_RPGMOD. For
binding, use the procedure EXABNDPGM.
All sample programs incorporate the ACI Broker control block definitions during compilation. The relevant include file and copybooks are located in:
| Include source file | Copy member | Description |
|---|---|---|
H |
ETBCDEF |
C ACI definitions for BCOS and BCOC.
|
ETBCINF |
Broker API definitions for Command/Info Services using C. See Broker Command and Information Services. |
|
QCBLLESRC |
COBDEF |
COBOL ACI definitions for BCOSCBL and BCOCCBL.
|
COBINF |
Broker API definitions for Command/Info Services using COBOL. See Broker Command and Information Services. |
|
QRPGLESRC |
RPGDEF |
RPG ACI definitions for BCOSRPG and BCOCRPG.
|
Make a backup of the existing version in library EXX.
Perform the steps listed in Installation Steps above.
All program and sample files in the library EXX will be replaced.
All application server programs that use the Broker stub (ACI) must be rebound with the server program EXA.
To perform this step, you can use the command CRTPGM (see CL example
EXABNDPGM).
Using command DSPPGMREF (Display Program Reference) you can
display the service programs that are currently referenced to your
application.
If you use Natural RPC, you must rebind the Natural Broker Wrapper
program NXWRAPPR located in your library NXWvrs.