EntireX WebSphere MQ RPC Server runs as an RPC server and processes RPC client calls. It is used to send messages to and receive messages from a WebSphere MQ Queue. This means that existing EntireX wrappers can be used for communication with WebSphere MQ.
This document covers the following topics:
See also Introduction to the WebSphere MQ RPC Server and WebSphere MQ Listener | Advanced WebSphere MQ RPC Server Functionality | Administering the WebSphere MQ Listener | Advanced WebSphere MQ Listener Functionality.
To set up the WebSphere MQ RPC Server, there is a configuration file and there are scripts to start the WebSphere MQ RPC Server.
The WebSphere MQ RPC Server is contained in entirex.jar. There are two parts: the RPC server and the WebSphere MQ side.
The WebSphere MQ RPC Server uses the WebSphere MQ base Java classes from
IBM. To run the WebSphere MQ RPC Server, 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.wmqbridge.properties. The WebSphere MQ RPC Server
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 RPC Server.
Use the RPC server agent of the System Management Hub for setup. Add the WebSphere MQ RPC Server as an RPC server. See Administering the EntireX RPC Servers using System Management Hub under UNIX | Windows for details.
Alternatively, you can use a script to start the WebSphere MQ RPC Server. On Windows, use wmqbridge.bat in the folder bin to start the WebSphere MQ RPC Server. On UNIX, use wmqbridge.bsh in the folder bin to start the WebSphere MQ RPC Server. Both scripts use the configuration file entirex.wmqBridge.properties in the folder etc, and both can be customized.
The RPC server side of the WebSphere MQ RPC Server is configured like the Java RPC Server. The WebSphere MQ RPC Server 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.
| Name | Parameter | 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 |
-broker |
localhost |
Broker ID. See URL-style Broker ID. | |||||||||||||||
entirex.server.compresslevel |
-compresslevel |
0 (no compression)
|
|
|||||||||||||||
entirex.server.encryptionlevel |
-encryption |
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.fixedservers |
no |
If no, use an attach server thread to manage worker threads,
otherwise run the minimum number of server threads. See the properties
entirex.server.maxservers and
entirex.server.minservers.
|
||||||||||||||||
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.monitorport |
-smhport |
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 |
-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 |
-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 Java RPC Server 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 the Broker for RPC. See entirex.server.password.
|
|||||||||||||||
entirex.server.verbose |
-verbose |
no |
Enable verbose output to the log file. | |||||||||||||||
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). |
These properties are used to configure the connection to the WebSphere 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 which is used for MQ GET
operations).
|
|
entirex.wmqbridge.outputqueue |
-wmqoutqueue |
Name of output queue (the queue which is used for MQ PUT
operations).
|
|
entirex.wmqbridge.userid |
-wmquser |
UserID for MQ Server. | |
entirex.wmqbridge.password |
-wmqpassword |
Password for MQ Server. | |
entirex.wmqbridge.waittime |
Wait interval for MQ Get operation in milliseconds. | ||
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 EntireX WebSphere MQ RPC Server (which acts as an MQ client), unused in bindings mode. | |
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 which is sent to MQ (if entirex.bridge.xmm is used). | |
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 RPC Server | |
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). |
The WebSphere MQ RPC Server 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.
The WebSphere MQ RPC Server uses a predefined mapping of IDL data types to the MQ message buffer.
| 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 wmqbridge.bsh (UNIX) or wmqbridge.bat (Windows) in the folder
bin to start the WebSphere MQ RPC Server. 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.
You can use the RPC server agent in the System Management Hub to configure and start the WebSphere MQ RPC Server.
Under Windows you can start the WebSphere MQ RPC Server as a Windows Service. The installation of the service is similar to the installation of the Java RPC Server as Windows Service. See Running the Java RPC Server as a Windows Service.
Use the RPC server agent in the System Management Hub to stop the WebSphere MQ RPC Server. You can also stop the WebSphere MQ RPC Server with CTRL-C.
On UNIX you can use kill <pid of Java
process> to stop the WebSphere MQ RPC Server.
An alternative is the agent for the Broker. Use
Deregister on the service, specified with the
property entirex.server.serveraddress.
To use SSL with WebSphere MQ RPC Server, 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 Server 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 RPC Server 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, default is standard output.