Administrating EntireX IMS Connect RPC Server

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:


Customizing the IMS Connect RPC Server

The following are provided to set up the IMS Connect RPC Server:

  • a configuration file

  • scripts to start the IMS Connect RPC Server.

Location of the IMS Connect RPC Server

The IMS Connect RPC Server is contained in the file entirex.jar.

The Configuration File

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.

graphics/imsConnect_config.png

Start of instruction setTo set up the IMS Connect RPC Server

  1. Use the RPC server agent of the System Management Hub.

  2. 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.

Configuring more than one IMS Connect RPC Server

If you configure more than one IMS Connect RPC Server that connects to the same 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

Configuring the RPC Server Side

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 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.

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. See URL-style 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
no Use attach server to manage worker threads.
yes Run minimum number of server threads.
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 Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX.
entirex.server.compresslevel -compresslevel 0 Permitted values (you can enter the text or the numeric value)
BEST_COMPRESSION 9
BEST_SPEED 1
DEFAULT_COMPRESSION -1, mapped to 6
DEFLATED 8
NO_COMPRESSION 0
N 0
Y 8
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.

Configuring the IMS Connect Side

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:
Enable conversion in the Broker attribute file so the data can be converted correctly, typically by setting service-specific attribute CONVERSION to "SAGTCHA".

Default "cp037" is EBCDIC codepage with full Latin-1 character set.

ims.useoldexit yes
yes Use old IMS Connect user message exit. Name is *SAMPLE*.
no Use new IMS Connect user message exit. Name is *SAMPLE1*.
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
true, yes Check for DFS message. Return an error and do not return the message if it contains a DFS error message.
false, no Do not check for DFS message.
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 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.

Using SSL/TLS with the RPC Server

To use SSL with the IMS Connect RPC Server, 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 in the Security documentation.

    Start of instruction setTo use SSL

    1. 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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the Security documentation.

    2. Set up the IMS Connect RPC Server 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 EntireX Clients and Servers.

    3. 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:

      • Running Broker with SSL/TLS Transport under z/OS | UNIX | Windows | z/VSE

      • Settting up and Administering the EntireX Broker SSL Agent under UNIX | Windows

Starting the IMS Connect RPC Server

Start of instruction setTo 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.

Stopping the IMS Connect RPC Server

Start of instruction setTo 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.

Application Identification

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.9.0.0