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:
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.
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 RPC Data 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 user ID for access to the broker. See 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. See 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. See 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):
|
||||||||||||||
-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.
See 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. See Setting the Transport Timeout under Writing Advanced Applications - EntireX Java ACI. | ||||||||||||||
entirex.trace |
0 |
Trace level (1,2,3). |
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
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.
To use the broker and RPC user ID/password
Specify a broker user ID with parameter entirex.server.userid.
Optional. Specify broker password with parameter entirex.server.password.
Enable to send the RPC user ID/password pair with parameter entirex.server.naturallogon.
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.
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.
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 |
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. |
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.
Use CTRL-C to stop 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.
To use SSL
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.
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.
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:
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.