The EntireX RPC Server for IMS Connect allows standard RPC clients to communicate with IMS MPP programs. It works together with the IDL Extractor for COBOL and transforms RPC requests from clients into message to IMS, using IMS Connect.
This document describes how to administer the RPC Server for IMS Connect with local scripts as in earlier versions of EntireX. It covers the following topics:
See also Administering the RPC Server for IMS Connect with the Command Central GUI | Command Line.
The following elements are used to set up the RPC Server for IMS Connect:
The default name of the configuration file is entirex.imsconnect.properties. The RPC Server for IMS Connect 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 RPC Server for IMS Connect.
If you configure more than one RPC Server for IMS Connect that connects to the same broker, the following items must be distinct:
the trace output file (property
entirex.server.logfile
)
the log for the Windows Service (property
entirex.server.serverlog
)
The start script for the RPC Server for IMS Connect is called imsconnectserver.bsh (UNIX) or imsconnectserver.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The RPC Server for IMS Connect itself is contained in the file entirex.jar.
The RPC Server for IMS Connect uses the properties that start with "entirex.server
" for configuring the RPC server side.
Alternatively to the properties, you can use the command-line options. These have a higher priority than the properties set as Java system properties, and these have higher priority than the properties in the configuration file.
Property Name | Command-line Option | Default | Explanation | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entirex.server.brokerid |
-broker |
localhost |
Broker ID. See URL-style Broker ID. | ||||||||||||||
entirex.server.serveraddress |
-server |
RPC/SRV1/CALLNAT |
Server address. | ||||||||||||||
entirex.server.userid |
-user |
IMSRPCServer |
The user ID for access to the broker. | ||||||||||||||
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 RPC Server for IMS Connect 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. To disable password encryption, set entirex.server.passwordencrypt=no .Default: 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.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. | |||||||||||||||
-help |
Display usage of the command-line parameters. | ||||||||||||||||
entirex.server.logfile |
-logfile |
Name of the log file, the default is standard output. | |||||||||||||||
entirex.trace |
-trace |
0 |
Trace level (1,2,3). |
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.
Enable character conversion in the broker by setting the service-specific attribute 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
(Designer files with extension .svm).
See Deploying Server-side Mapping Files to the RPC Server and Undeploying Server-side Mapping Files from 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 use SSL with the RPC Server for IMS Connect, you need to configure two sides:
IMS Connect Side
See parameter ims.sslparams
under Configuring the IMS Connect Side.
RPC Server Side
RPC servers can use Secure Sockets Layer/Transport Layer Security (SSL/TLS) as the transport medium.
The term "SSL" in this section refers to both SSL and TLS.
RPC-based servers are always SSL clients. The SSL server can be either the EntireX Broker or Broker SSL Agent. For an introduction
see SSL/TLS and Certificates with EntireX in the Platform-independent Administration documentation.
To use SSL
To operate with SSL, certificates need to be provided and maintained. Depending on the platform, Software AG provides default certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.
Set up the RPC Server for IMS Connect for an SSL connection.
Use the URL-style Broker ID with protocol ssl://
for the Broker ID. If no port number is specified, port 1958 is used as default. Example:
ssl://localhost:22101?trust_store=C:\SoftwareAG\EntireX\etc\ExxCACert.jks&verify_server=no
If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. The mandatory trust_store
parameter
specifies the file name of a keystore that must contain the list of trusted certificate authorities for the certificate of
the SSL server.
By default a check is made that the certificate of the SSL server is issued for the hostname specified in the Broker ID.
The common name of the subject entry in the server's certificate is checked against the hostname. If they do not match, the
connection will be refused.
You can disable this check with SSL parameter verify_server=no
.
If the SSL server additionally checks the identity of the SSL client, this is known as two-way SSL. In this case the SSL server requests a client certificate
(the parameter verify_client=yes
is defined in the configuration of the SSL server).
Two additional SSL parameters must be specified on the SSL client side: key_store
and key_passwd
.
This keystore must contain the private key of the SSL client. The password that protects the private key is specified with
key_passwd
.
The ampersand (&) character cannot appear in the password.
SSL parameters are separated by ampersand (&). See also SSL/TLS Parameters for SSL Clients.
Make sure the SSL server to which the RPC side connects is prepared for SSL connections as well. The SSL server can be EntireX Broker or Broker SSL Agent. See:
To start the RPC Server for IMS Connect
Use the Start Script.
Or:
Under Windows you can use the RPC Server for IMS Connect as a Windows Service. See Running an EntireX RPC Server as a Windows Service.
To stop the RPC Server for IMS Connect
Use the command stopService
. See Stop Running Services in Command Central's Command-line Interface.
Or:
Stop the service using Command Central's Graphical User Interface. See Stopping a Service.
Or:
Use the command-line utility etbcmd
. See ETBCMD
under
z/OS |
UNIX |
Windows |
z/VSE |
BS2000.
Or:
Use CTRL-C
in the session where you started the RPC server instance.
Or:
Under UNIX, enter command kill -
.
process-id
To ping the RPC Server for IMS Connect
Enter the following command:
java -classpath "$EXXDIR/classes/entirex.jar" com.softwareag.entirex.rpcping.RPCServerPing -p <admin_port>
where | admin_port |
is the number of the administration port. |
The ping
command returns "0
" if the server is reachable, and "1
" if the server cannot be accessed.
For general information see Running an EntireX RPC Server as a Windows Service.
To run the RPC Server for IMS Connect as a Windows Service
Customize the Start Script according to your system installation.
Note:
The script must pass external parameters to the RPC server and use the reduced signaling of the JVM (option -Xrs
):
java -Xrs com.softwareag.entirex.ims.IMSRPCServer %*
If -Xrs
is not used, the JVM stops and an entry 10164002 is written to the event log when the user logs off from Windows.
See also Starting the RPC Server.
Test your RPC server to see whether it will start if you run your script file.
Use the EntireX RPC Service Tool and install the RPCService
with some meaningful extension, for example MyServer
. If your Start Script is imsconnectserver.bat, the command will be
RPCService -install -ext MyServer -script install_path
\EntireX\bin\imsconnectserver.bat
The log file will be called RPCservice_MyServer.log.
In Windows Services menu (Control Panel > Administrative Tools > Services) select the service: Software AG EntireX RPC Service [MyServer]
and change the property Startup Type
from "Manual" to "Automatic".
The application identification is sent from the RPC Server for IMS Connect 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 RPC Server for IMS Connect, these values are:
Identification Part | Value |
---|---|
Application name | ANAME=IMS Connect RPC Server
|
Node name | ANODE=<host name> |
Application type | ATYPE=Java |
Version | AVERS=10.5.0.0 |