The EntireX RPC Server for IBM® MQ runs as an RPC server and processes RPC client calls. It is used to send messages to and receive messages from an IBM MQ queue. This means that existing EntireX wrappers can be used for communication with IBM MQ.
This document describes how to administer the RPC Server for IBM MQ with local scripts as in earlier versions of EntireX. It covers the following topics:
See also Administering the RPC Server for IBM MQ with the Command Central GUI | Command Line.
The following elements are used to set up the RPC Server for IBM MQ:
There are two parts: the RPC server and the IBM® MQ side. The RPC Server for IBM MQ uses the following:
The IBM® MQ base Java classes from IBM.
To run the RPC Server for IBM MQ, you need either the base Java classes or a full installation of IBM® MQ.
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 WS-Stack. Therefore 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.
The default name for the configuration file is
entirex.wmqbridge.properties. The RPC Server 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 RPC Server for IBM MQ.
The start script for the RPC Server for IBM MQ is called wmqbridge.bsh (UNIX) or wmqbridge.bat (Windows) and is provided in the bin folder of the installation directory. You may customize this file. The script uses the configuration file entirex.wmqBridge.properties in the folder etc. The RPC Server for IBM MQ itself is contained in the file entirex.jar.
The RPC server side of the RPC Server for IBM MQ is configured like the RPC Server for Java. The RPC Server for IBM MQ 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.
| Property Name | Parameter | Default | 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 |
-broker |
localhost |
Broker ID. See URL-style Broker ID. | |||||||||||||||
entirex.server.compresslevel |
-compresslevel |
0 (no compression)
|
|
|||||||||||||||
entirex.server.fixedservers |
no |
|
||||||||||||||||
-help |
Display usage of the command-line parameters. | |||||||||||||||||
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.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. To disable password encryption, set entirex.server.passwordencrypt=no.Default: 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 RPC Server for Java 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 access to the broker. | |||||||||||||||
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 IBM® 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 that is used for MQGET
calls).
|
|
entirex.wmqbridge.outputqueue |
-wmqoutqueue |
Name of output queue (the queue that is used for MQPUT
calls).
|
|
entirex.wmqbridge.userid |
-wmquser |
UserID for MQ Server. | |
entirex.wmqbridge.password |
-wmqpassword |
Password for MQ Server. | |
entirex.wmqbridge.waittime |
Wait interval for MQGET call in milliseconds.
|
||
entirex.wmqbridge.userexit |
Class name for user exit. | ||
entirex.wmqbridge.userexit.classpath |
URL of the classpath for user exit (optional). | ||
entirex.wmqbridge.ccsid |
platform encoding | Coded Character Set Identification used by the
RPC Server 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.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 that is sent to MQ
(if entirex.bridge.xmm is used).
|
|
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). |
The RPC Server for IBM MQ 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.
To start the RPC Server for IBM MQ
Use the Start Script.
Or:
Under Windows you can use the RPC Server for IBM MQ as a Windows Service. See Running an EntireX RPC Server as a Windows Service.
To stop the RPC Server for IBM MQ
Use the command stopService. See Stop Running Services in Command Central's Command-line Interface.
Or:
Stop the service using Command Central's Graphical User Interface. See Stopping a Service.
Or:
Use the command-line utility etbcmd. See ETBCMD under
z/OS |
UNIX |
Windows |
z/VSE |
BS2000.
Or:
Use CTRL-C in the session where you started the RPC server instance.
Or:
Under UNIX, enter command kill -.
process-id
To use SSL with RPC Server 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
On the RPC server side you 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.
On the RPC server side, an SSL client is configured. 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 RPC server side 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:
For general information see Running an EntireX RPC Server as a Windows Service.
To run the RPC Server for IBM MQ as a Windows Service
Customize the Start Script according to your system installation.
Note:
The script must pass external parameters to the RPC server and use the reduced signaling of the JVM (option -Xrs):
java -Xrs com.softwareag.entirex.rpcbridge.WMQBridge %*
If -Xrs is not used, the JVM stops and an entry 10164002 is written to the event log when the user logs off from Windows.
See also Starting the RPC Server.
Test your RPC server to see whether it will start if you run your script file.
Use the EntireX RPC Service Tool and install the RPCService with some meaningful extension, for example MyServer. If your Start Script is wmqbridge.bat, the command will be
RPCService -install -ext MyServer -script install_path\EntireX\bin\wmqbridge.bat
The log file will be called RPCservice_MyServer.log.
In Windows Services menu (Control Panel > Administrative Tools > Services) select the service: Software AG EntireX RPC Service [MyServer] and change the property Startup Type from "Manual" to "Automatic".
The trace level for the RPC server side is controlled by the
usual entirex.trace property.
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, default is standard output.
All properties can be set in the configuration file.