Configuring the RPC Server for IMS Connect with Local Scripts

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.


Customizing the RPC Server

The following elements are used to set up the RPC Server for IMS Connect:

Configuration File

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.

graphics/imsConnect_config.png

Configuring more than one RPC Server

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)

Start Script

The start script for the RPC Server for IMS Connect is called imsconnectserver.bsh (Linux) 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.

Configuring the RPC Server Side

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. graphics/toc_closed.png More info
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
NO The number of worker threads balances between what is specified in entirex.server.minservers and what is specified in entirex.server.maxservers. This is done by a so-called attach thread. At startup, the number of worker threads is the number specified in entirex.server.minservers. A new worker thread starts if the broker has more requests than there are worker threads waiting. If more than the number specified in 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.
See worker model DYNAMIC.
YES The number of worker threads specified in entirex.server.minservers is started and the server can process this number of parallel requests.
See worker model FIXED.
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 yes 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 name of the property file.
entirex.server.security -security no Valid values:
no | yes | auto | name of BrokerSecurity object.
entirex.server.compresslevel -compresslevel 0 (no compression) Enter the text or the numeric value:
BEST_COMPRESSION  9
BEST_SPEED  1
DEFAULT_COMPRESSION
  (mapped to
-1
 6)
DEFLATED  8
NO_COMPRESSION  0
N  0
Y  8
graphics/toc_closed.png More info
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. graphics/toc_closed.png More info
  -help   Display usage of the command-line parameters.
entirex.server.logfile -logfile standard output Name of the log file.
entirex.trace -trace 0 Trace level. graphics/toc_closed.png More info
0 No tracing, default.
1 Trace all broker calls and other major actions.
2 Dump the send and receive buffer.
3 Dump the buffers sent to the broker and received from the broker.

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 or IP address where IMS Connect is running
ims.port   TCP or SSL port number where IMS Connect is listening.
ims.datastoreid   Data store ID. Name of the IMS system that will receive transactions.
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. 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 (max. 8 chars).
ims.lterm   IMS LTERM override (max. 8 chars).
ims.userid   The user ID (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).
ims.groupid   RACF group ID (max. 8 chars).
ims.password   Password (max. 8 chars) as defined in your underlying mainframe security system (e.g. RACF).

The password is encrypted and written to the property ims.password.e.

  • To change the password, set the new password in the properties file.

  • To disable password and/or secured signon key encryption, set entirex.server.passwordencrypt=no.

ims.applname (1)   Required if PassTicket is to be used instead of a password. Application name (1-8 chars) as defined in your RACF system. This property is ignored if RACF password is set.
ims.secured.signonkey (1)   Required if PassTicket is to be used instead of a password. Secured signon key as defined in your RACF system. Must be exactly 16 characters long.

The secured signon key is encrypted and written to the property ims.secured.signonkey.e.

  • To change the secured signon key, set the new secured signon key in the properties file.

  • To disable password and/or secured signon key encryption, set entirex.server.passwordencrypt=no.

    This property is ignored if ims.password is set.

ims.sslparams   SSL parameters. Same syntax as Broker ID.
ims.mapping.folder   This is the server-side mapping container, the folder where the RPC server expects server-side mapping files (Designer files with extension .svm).
  • If no server requires server-side mapping (.svm) or you use server mapping files with extension .cvm only, you can omit this property.

  • If one server requires server-side mapping (.svm), this property must be specified.

Server mapping files with extension .svm are no longer supported at design time by the Designer. You can still use them at runtime in a server-side mapping container. All special COBOL syntax and features supported by server mapping files with extension .svm are also covered by server mapping files with extension .cvm. See When is a Server Mapping File Required?
We recommend migrating .svm files to .cvm files. See Migrating Server Mapping Files under Server Mapping Files for COBOL in the Designer documentation.

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.

Notes:

  1. By default, PassTickets can only be used once during a one-second time interval. They are protected against replay. This limits the workload to one request per second.

    Warning:
    IBM provides a mechanism to bypass the PassTicket's replay mechanism, allowing higher workloads, but this introduces security risks. The option to bypass the PassTicket's replay mechanism should only be used in secure environments where access to generated PassTickets is limited to a secure or internal network. See your IBM documentation for more information.

Using SSL/TLS with the RPC Server

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, HTTP(S), and Certificates with EntireX in the platform-independent Administration 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 sample certificates, but we strongly recommend that you create your own. See SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

    2. 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.p12&trust_passwd=ExxCACert&verify_server=no

      If the SSL client checks the validity of the SSL server only, this is known as one-way SSL. Two SSL parameters must be specified on the SSL client side: trust_store and trust_passwd. The mandatory trust_store parameter specifies the file name of a PKCS#12 certificate store that must contain the certificate chain of the trusted certificate authority (CA) that issued the SSL server's certificate.
      To unlock this certificate store, the password has to be set with SSL parameter trust_passwd.
      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.

    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:

Starting the RPC Server

Start of instruction setTo start the RPC Server for IMS Connect

Stopping the RPC Server

Start of instruction setTo stop the RPC Server for IMS Connect

Pinging the RPC Server

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

Running an EntireX RPC Server as a Windows Service

For general information see Running an EntireX RPC Server as a Windows Service in the Windows Administration documentation.

Start of instruction setTo run the RPC Server for IMS Connect as a Windows Service

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

  2. Test your RPC server to see whether it will start if you run your script file.

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

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

Application Identification

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