The EntireX IMS Connect RPC Server allows standard RPC clients to communicate with IMS MPP programs running on IMS version 9 and higher. The IMS Connect RPC Server transforms the RPCs from the clients into messages to IMS Connect v2.2. The IMS Connect RPC Server acts on one side as an RPC server and on the other side as a client for IMS Connect. The IMS Connect RPC Server is a Java-based component that can run on a different host to the one where IMS is running. This allows it to operate with a zero footprint of EntireX on the IMS host.
This document covers the following topics:
For the setup of the IMS Connect RPC Server there are
a configuration file and
scripts to start the IMS Connect RPC Server.
The IMS Connect RPC Server is contained in the file entirex.jar.
The default name of the configuration file is entirex.imsconnect.properties. The IMS Connect RPC Server searches for this file in the current working directory.
You can set the name of the configuration file with
-Dentirex.server.properties=<your file
name> with "/" as file separator.
The configuration file contains the configuration for both parts of the IMS Connect RPC Server.
To set up the IMS Connect RPC Server
Use the RPC server agent of the System Management Hub.
Add the IMS Connect RPC Server as an RPC server.
See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows for details.
Or:
Use the scripts to start the IMS Connect RPC Server.
Under Windows, use imsconnectserver.bat in the folder bin to start the IMS Connect RPC Server. You may customize this file.
Under UNIX, use imsconnectserver.bsh in the folder bin to start the IMS Connect RPC Server. You may customize this file.
Both scripts use the configuration file entirex.imsconnect.properties in the folder etc.
If you configure more than one IMS Connect RPC Server that connect to the same EntireX Broker, the following items must be distinct:
The trace output file (property
entirex.server.logfile).
The monitor port for SMH (property
entirex.server.monitorport).
The log for the Windows Service (property
entirex.server.serverlog).
The trace output file of the SMH agent for RPC servers.
The RPC server side of the IMS Connect RPC Server is configured like the Java RPC Server. The IMS Connect RPC Server uses the properties that start with "entirex.server".
The RPC server side can adjust the number of worker threads to the number
of parallel requests. Use the properties
entirex.server.fixedservers,
entirex.server.maxservers and
entirex.server.minservers to configure this
scalability.
If entirex.server.fixedservers=yes, the
number of entirex.server.minservers is started and
the server can process this number of parallel requests.
If entirex.server.fixedservers=no, the
number of worker threads balances between
entirex.server.minservers and
entirex.server.maxservers. This is done by a
so-called attach server thread. On startup, the number of worker threads is
entirex.server.minservers.
If more than entirex.server.minservers are
waiting for requests, a worker thread stops if its receive call times out. The
timeout period is configured with
entirex.server.waitserver.
Alternatively to the properties, you can use the command-line option. The command-line options have a higher priority than the properties set as Java system properties and these have higher priority than the properties in the configuration file.
| Name | Command-line Option | Default Value | Explanation | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entirex.bridge.verbose |
no |
Verbose/trace mode of IMS Connect RPC Server | |||||||||||||||
entirex.server.brokerid |
-broker |
localhost |
Broker ID | ||||||||||||||
entirex.server.serveraddress |
-server |
RPC/SRV1/CALLNAT |
Server address. | ||||||||||||||
entirex.server.userid |
-user |
IMSRPCServer |
The user ID for the Broker for RPC. See entirex.server.password. | ||||||||||||||
entirex.server.fixedservers |
no |
|
|||||||||||||||
entirex.server.minservers |
1 |
Minimum number of server threads. | |||||||||||||||
entirex.server.maxservers |
32 |
Maximum number of server threads. | |||||||||||||||
entirex.server.restartcycles |
-restartcycles |
15 |
Number of restart attempts if the Broker is not available. This can be used to keep the IMS Connect RPC Server running while the Broker is down for a short time. | ||||||||||||||
entirex.server.password |
-password |
The password for secured access to the Broker. The password is encrypted and written to the property entirex.server.password.e. To change the password, set the new password in the properties file (default is entirex.imsconnect.properties). To disable password encryption set entirex.server.passwordencrypt=no. Default for
this property is "yes".
|
|||||||||||||||
entirex.server.properties |
-propertyfile |
entirex.server.properties |
The file name of the property file. | ||||||||||||||
entirex.server.security |
-security |
no |
no|yes|auto|name of BrokerSecurity object
|
||||||||||||||
entirex.server.encryptionlevel |
0 |
Encryption level. Valid values: 0,1,2. | |||||||||||||||
entirex.server.compresslevel |
-compresslevel |
0 |
Permitted values (you can enter the text or the numeric value)
|
||||||||||||||
entirex.server.waitattach |
600S |
Wait timeout for the attach server thread. | |||||||||||||||
entirex.server.waitserver |
300S |
Wait timeout for the worker threads. | |||||||||||||||
entirex.timeout |
20 |
TCP/IP transport timeout. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI. | |||||||||||||||
entirex.server.verbose |
-verbose |
no |
Enable verbose output to the log file. | ||||||||||||||
entirex.server.logfile |
-logfile |
Name of the log file, the default is standard output. | |||||||||||||||
entirex.trace |
-trace |
0 |
Trace level (1,2,3). | ||||||||||||||
entirex.server.monitorport |
-smhport |
0 |
The port where the server listens for commands from the System Management Hub (SMH). If this port is 0, no port is used and management by the SMH is disabled. |
These properties are used to configure the connection to IMS Connect.
Alternatively, you can use the command-line option. The command-line options have a higher priority than the properties set as Java system properties and these have higher priority than the properties in the configuration file
| Name | Default Value | Explanation | ||||
|---|---|---|---|---|---|---|
ims.host |
Host name of IMS Connect. Mandatory. | |||||
ims.port |
Port number of IMS Connect. Mandatory. | |||||
ims.datastoreid |
Data store ID. Name of the IMS system that will receive transactions. Mandatory. | |||||
entirex.bridge.targetencoding |
cp037 |
Specify the appropriate EBCIDIC encoding used by your IMS Connect.
This codepage is also used when communicating with the EntireX Broker.
Note: Default "cp037" is EBCDIC codepage with full Latin-1 character set. |
||||
ims.useoldexit |
yes |
|
||||
ims.exitname |
*SAMPLE* (old exit)*SAMPL1* (new exit)
|
Name of IMS Connect user message exit. | ||||
ims.sockettimeout |
10000 |
Socket timeout for connection to IMS Connect (in milliseconds). | ||||
ims.checkdfs |
true |
|
||||
ims.clientid |
ID of the client that is used by IMS Connect. Maximum 8 bytes (optional). | |||||
ims.lterm |
IMS LTERM override. Maximum 8 bytes (optional).
|
|||||
ims.userid |
RACF user ID. Maximum 8 bytes (optional). | |||||
ims.groupid |
RACF group ID. Maximum 8 bytes (optional). | |||||
ims.password |
RACF password/PassTicket. Maximum 8 bytes (optional). | |||||
ims.applname |
RACF application name. Maximum 8 bytes (optional). | |||||
ims.sslparams |
SSL parameters (optional). Same syntax as Broker ID. | |||||
ims.mapping.folder |
The folder where the RPC server expects server-side mapping files
(EntireX Workbench files with extension .svm).
See Deploying Server-side Mapping Files to the RPC Server and Undeploying Server-side Mapping Files to the RPC Server.
There are also client-side mapping files that do not require configuration here. See Server Mapping Files for COBOL. If no server requires server-side mapping, you can omit this property. If one server requires server-side mapping, this property must be specified. |
|||||
ims.useprogramname |
false |
Automatically use the IDL program name as transaction name. If set to "true" or "yes", 10 bytes are used for the transaction name. If set to a number, this number of bytes is used for the transaction name. |
To start the IMS Connect RPC Server
Use the script imsconnectserver in the folder bin to start the IMS Connect RPC Server. You may customize this file.
Or:
Use the RPC server agent in the System Management Hub to
configure and start the IMS Connect RPC Server.
See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows for details.
To stop the IMS Connect RPC Server
Use the RPC server agent in the SMH to stop the IMS Connect RPC Server.
Or:
Use the agent for the Broker. Use
Deregister on the service, specified with the
property entirex.server.serveraddress.
The application identification is sent from the IMS Connect RPC Server to the Broker. It is visible with Broker Command and Info Services.
The identification consists of four parts: name, node, type, and version. These four parts are sent with each Broker call and are visible in the trace information.
For the IMS Connect RPC Server, these values are:
| Identification Part | Value |
|---|---|
| Application name | ANAME=IMS Connect RPC Server |
| Node name | ANODE=<host name> |
| Application type | ATYPE=Java |
| Version | AVERS=9.5.0.0 |
