Administering the Listener for IBM® MQ

The Listener for IBM® MQ runs as a listener on an IBM MQ queue and passes messages to an RPC server. It is used to send messages received from an IBM MQ queue to an RPC server application. This means that existing RPC servers can be used for communication with IBM MQ. This document covers the following topics:

Customizing the Listener for IBM MQ

To set up the Listener for IBM MQ, there is a configuration file and there are scripts to start the Listener for IBM MQ.

The Listener for IBM MQ is contained in entirex.jar. There are two parts: the RPC side and the IBM® MQ side.

The Listener for IBM MQ uses the IBM® MQ base Java classes from IBM. To run the Listener for IBM MQ, you need either the base Java classes or a full installation of IBM® MQ. Prerequisites for all EntireX components are described centrally. 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 default name for the configuration file is entirex.wmqbridgelistener.properties. The Listener 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 Listener for IBM MQ.

Alternatively, use script wmqbridgelistener.bsh (UNIX) or wmqbridgelistener.bin in the bin directory to start the Listener for IBM MQ. Both scripts use the configuration file entirex.wmqbridgelistener.properties in the etc directory, and both can be customized.

Configuring the RPC Server Side

The Listener for IBM MQ converts an MQ message into an RPC request to an RPC server. The RPC server is defined using the following properties.

Name Default Value 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 IDL Data Types to the MQ Message Buffer.
entirex.server.brokerid localhost Broker ID. See URL-style Broker ID.
entirex.server.serveraddress RPC/SRV1/CALLNAT Server address
entirex.server.userid mqListener The Broker user ID.
entirex.server.libname   The RPC library name (optional). The default value is the library name of the XMM/IDL file.
entirex.server.naturallogon no Enables or disables logon to Natural Security for Natural RPC Server.
entirex.server.reliableRPC no If set to "yes", use reliable RPC for the call to the RPC Server.
entirex.server.rpcuser   Optional. RPC user ID (if different from entirex.server.brokerid).
entirex.server.rpcpassword   Optional. RPC password (if different from entirex.server.password).
entirex.server.retrycycles 15 Number of retry attempts if the call to the RPC server is not successful. If all attempts fail, the MQ message will not be committed and the Listener for IBM MQ will terminate. If a dead-letter queue has been specified, the message will be put to that queue and committed and the Listener will not stop.
entirex.server.retryinterval 20 Retry interval (in seconds) if the call to the RPC server is not successful.
entirex.server.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
  -help Display usage of the command-line parameters.
entirex.server.logfile   Name of the log file, the default is standard output.
entirex.server.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.wmqbridge.properties). To disable password encryption, set entirex.server.passwordencrypt=no (default for this property is yes).
entirex.server.properties entirex.wmqbridgelistener. properties The file name of the property file.
entirex.server.security no no/yes/auto/Name of BrokerSecurity object.
entirex.server.logfile   Name of the log file, the default is standard output.
entirex.server.verbose no Enable verbose output to the log file.
entirex.server.waitserver 60S Wait time for the call to the RPC server.
entirex.timeout 20 TCP/IP transport timeout. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI.
entirex.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 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   Name of the (local or remote) queue manager. If not specified, a connection is made to the default queue manager.
entirex.wmqbridge.listenqueue   Name of the queue from which messages are retrieved.
entirex.wmqbridge.userid   User ID for MQ Server.
entirex.wmqbridge.password   Password for MQ Server.
entirex.wmqbridge.userexit   Class name for WMQBridge user exit.
entirex.wmqbridge.userexit.classpath   URL of the classpath for WMQBridge user exit (optional).
entirex.wmqbridge.ccsid platform encoding Coded Character Set Identification used by the Listener for IBM MQ (which acts as an MQ client), unused in bindings mode.
entirex.wmqbridge.mqtrace 0 MQ tracing enabled if parameter > 0.
entirex.bridge.idl   Name of a Software AG IDL file; messages to/from MQ are in plain text.
entirex.bridge.xmm   Name of XMM (XML mapping) file; messages to/from MQ will be converted to XML.
entirex.bridge.xml.encoding   Encoding of the reply XML document.
entirex.bridge.verbose no Verbose/trace mode of Listener for IBM MQ
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).
entirex.wmqbridge.deadletterqueue   Name of the queue that will receive unprocessed messages.

Starting the Listener for IBM MQ

Use start script mqListener.bsh (UNIX) or mqListener.bat (Windows) in the bin directory to start the Listener for IBM MQ. You may customize this file. See also Prerequisites for RPC Server and Listener for IBM® MQ under UNIX | Windows.

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.

Stopping the Listener for IBM MQ

Use CTRL-C to stop the Listener for IBM MQ.

Using SSL/TLS

To use SSL with the Listener 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
    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, Broker SSL Agent, or Direct RPC in webMethods Integration Server (IS inbound). For an introduction see SSL/TLS and Certificates with EntireX in the EntireX 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 SSL/TLS Sample Certificates Delivered with EntireX in the EntireX Security documentation.

    2. Set up the Listener 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:

Activating Tracing for the RPC Server

The trace level for the EntireX RPC part is controlled by the usual entirex.trace property. It can be set in the configuration file. Additional diagnostic output can be enabled by setting the property entirex.server.verbose.

The Listener for IBM MQ-specific diagnostic output is enabled by setting the property entirex.bridge.verbose. In addition, 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.