Version 9.6
 —  WMQ RPC Server and Listener  —

Administering the EntireX WebSphere MQ RPC Server

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.


Customizing the WebSphere MQ RPC Server

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.

Top of page

Configuring the RPC Server Side

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)
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
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).

Top of page

Configuring the WebSphere MQ Side

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

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.

Start of instruction setTo adjust the marshalling for arrays of groups under COBOL

  1. Use the property entirex.bridge.marshalling for the configuration.

  2. 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:

  1. Only as last value.
  2. YYYY year, MM month, DD day.
  3. YYYY year, MM month, DD day, hh hour, mm minute, ss second, S tenth of a second.

Data Types not supported:

Start of instruction setTo adjust the marshalling for arrays of groups under Natural

  1. Use the property entirex.bridge.marshalling for the configuration.

  2. 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:

  1. Only as last value.
  2. YYYY year, MM month, DD day.
  3. YYYY year, MM month, DD day, hh hour, mm minute, ss second, S tenth of a second.

Data Types not supported:

Top of page

Starting the WebSphere MQ RPC Server

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.

Top of page

Stopping the WebSphere MQ RPC Server

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.

Top of page

Tracing the WebSphere MQ RPC Server

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.

Top of page