Informatica

Ultra Messaging (Version 6.16)

Configuration Guide

[ Single-page HTML ] | [ PDF ]

Introduction

This document describes how Ultra Messaging-based user applications are configured.

For information on configuring other UM components, see:

For policies and procedures related to Ultra Messaging Technical Support, see UM Support.

This software and documentation are provided only under a separate license agreement containing restrictions on use and disclosure. No part of this document may be reproduced or transmitted in any form, by any means (electronic, photocopying, recording or otherwise) without prior consent of Informatica LLC.

A current list of Informatica trademarks is available on the web at https://www.informatica.com/trademarks.html.

Portions of this software and/or documentation are subject to copyright held by third parties. Required third party notices are included with the product.

This software is protected by patents as detailed at https://www.informatica.com/legal/patents.html.

The information in this documentation is subject to change without notice. If you find any problems in this documentation, please report them to us in writing at Informatica LLC 2100 Seaport Blvd. Redwood City, CA 94063.

Informatica products are warranted according to the terms and conditions of the agreements under which they are provided.
INFORMATICA LLC PROVIDES THE INFORMATION IN THIS DOCUMENT "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND ANY WARRANTY OR CONDITION OF NON-INFRINGEMENT.

This document assumes familiarity with the UM Concepts Guide.

See UM Glossary for Ultra Messaging terminology, abbreviations, and acronyms.

Configuration Overview <-

There are different kinds of configuration.

Applications create UM objects (contexts, sources, receivers) using the UM library. Those objects must be configured to control their operation and behavior using "LBM configuration options". An application typically uses an "LBM configuration file" in either XML or flat format.
Informatica daemons (e.g. SRS, Store, DRO) are configured using program-specific configuration files in XML format.
Informatica daemons (e.g. SRS, Store, DRO) also internally create UM objects (contexts, sources, receivers) using the UM library. Those objects must also be configured using one or more LBM configuration files.

This document describes the options available for LBM configuration.

For Ultra Messaging applications, you can set a variety of operational options to customize the application's behavior or performance. You assign values to these options in configuration files or by using API calls. You can assign option values to objects upon or after object creation. Within an object, the implemented option values are referred to as attributes.

Ultra Messaging uses reasonable default values for configuration options, enabling applications to run "out of the box." However, expect to customize Ultra Messaging options to optimize your operating environment. You can use different ways to configure option default and customized value assignments.

Assignment Methods <-

You can use the following ways to set attributes with configuration options:

plain text configuration file: The simplest way to configure an application, a plain text configuration file (sometimes called a "flat" file) allows you to re-define UM's default berhaviors. These new defaults are read into a process-global configuration buffer, and are used as UM objects are created. Note that after reading a plain text configuration file, an application can still override the defaults on a per-object basis using UM's API. NOTE: Informatica recommends the use of XML configuration files for their added flexibility.

XML configuration file: An XML configuration file provides a more sophisticated way to set UM's default behavior, allowing users to customize UM's default behavior on a per-application and/or per-object basis. And while an application can still override the defaults, restrictions can be imposed, constraining applications to only certain options and certain values of those options. NOTE: Informatica recommends the use of XML configuration files.

attributes objects API: The application program can call API functions to create UM attributes objects and set configuration options in those objects. The attributes objects are then used to create other UM messaging objects to set those options.

: Alternatively, there are API functions which allow you to modify a subset of configurable options on already-created UM messaging objects. NOTE: Informatica recommends the use of XML configuration files so that configuration can be adjusted without changing source code.

The following image shows the different ways Ultra Messaging stores and assigns option values before, during, and after primitive object creation. Primitive objects are sources, receivers, wildcard receivers, event queues, contexts, or HFX objects. The ultimate result is a primitive object with the assigned values residing in current attributes.

The initial default attributes is the set of factory defaults in Ultra Messaging. At process initialization time, these factory defaults are copied into a set of internal process-global attribute structures (current default attributes).

An application can modify desired options by reading a plaintext configuration file. UM will store these values in current default attributes, overwriting the factory defaults.

An instantiated primitive object uses values from current default attributes, the XML config table, and the custom attributes object, and then holds the results in current attributes.

An XML configuration file can pass its setting to an object being created either by directly populating the XML config table, or by creating a custom attributes object.

Assignment Flow <-

The above diagram implies, but does not fully explain, the flow of attribute value assignment that UM performs when an application creates a primitive object. This flow is described below, and is important in understanding how and when default values are overridden:

If applicable, copy plain text configuration file values to current process-global default attributes.
Start creating object.
Custom attributes object(s) created/populated (if applicable).
If lbm_*_create() has a NULL attr, copy current default attributes into current attributes. Otherwise, copy custom attributes object values into current attributes.
Read applicable options from the XML config table into the current attributes. Do not overwrite options set with lbm_config(), or lbm_*_attr_setopt(), which were tagged when modified.
Finish object creation.
current attributes can be changed further (only certain options) via lbm_*_setopt().

Definitions <-

Before discussing how UM options can be set, some terminology is in order.

Option: A single configuration item that controls some aspect of UM operation. An option typically resides in a configuration file, but can also be assigned a value via API call. We use options to assign values to an object's attributes.

Attribute: An operational characteristic of an object. An attribute's value is set by an option, hence, there is a one-to-one correspondence between options and attributes. (Note: This use of the term "attribute" is unrelated to, and not to be confused with, "attribute" in XML syntax. In this document, we refer to the latter as "XML attribute".)

XML attribute: See above. In XML syntax, XML attributes are parameters for XML elements.

Custom attributes object: A UM object that contains custom attribute values (set by options) for a specific UM object. Separate (and multiple) sets of attributes can exist for each application, though only one can be used when creating a primitive object.

Initial default attributes: The default attributes values built into UM. UM and your applications use these if you have not set any options for the attributes.

Primitive object: Specifically, an object that is a source, receiver, wildcard receiver, event queue, context, or HFX object.

Configuration file: This comes in two types: XML and plain text. Configuration files contain assigned values for options, but the different types are read/copied at different times during the creation of an object.

XML config table: Contains option values that are read from the XML configuration file.

Current default attributes: The attributes values used to create an object in the absence of custom attributes values.

Current attributes: The attribute values for an instantiated UM object that control the current operation of that object.

Scope: The type of object to which an option can apply. Possible scopes are context, source, receiver, wildcard_receiver, event_queue, and hfx.

Which Method Should I Use? <-

Informatica generally recommends the use of XML configuration files. They provide a flexible method of controlling configuration that doesn't require changing source code.

For example, a publisher can map sources to transport sessions by topic name using regular expression pattern matching. Other configurations can be customized to specific applications.

Configuration Error Handling <-

Prior to UM version 6.13, an error in a configuration file typically resulted in the remainder of the configuration file not being processed.

As of UM version 6.13, UM will attempt to process the entire configuration file, even if there are errors. Any lines which cannot be properly parsed will generate an error to the logger, but subsequent lines will still be processed.

Note that the API function will return a bad status to indicate that one or more errors were encountered, and the application can decide what to do. For example:

err = lbm_config("test.cfg");
if (err == LBM_FAILURE) {
  fprintf(stderr, "Warning, ignoring lbm_config error: %s\n", lbm_errmsg());
}

The last error encountered will be returned by the lbm_errmsg() call. Note that all errors are also reported via the UM logger callback; see lbm_log(). Thus, if the "test.cfg" file has two errors in it, both will be logged to the logger, and the last one is returned by lbm_errmsg().

Why Ignore Errors?

Normally an application would want to exit if lbm_config() returned an error. However, here is an example use case for considering it a warning and continuing with the application execution.

Let's imagine that future UM version 42.0 has a new configuration option, "receiver predict_next_message 1", which allows receivers to receive messages before they are sent, achieving the elusive goal of negative latency. The user could include this option in the master configuration file, and all applications at version 42.0 and beyond will benefit from negative latencies. Applications at version 6.13 through 41 will log an error when they encounter that option, but will continue to load the rest of the configuration file, and will run normally.

Thus, new configuration options can be included in a master configuration file, and older versions will log warnings about but will still run.

Note however that any pre-6.13 applications will return an error and not process the rest of the configuration file.

Also note that the user must be very careful to examine the error messages logged to ensure that all errors are expected (due to earlier versions not understanding options included for later versions). If lbm_config errors are ignored, it would be easy to overlook a mistyped option and have it not take effect.

XML Errors

If an XML configuration file is being used, the basic XML structure must be valid for the parser to read the whole file.

For example:

<?xml version="1.0" ?>
<um-configuration version="1.0">
  <mistake />
  <applications>
    <application>
      <contexts>
        <context>
          <options type="context">
            <option name="request_tcp_port_low" default-value="13000">
            <option name="request_tcp_port_high" default-value="13010">
            </option>
          </options>
        </context>
      </contexts>
    </application>
  </applications>
</um-configuration>

This XML file will be rejected without applying the two request port options because of the "<mistake />" element.

However, if the XML elements are properly coded, invalid option names or values will follow the same pattern as flat configuration files: errors will be reported, and parsing will continue.

For example:

<?xml version="1.0" ?>
<um-configuration version="1.0">
  <applications>
    <application>
      <contexts>
        <context>
          <options type="context">
            <option name="mistake" default-value="1">
            <option name="request_tcp_port_low" default-value="13000">
            <option name="request_tcp_port_high" default-value="13010">
            </option>
          </options>
        </context>
      </contexts>
    </application>
  </applications>
</um-configuration>

This XML file will be accepted and the request TCP port range will be applied. The "mistake" option will log an error. And the API will return LBM_FAILURE, which the application can decide to ignore.

Daemon Config Files

This behavior of continuing execution in the event of errors is extended to the UMP Store and the DRO for UM configuration configuration files. That is, an error found in a UM configuration file will be logged, and the daemon will continue to run. Users should again be very careful to examine log files to prevent mistyped options from leading to undesired behavior.

However, for the Store and DRO configuration XML files, this "log and continue" error handling is not used. Errors in the Store or DRO configuration files will prevent them from running.

Host Name Resolution <-

Many of UM's configuration options specify an IP address. Prior to UM version 6.10 these needed to be specified in dotted numeric format. For example, 10.23.19.210. Starting in version 6.10, any configuration option that accepts an IP address can also accept a DNS host name (the few exceptions are noted in the documentation). For example, myhost.mydomain.com. Note that the DNS name system is not necessarily used when host names are specified; for example, most Unix systems will first look up the name in /etc/hosts.

When host names are specified, the name is resolved to an IP address when the configuration option is parsed. If you change the IP address associated with a name, that change will not take effect until the configuration file is re-read, typically by restarting the application.

Configuration Files <-

There are two types of UM Configuration files:

XML Configuration Files - recommended.
Plain Text Configuration Files

You can read Configuration files either by API call, or automatically upon application launch by specifying a file name in an environment variable. See Assignment Methods and Assignment Flow for details on how these options replace or override default values.

There are some UM configuration options which cannot be set via configuration files. These are options whose values are function pointers or data structures. These options can only be set via API functions *_setopt. For example, context resolver_source_notification_function has a function pointer as its value.