Guide to Queuing
Getting Started

To install Ultra Messaging and Ultra Messaging options, download the Ultra Messaging installation files for your specific operating system and platform.

Ultra Messaging Queuing Edition installation files include the following files:

Core installation script
The core installation program or script is a self-extracting executable file you run to extract Ultra Messaging files to a host system. Use the core installation script that matches your operating system, version, and chip set combination.
Documentation
The compressed documentation files each contain the complete documentation set.
Option packages
Option packages include support for Java and .NET.
In addition to the installation files, you also receive the following files by email:
Software Download Instructions
Description of general procedure for downloading Informatica software.
License
You must supply the license to run Ultra Messaging applications.


Requirements  <-

Ultra Messaging runs on a variety of current operating systems and chip sets.


Minimum System Requirements  <-

For Ultra Messaging, there are no strict requirements for hardware computing capacity and storage capacity. Such requirements depend on client applications and on configuration of clients and brokers.


Software Requirements  <-

UMQ brokers require Java SE Development Kit 6 or later. Informatica recommends Java SE Development Kit 7.

UMQ on UNIX requires an installation of a libstdc++ Standard C++ Library.


Single Node Installation  <-

To install UMQ on a host for a single-node deployment, perform the following steps. All examples are Linux examples.

  1. Consult your Informatica sales engineer for the download procedure and appropriate files for your specific operating system and platform. Informatica sends you the Ultra Messaging license file by email.
  2. Download the installation files to the installation directory and run the installation script.

  3. Locate the documentation .zip package and unzip it into the installation directory. For example:

    unzip UMQ_6.16.1_doc.zip -d <InstallDir>/
  4. Copy the license file into a location that is accessible to the Ultra Messaging library.

  5. Set the Ultra Messaging license environment variable to the full path name of the license file. For example: 

    export LBM_LICENSE_FILENAME=/path/filename.lic

  6. Add the library to the library path. For example, use the following line: 
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<InstallDir>/UMQ_6.16.1/<platform>/lib


Starting a Single-Node Queuing System  <-

After you have installed Ultra Messaging, run the daemons and sample applications to verify successful installation.

  1. Start the broker with the following command: 

    <InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0/bin/activemq start

  2. Start the sample receiving application with the following commands: 

    <InstallDir>/UMQ_6.16.1/<platform>/bin/umqrcv -B <brokerIP:port> -r 10 QueueDestA

  3. In a second command window, start the sample sending application with the following command: 

    <InstallDir>/UMQ_6.16.1/<platform>/bin/umqsrc -B <brokerIP:port> -M 10 QueueDestA

    In the sending application window, you see output similar to the following example display: 

    0 msgs/sec -> 1 msgs/ivl, 0 msec ivl
Using flight size of 1000
Not using UME Late Join.
Using UMQ Message Stability Notification. Will not display events. Delaying for 1 second
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0][Inst: 10.29.3.49/5672] [0] ctx registration. ID 92da70611c65ece4 Flags 0
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] ctx registration complete. ID 92da70611c65ece4 Flags 0
UMQ "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] src registration complete. Flags 0
Sending 10 messages of size 25 bytes to topic [QueueDestA]
Sent 10 messages of size 25 bytes in 1.003 seconds.
1.003 secs. 0.009965 Kmsgs/sec. 1.993 Kbps
[BROKER], sent 10/1660, app sent 10 stable 0 inflight 10 Lingering for 5 seconds...
Deleting source
Deleting context

    In the receiving application window, you see messages being received, as in the following example display: 

    Request port binding disabled, no immediate messaging target.
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0][Inst: 10.29.3.49/5672] [0] ctx registration. ID a1387d282ba177d2 Flags 0
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] ctx registration complete. ID a1387d282ba177d2 Flags 0
[QueueDestA][(Broker: Default IP: 10.29.3.49 PORT: 5672 )] UMQ "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] registration complete. AssignID 0. Flags 0
1.001 secs. 0
1.001 secs. 0
1.001 secs. 0
1.001 secs. 0
1.001 secs. 0
1.001 secs. 0.009991 Kmsgs/sec.
Quitting.... received 10 messages (0 reassigned, 0 resubmitted)


Shutting Down a Single-Node Broker  <-

Shut down the broker with the following command: 

<InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0/bin/activemq stop
Kmsgs/sec. 0 Kmsgs/sec. 0 Kmsgs/sec. 0 Kmsgs/sec. 0 Kmsgs/sec. 0
Kbps Kbps Kbps Kbps Kbps 1.998 Kbps


High Availability Installation  <-

A high-availability queuing system requires an Ultra Messaging installation on three hosts. To install UMQ on hosts for a high-availability queuing system, perform the following steps. All examples are Linux examples.

Note
Each node has a unique configuration file, but these configuration files are each in the same path- named directory. Therefore, the three installations must not be on the same NFS mounted disk.
  1. Consult your Informatica sales engineer for the download procedure and appropriate files for your specific operating system and platform. Informatica sends you the Ultra Messaging license file by email.
  2. Download the installation files to the installation directory of the first broker host and run the installation script.

  3. Locate the documentation .zip package and unzip it into the installation directory. For example: 

    unzip UMQ_6.16.1_doc.zip -d <InstallDir>/

  4. Copy the license file into a location that is accessible to the Ultra Messaging library.

  5. Set the Ultra Messaging license environment variable to the full path name of the license file. For example: 

    export LBM_LICENSE_FILENAME=/path/filename.lic

  6. Add the library to the library path. For example, use the following line: 

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:<InstallDir>/UMQ_6.16.1/<platform>/lib

  7. A high availability broker node contains a working configuration directory and a default configuration directory for each unique node in a multiple node arrangement.

    Create the store repository directories. Then, depending on which host you are configuring, copy the default broker1, broker2, or broker3 configuration file to the working configuration directory with the following example commands: 

    mkdir <InstallDir>/UMQ_6.16.1/<platform>/broker/store/
mkdir <InstallDir>/UMQ_6.16.1/<platform>/broker/store/cache
mkdir <InstallDir>/UMQ_6.16.1/<platform>/broker/store/state
cp <InstallDir>/UMQ_6.16.1/<platform>/broker/deployments/three_replicating_brokers/broker1/um.xml <InstallDir>/UMQ_6.16.1/<platform>/broker

  8. Edit the um.xml configuration file that is in <InstallDir>/UMQ_6.16.1/<platform>/broker/ to set the resolver IP addresses and ports for all three nodes, as shown in the following example:

    <option name="resolver_unicast_daemon" default-value="10.33.200.201:21212"/>
    <option name="resolver_unicast_daemon" default-value="10.33.200.202:21212"/>
    <option name="resolver_unicast_daemon" default-value="10.33.200.203:21212"/>

    Also, set the local broker host interface addresses to the IP address of a network interface on the current broker host that has connectivity to the other broker hosts, and to the servers where the clients run, as shown in the following example:

    <option name="resolver_multicast_interface" default-value="10.33.200.201"/>
    <option name="resolver_unicast_interface" default-value="10.33.200.201"/>
    <option name="request_tcp_interface" default-value="10.33.200.201"/>
    <option name="response_tcp_interface" default-value="10.33.200.201 "/>
    Note
    Do not change any values in the broker um.xml configuration file other than interfaces and addresses shown in this step.

  9. Depending on which host you are configuring, copy the default broker1, broker2, or broker3 stored.xml configuration file to the working configuration directory with the following broker1 example command: 

    cp <InstallDir>/UMQ_6.16.1/<platform>/broker/deployments/three_replicating_brokers/broker1/store/stored.xml <InstallDir>/UMQ_6.16.1/<platform>/broker/store

  10. Depending on which host you are configuring, copy the default broker1, broker2, or broker3 ActiveMQ configuration file to the working configuration directory with the following broker1 example command: 
    cp <InstallDir>/UMQ_6.16.1/<platform>/broker/deployments/three_replicating_brokers/broker1/apache-activemq-5.10.0/conf/activemq.xml <InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0/conf

  11. Repeat steps 1-10 for the second broker host, and again for the third broker host, making sure to copy the configuration files from ...three_replication_brokers/broker2/... or ...three_replication_brokers/broker3/... as needed.


Starting a High Availability Queuing System  <-

After you have installed Ultra Messaging, run the daemons and sample applications to verify successful installation.

  1. On the first host, start the lbmrd resolver daemon with the following example command: 
    <InstallDir>/UMQ_6.16.1/<platform>/bin/lbmrd -i 10.33.200.201 -p 21212 &
  2. Start the umestored daemon with the following example commands: 
    cd <InstallDir>/UMQ_6.16.1/<platform>/broker/store
<InstallDir>/UMQ_6.16.1/<platform>/bin/umestored stored.xml &
  3. Start the broker with the following example commands: 
    cd <InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0
<InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0/bin/activemq start
  4. Repeat steps 1-3 on the second and third host.
  5. Start the sample receiving application with the following commands: 
    <InstallDir>/UMQ_6.16.1/<platform>/bin/umqrcv -B <broker1IP:port1,broker2IP:port2,broker3IP:port3> -r 10 QueueDestA

  6. In a second command window, start the sample sending application with the following command: 

    <InstallDir>/UMQ_6.16.1/<platform>/bin/umqsrc -B <broker1IP:port1,broker2IP:port2,broker3IP:port3> -M 10 QueueDestA

    In the sending application window, you see output similar to the following example display: 

    0 msgs/sec -> 1 msgs/ivl, 0 msec ivl
Using flight size of 1000
Not using UME Late Join.
Using UMQ Message Stability Notification. Will not display events. Delaying for 1 second
LOG Level 4: Core-8901-03: BROKER: Disconnect detected while establishing broker connection (10.29.3.85:5672).
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0][Inst: 10.29.3.49/5672] [0] ctx registration. ID f544ce868d92a087 Flags 0
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] ctx registration complete. ID f544ce868d92a087 Flags 0
UMQ "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] src registration complete. Flags 0
Sending 10 messages of size 25 bytes to topic [QueueTstA] Sent 10 messages of size 25 bytes in 1.003 seconds. 1.003 secs. 0.009972 Kmsgs/sec. 1.994 Kbps
[BROKER], sent 10/1660, app sent 10 stable 0 inflight 10 Lingering for 5 seconds...
Deleting source Deleting context

    In the receiving application window, you see messages being received, as in the following example display: 

    Request port binding disabled, no immediate messaging target.
LOG Level 4: Core-8901-03: BROKER: Disconnect detected while establishing broker connection (10.29.3.85:5672).
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0][Inst: 10.29.3.49/5672] [0] ctx registration. ID a8c3c09a7ccb1476 Flags 0
UMQ queue "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] ctx registration complete. ID a8c3c09a7ccb1476 Flags 0
[QueueTstA][(Broker: Default IP: 10.29.3.49 PORT: 5672 )] UMQ "(Broker: Default IP: 10.29.3.49 PORT: 5672 )"[0] registration complete. AssignID 0. Flags 0
1.001 secs. 0      Kmsgs/sec.  0          Kbps
1.001 secs. 0      Kmsgs/sec.  0          Kbps
1.001 secs. 0      Kmsgs/sec.  0          Kbps
1.001 secs. 0      Kmsgs/sec.  0          Kbps
1.001 secs. 0      Kmsgs/sec.  0          Kbps
1.001 secs. 0.007993 Kmsgs/sec.  1.599 Kbps
1.001 secs. 0.001998 Kmsgs/sec.  0.3996 Kbps
Quitting.... received 10 messages (0 reassigned, 0 resubmitted)


Shutting Down High Availability Nodes  <-

To shut down a high availability queuing system node, perform the following steps:

  1. Shut down the broker with the following command: 
    <InstallDir>/UMQ_6.16.1/<platform>/broker/apache-activemq-5.10.0/bin/activemq stop
  2. Shut down the umestored process.
  3. Shut down the lbmrd process.

  4. Repeat steps 1-3 for the remaining nodes.


Queuing Upgrade Considerations  <-

When UMQ 6.8 was released, it added some capabilities and deprecated others, when compared with pre-6.8 UMQ. You might need to change how you set configuration options or change function calls in your application code.

If the application does not use UMQ-specific features other than Ultra Load Balancing (ULB), ignore this section. This section is a supplement to upgrade guidelines in the Release Notes and does not repeat the guidelines therein.


Configuration Options  <-

When you upgrade client applications from versions prior to 6.8, you must change the following configuration settings:

  • Contexts that contain queue sources or receivers must specify a list of brokers with the broker option.

  • Sources in a brokered context must set source option transport to BROKER.


Application Code  <-

You might need to make changes to client application source code.

You do not need to change any API calls unless the functions are deprecated. However, you must recompile client applications from versions prior to 6.8.

UMQ client applications from versions prior to 6.8 might use the same context for both queue sources or receivers and topic sources or receivers. In such cases, you must create separate contexts for queue applications and non-queue applications.

For more information, see Deprecated and Unavailable Features.