Administering the EntireX Listener for IBM® MQ

The EntireX 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

Properties

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 More Information
entirex.bridge.marshalling Define the type of marshalling (Natural or COBOL). Must be set only if the IDL file contains arrays of groups. Mapping RPC Data to the MQ Message Buffer
entirex.server.brokerid localhost Broker ID. URL-style Broker ID
entirex.server.serveraddress RPC/SRV1/CALLNAT Server address  
entirex.server.userid mqListener The user ID for access to the broker. Using the Broker and RPC User ID/Password
entirex.server.libname   By default the library name sent to the RPC server is retrieved from the IDL file (see library-definition under Software AG IDL Grammar in the IDL Editor documentation). The library name can be overwritten. This is useful if communicating with a Natural RPC server.  
entirex.server.naturallogon no Enable to send the RPC user ID/password pair. Using the Broker and RPC User ID/Password
entirex.server.reliableRPC no If set to "yes", use reliable RPC for the call to the RPC server.  
entirex.server.rpcuser   The RPC user ID sent to the RPC server. Using the Broker and RPC User ID/Password
entirex.server.rpcpassword   The RPC password sent to the RPC server.
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 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.
Using the Broker and RPC User ID/Password
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.waitserver 60S Wait time for the call to the RPC server.  
entirex.timeout 20 TCP/IP transport timeout. Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI
entirex.trace 0 Trace level (1,2,3).  

Using the Broker and RPC User ID/Password

EntireX supports two user ID/password pairs: a broker user ID/password pair and an (optional) RPC user ID/password pair sent from RPC clients to RPC servers. With EntireX Security, the broker user ID/password pair can be checked for authentication and authorization.

The RPC user ID/password pair is designed to be used by the receiving RPC server. This component's configuration determines whether the pair is considered or not. Useful scenarios are:

  • Credentials for Natural Security

  • Impersonation under z/OS (CICS, Batch, IMS) | z/VSE (CICS)

  • Web Service Transport Security with the RPC Server for XML/SOAP, see XML Mapping Files

  • Service execution with client credentials for EntireX Adapter Listeners, see Configuring Listeners

  • etc.

Sending the RPC user ID/password pair needs to be explicitly enabled by the RPC client. If it is enabled but no RPC user ID/password pair is provided, the broker user ID/password pair is inherited to the RPC user ID/password pair.

With the parameter entirex.server.naturallogon (see naturallogon under Configuring the RPC Server Side) sending the RPC user ID/password pair is enabled for the Listener for IBM MQ. If you do so, we strongly recommend using SSL/TLS. See Using SSL/TLS.

Start of instruction setTo use the broker and RPC user ID/password

  1. Specify a broker user ID with parameter entirex.server.userid.

  2. Optional. Specify broker password with parameter entirex.server.password.

  3. Enable to send the RPC user ID/password pair with parameter entirex.server.naturallogon.

  4. If different user IDs and/or passwords are used for broker and RPC, use the parameters entirex.server.rpcuser and entirex.server.rpcpassword to provide a different RPC user ID/password pair.

  5. By default the library name sent to the RPC server is retrieved from the IDL file (see library-definition under Software AG IDL Grammar in the IDL Editor documentation). The library name can be overwritten. This is useful if communicating with a Natural RPC server. Specify a library in property entirex.server.libname.

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.

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.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.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 with the Listener for IBM MQ

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 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 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 Listener for IBM MQ

The trace level for the EntireX RPC part is controlled by the usual entirex.trace property. It can be set in the configuration file.

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.