Administering the EntireX RPC Server for IBM® MQ

The EntireX RPC Server for IBM® MQ runs as an RPC server and processes RPC client calls. It is used to send messages to and receive messages from an IBM MQ queue. This means that existing EntireX wrappers can be used for communication with IBM MQ.

This document describes how to administer the RPC Server for IBM MQ with local scripts as in earlier versions of EntireX. It covers the following topics:

See also Administering the RPC Server for IBM MQ with the Command Central GUI | Command Line.

Customizing the RPC Server

The following elements are used to set up the RPC Server for IBM MQ:

Prerequisites

There are two parts: the RPC server and the IBM® MQ side. The RPC Server for IBM MQ uses the following:

  • The IBM® MQ base Java classes from IBM. To run the RPC Server for IBM MQ, you need either the base Java classes or a full installation of IBM® MQ. See Prerequisites for RPC Server and Listener for IBM® MQ under UNIX | Windows for the required JAR file(s). The IBM® MQ environment variables MQ_JAVA_LIB_PATH and MQ_JAVA_INSTALL_PATH must be set. Make sure that either the local IBM® MQ installation or the IBM® MQ Java classes are accessible.

  • The WS-Stack. Therefore the start scripts contain references to JAR files in the WS-Stack directory. If you update these JAR files, you may need to customize the JAR file names in the script files.

Configuration File

The default name for the configuration file is entirex.wmqbridge.properties. The RPC Server for IBM MQ 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. Use the slash "/" as file separator. The configuration file contains the configuration for both parts of the RPC Server for IBM MQ.

Start Script

The start script for the RPC Server for IBM MQ is called wmqbridge.bsh (UNIX) or wmqbridge.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The script uses the configuration file entirex.wmqBridge.properties in the folder etc. The RPC Server for IBM MQ itself is contained in the file entirex.jar.

Configuring the RPC Server Side

The RPC server side of the RPC Server for IBM MQ is configured like the RPC Server for Java. The RPC Server for IBM MQ uses all properties starting 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.

With entirex.server.fixedservers=yes, the number of entirex.server.minservers is started and the server can process this number of parallel requests.

With 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 you can use the command-line option. The command-line parameters have a higher priority than the properties set as Java system properties, and these have higher priority than the properties in the configuration file. For a list of all of the command-line parameters, use -help.

Property Name Parameter Default Explanation
entirex.bridge.marshalling     Define the type of marshalling (Natural or COBOL). Must be set only if the IDL file contains arrays of groups. See Mapping RPC Data to the MQ Message Buffer.
entirex.server.brokerid -broker localhost Broker ID. See URL-style Broker ID.
entirex.server.compresslevel -compresslevel 0 (no compression)
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.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.
  -help   Display usage of the command-line parameters.
entirex.server.logfile -logfile   Name of the log file, the default is standard output.
entirex.server.maxservers   32 Maximum number of worker threads.
entirex.server.minservers   1 Minimum number of server threads.
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.wmqbridge.properties The file name of the property file.
entirex.server.restartcycles -restartcycles 15 Number of restart attempts if the Broker is not immediately available. This can be used to keep the RPC Server for IBM MQ running while the Broker is temporarily down.
entirex.server.security -security no no/yes/auto/Name of BrokerSecurity object.
entirex.server.serveraddress -server RPC/SRV1/CALLNAT Server address.
entirex.server.serverlog -serverlog   Name of the file where worker thread starts and stops are logged. Used by the Windows RPC Service.
entirex.server.userid -user WMQRPCServer The user ID for access to the broker.
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.trace -trace 0 Trace level (1,2,3).

Configuring the IBM MQ Side

These properties are used to configure the connection to the IBM® MQ queue manager.

Name Parameter Default Value Explanation
entirex.wmqbridge.host     If host is not specified, bindings mode is used to connect to the local MQ Server. Otherwise specify the hostname or IP address of the MQ Server.
entirex.wmqbridge.port   1414 Port of the MQ Server. Not used in bindings mode.
entirex.wmqbridge.channel   SYSTEM.DEF.SVRCONN Channel name used to the MQ Server. Not used in bindings mode.
entirex.wmqbridge.queuemanager -wmqqmanager   Name of the (local or remote) queue manager. If not specified, a connection is made to the default queue manager.
entirex.wmqbridge.inputqueue -wmqinqueue   Name of input queue (the queue that is used for MQGET calls).
entirex.wmqbridge.outputqueue -wmqoutqueue   Name of output queue (the queue that is used for MQPUT calls).
entirex.wmqbridge.userid -wmquser   UserID for MQ Server.
entirex.wmqbridge.password -wmqpassword   Password for MQ Server.
entirex.wmqbridge.waittime     Wait interval for MQGET call in milliseconds.
entirex.wmqbridge.userexit     Class name for user exit.
entirex.wmqbridge.userexit.classpath     URL of the classpath for user exit (optional).
entirex.wmqbridge.ccsid   platform encoding Coded Character Set Identification used by the RPC Server for IBM MQ (which acts as an MQ client), unused in bindings mode.

Enable character conversion in the broker by setting the service-specific attribute CONVERSION to "SAGTRPC". See also Configuring ICU Conversion under z/OS | UNIX | Windows | BS2000 | z/VSE. More information can be found under Internationalization with EntireX.

entirex.wmqbridge.mqtrace   0 MQ tracing enabled if parameter > 0.
entirex.bridge.xmm     Name of XMM (XML Mapping) file; if MQ message payload is XML/SOAP. If this is specified, messages to/from MQ will be converted to XML.
entirex.bridge.xml.encoding   utf-8 Encoding of the XML document that is sent to MQ (if entirex.bridge.xmm is used).
entirex.wmqbridge.environment.sslCipherSuite     Configuration for SSL connection to MQ Server. See the IBM® MQ documentation for details.
entirex.wmqbridge.environment.sslFipsRequired     Configuration for SSL connection to MQ Server. See the IBM® MQ documentation for details.
entirex.wmqbridge.priority     Message priority for messages sent to MQ (different from the default priority of the destination queue).

The RPC Server for IBM MQ can be run to

  • only send messages to MQ (only output queue specified),

  • only receive messages from MQ (only input queue specified), or

  • transport messages in both directions (bidirectional communication).

If your programs use arrays of groups, you have to set entirex.bridge.marshalling to "Natural" or "COBOL". If your programs do not use arrays of groups, you must not set entirex.bridge.marshalling.

Alternatively the RPC data can be transformed to/from XML or SOAP as defined by an XMM mapping file from the XML/SOAP Wrapper. To achieve this, specify the parameter entirex.bridge.xmm.

Starting the RPC Server

Start of instruction setTo start the RPC Server for IBM MQ

Stopping the RPC Server

Start of instruction setTo stop the RPC Server for IBM MQ

Pinging the RPC Server

Start of instruction setTo ping the RPC Server for IBM MQ

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

Using SSL/TLS with the RPC Server

To use SSL with RPC Server for IBM MQ, you need to configure two sides:

  • IBM® MQ Side
    See parameters entirex.wmqbridge.environment.sslCipherSuite and entirex.wmqbridge.environment.sslFipsRequired under Configuring the IBM MQ Side.

  • RPC Server side
    On the RPC server side you 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. On the RPC server side, an SSL client is configured. The SSL server can be either the EntireX Broker, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS 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 default 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 side for IBM MQ 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.

    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, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). See:

Running an EntireX RPC Server as a Windows Service

For general information see Running an EntireX RPC Server as a Windows Service.

Start of instruction setTo run the RPC Server for IBM MQ 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.rpcbridge.WMQBridge %*

    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 wmqbridge.bat, the command will be 

    RPCService -install -ext MyServer -script install_path\EntireX\bin\wmqbridge.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".

Activating Tracing for the RPC Server

The trace level for the RPC server side is controlled by the usual entirex.trace property.

Tracing of the IBM MQ classes can be influenced with the property entirex.wmqbridge.mqtrace.

Redirect the trace to a file with the property entirex.server.logfile. Set this to the file name of the log file, default is standard output.

All properties can be set in the configuration file.