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 EntireX 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.xml.encoding |
utf-8 |
Encoding of the XML document which is sent to MQ
(if entirex.bridge.xmm is used).
|
||||||||||||||||
entirex.server.brokerid |
-broker |
localhost |
Broker ID | |||||||||||||||
entirex.server.compresslevel |
-compresslevel |
0 (no compression)
|
|
|||||||||||||||
entirex.server.encryptionlevel |
-encryption |
0 |
Encryption level. Valid values: 0,1,2. | |||||||||||||||
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 |
Path and name of the trace output file. | ||||||||||||||||
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. For Java 1.4 and
above, 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). For Java 1.3 and below, password encryption
is not available.
|
||||||||||||||||
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.logfile |
-serverlog |
Name of the file where worker thread starts and stops are logged. Used by the Windows RPC Service. | ||||||||||||||||
entirex.server.userid |
-user |
WMQBridge |
The user ID for the Broker for RPC. See entirex.server.password.
|
|||||||||||||||
entirex.server.verbose |
-verbose |
no |
Verbose output to standard output yes/no. | |||||||||||||||
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 |
Level of MQ tracing required, from 1 to 5 (5 being the most detailed). | |
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 adjust the marshalling
(see below). If your programs do not use arrays of groups, you do not need to
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.
To adjust the marshalling for arrays of groups under COBOL
Use the property
entirex.bridge.marshalling for the
configuration.
Set the property to "cobol".
The WebSphere MQ RPC Server uses a predefined mapping of IDL data types to the MQ message buffer.
| Data Type | Description | Format | Note |
|---|---|---|---|
Anumber |
Alphanumeric | number bytes, encoding the characters.
|
|
AV[number] |
Alphanumeric variable length with maximum length | Bytes up to the end of the buffer, maximal length number.
|
1 |
Knumber |
Kanji | Same as data type A.
|
|
KV[number] |
Kanji variable length with maximum length | Same as data type AV[number].
|
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).
|
|
Nnumber1[.number2] |
Unpacked decimal | sign (+, -), number1 bytes (digits) [number2] bytes (digits), no decimal point.
|
|
NUnumber1[.number2] |
Unpacked decimal unsigned | number1 bytes (digits) [number2] bytes (digits), no decimal point.
|
|
Pnumber1[.number2] |
Packed decimal | sign (+, -), number1 bytes (digits) [number2] bytes (digits), no decimal point.
|
|
PUnumber1[.number2] |
Packed decimal unsigned | number1 bytes (digits) [number2] 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)
To adjust the marshalling for arrays of groups under Natural
Use the property
entirex.bridge.marshalling for the
configuration.
Set the property to "natural".
The WebSphere MQ RPC Server uses a predefined mapping of IDL data types to the MQ message buffer.
| Data Type | Description | Format | Note |
|---|---|---|---|
Anumber |
Alphanumeric | number bytes, encoding the characters.
|
|
AV |
Alphanumeric variable length | Bytes up to the end of the buffer. | 1 |
AV[number] |
Alphanumeric variable length with maximum length | Bytes up to the end of the buffer, maximal length number.
|
1 |
Knumber |
Kanji | Same as data type A.
|
|
KV |
Kanji variable length | Same as data type AV.
|
1 |
KV[number] |
Kanji variable length with maximum length | Same as data type AV[number].
|
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).
|
|
Nnumber1[.number2] |
Unpacked decimal | sign (+, -), number1 bytes (digits) [number2] bytes (digits), no decimal point.
|
|
Pnumber1[.number2] |
Packed decimal | sign (+, -), number1 bytes (digits) [number2] 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.
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.