EntireX WebSphere MQ Listener runs as a listener on a WebSphere MQ queue and passes messages to an RPC server. It is used to send messages received from a WebSphere MQ queue to an RPC server applications. This means that existing RPC servers can be used for communication with WebSphere MQ.
The WebSphere MQ Listener can process MQ messages that are in
XML or SOAP format and that can be mapped to a Software AG IDL file, using
XML Mapping Editor. The resulting XMM file has to be specified by the configuration property entirex.bridge.xmm.
The WebSphere MQ Listener can also process MQ messages that are in text format.
An IDL file is used, which describes the message layout (see Mapping IDL Data Types to the MQ Message Buffer).
The IDL file has to be specified by the configuration property entirex.bridge.idl.
The program name is taken from the applicationIdData field of the incoming MQ message.
If this field is empty and the IDL file has only one program this program will be called.
A custom logic (e.g. using the first n bytes of the MQ message payload) can be implemented in the user exit.
Note:
EntireX WebSphere MQ ignores EntireX configuration parameters inside the XML/SOAP payload.
See XML/SOAP Listener under Writing Advanced Applications with the XML/SOAP Wrapper.
This document covers the following topics:
See also Introduction to the WebSphere MQ RPC Server and WebSphere MQ Listener | Advanced WebSphere MQ Listener Functionality.
To set up the WebSphere MQ Listener, there is a configuration file and there are scripts to start the WebSphere MQ Listener.
The WebSphere MQ Listener is contained in entirex.jar. There are two parts: the RPC side and the WebSphere MQ side.
The WebSphere MQ Listener uses the WebSphere MQ base Java classes from
IBM. To run the WebSphere MQ Listener, you need either the base Java classes or
a full installation of WebSphere. Prerequisites for all EntireX components are described centrally.
See Prerequisites for WebSphere MQ RPC Server and WebSphere MQ Listener under
UNIX |
Windows for the required JAR file(s).
The WebSphere MQ environment variables
MQ_JAVA_LIB_PATH and
MQ_JAVA_INSTALL_PATH must be set.
Make sure that either the local WebSphere MQ installation or the WebSphere MQ Java classes are accessible.
The default name for the configuration file is
entirex.wmqbridgelistener.properties. The
WebSphere MQ Listener 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
WebSphere MQ Listener.
Alternatively, use script wmqbridgelistener.bsh (UNIX) or wmqbridgelistener.bin in the
bin directory to start the
WebSphere MQ Listener. Both
scripts use the configuration file
entirex.wmqbridgelistener.properties in the folder
etc, and both can be customized.
The WebSphere MQ Listener 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 |
WMQListener |
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 WebSphere MQ Listener 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) |
|
|||||||||||||||
entirex.server.encryptionlevel |
0 |
Deprecated. For encrypted transport we strongly recommend using the Secure Sockets Layer/Transport Layer Security protocol. See SSL/TLS and Certificates with EntireX. | |||||||||||||||
entirex.server.logfile |
Name of the log file, the default is standard output. | ||||||||||||||||
entirex.server.monitorport |
0 |
The port where the server listens for commands from the System Management Hub (SMH). If this port is 0, no port is used and management by the SMH is disabled. | |||||||||||||||
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). |
These properties are used to configure the connection to the WebSphere 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 WebSphere MQ Listener (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.names.file |
Name of a properties file generated with the bridge.tpl template, which contains names of the first level parameters in the IDL file (optional). Necessary if IDL file contains dynamic MQ parameters. | |
entirex.bridge.verbose |
no |
Verbose/trace mode of WebSphere MQ Listener |
entirex.wmqbridge.environment.sslCipherSuite |
Configuration for SSL connection to MQ Server. See the WebSphere MQ documentation for details. | |
entirex.wmqbridge.environment.sslFipsRequired |
Configuration for SSL connection to MQ Server. See the WebSphere 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. |
The WebSphere MQ Listener uses a predefined mapping of IDL data types to the MQ message buffer if the MQ message is in text format.
If your programs use arrays of groups, you have to set the property
entirex.bridge.marshalling to "Natural" or "COBOL".
If your programs do not use arrays of groups, you must not set entirex.bridge.marshalling.
| Data Type | Description | Format | Note |
|---|---|---|---|
A |
Alphanumeric | number bytes, encoding the characters.
|
|
AV |
Alphanumeric variable length | Bytes up to the end of the buffer. | 1, 4 |
AV[ |
Alphanumeric variable length with maximum length | Bytes up to the end of the buffer, maximal length number.
|
1 |
K |
Kanji | Same as data type A.
|
|
KV |
Kanji variable length | Same as data type AV.
|
1, 4 |
KV[ |
Kanji variable length with maximum length | Same as data type AV[.
|
1 |
I1 |
Integer (small) | sign (+, -) and 3 bytes (digits).
|
|
I2 |
Integer (medium) | sign (+, -) and 5 bytes (digits).
|
|
I4 |
Integer (large) | sign (+, -) and 10 bytes (digits).
|
|
N |
Unpacked decimal | sign (+, -), number1 bytes (digits) [number2] bytes (digits), no decimal point.
|
|
P |
Packed decimal | sign (+, -), [ bytes (digits), no decimal point.
|
|
L |
Logical | 1 byte: X for true, all other false. | |
D |
Date | YYYYMMDD.
|
2 |
T |
Time | YYYYMMDDhhmmssS.
|
3 |
Notes:
YYYY year, MM month, DD day.
YYYY year, MM month, DD day, hh hour, mm minute, ss second, S tenth of a second.
Data types not supported:
Binary (B[n],BV, BV[n])
Floating point (F4, F8)
Use start script wmqlistener.bsh (UNIX) or wmqlistener.bat (Windows) in the folder
bin to start the WebSphere MQ Listener. You may customize
this file. See also Prerequisites for WebSphere MQ RPC Server and WebSphere MQ Listener 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 WebSphere MQ Listener.
On UNIX you can use kill <pid of java
process> to stop the WebSphere MQ Listener.
To use SSL with the WebSphere MQ Listener, you need to configure two sides:
WebSphere MQ Side
See parameters entirex.wmqbridge.environment.sslCipherSuite and entirex.wmqbridge.environment.sslFipsRequired under Configuring the WebSphere 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 in the Security 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 Default Certificates Delivered with EntireX under SSL/TLS and Certificates with EntireX in the Security documentation.
Set up the WebSphere MQ RPC Server 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 EntireX Clients and Servers.
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. Additional diagnostic output can be enabled by setting the
property entirex.server.verbose.
The WebSphere MQ Listener-specific diagnostic output is enabled by
setting the property entirex.bridge.verbose. In
addition, tracing of the IBM WebSphere MQ classes can be influenced with the
property entirex.wmqbridge.mqtrace.
Use the RPC server agent of the System Management Hub to dynamically
change the level of the diagnostic output. You can specify a value of 0, 1, 2,
or 3 which changes the value of entirex.trace. In
addition, the value 0 will disable both
entirex.server.verbose and
entirex.bridge.verbose. A value greater than 0
will enable both entirex.server.verbose and
entirex.bridge.verbose.
Redirect the trace to a file with the property
entirex.server.logfile. Set this to the file name
of the log file.