Configuration Guide

Informatica

Ultra Messaging (Version 6.12.1)



Configuration Guide



Single-page HTML ]  |  [ PDF ]

Introduction  <-

© Copyright Informatica LLC 2004-2019.

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

For information on configuring other UM components, see:

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

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

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.

Attr_Config_and_XML.png

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:

  1. If applicable, copy plain text configuration file values to current process-global default attributes.
  2. Start creating object.
  3. Custom attributes object(s) created/populated (if applicable).
  4. If lbm_*_create() has a NULL attr, copy current default attributes into current attributes. Otherwise, copy custom attributes object values into current attributes.
  5. 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.
  6. Finish object creation.
  7. 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?  <-

For the four basic assignment methods listed above, following are some scenarios where specific methods are selected.

  • To change a default option value and apply it to all objects you create, call lbm_config() for one or more configuration files. For example, to use LBT-RM rather than TCP for all sources, create a plain text configuration file containing

    source transport LBTRM

    and pass its file name to lbm_config().

    Note
    The C API offers APIs lbm_*_attr_create_default() to create an attribute object with initial factory default values. This is unaffected by default overrides from configuration files. No such corresponding method exists for the Java or .NET APIs.
  • To customize specific options before an object is created for a specific object instance, use a custom attributes object. Also, you can assign XML data to the XML config table directly from your application via lbm_config_xml_string().
  • To create sets of custom values to be used when creating primitive objects, call lbm_config_xml_file() and specify an XML configuration file. This is useful for setting specific default options on a per-topic or per-context basis, which cannot be done with a plain text configuration file. For an example where a sending application uses specific options and values, create an XML configuration file with the application's name (optional) that specifies those options and values. Then pass the XML file name and application name to lbm_config_xml_file().
  • To change an option after an object is created, modify the current attributes for the object. (Note that many options cannot be changed after an object has been created.)

These methods can be used in combination. See Assignment Methods to see the relationships between attributes and the various UM API function calls that affect them.


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:

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. See Options that Cannot Be Set Via Configuration Files for the full list.


Plain Text Configuration Files  <-

The plain text configuration file (sometimes called a "flat" file), when invoked, writes option values into UM's current default attributes. These are then read and used in the creation of all objects.

See Example Configuration Scenarios for example configuration files.


Reading Plain Text Configuration Files  <-

There are two ways to read a plain text configuration file to set values in current default attributes.

API function lbm_config()
You can call the API multiple times with different file names to set configuration options in phases.

When you create UM objects (such as a context or receiver), UM sets attributes for that object using the current default attributes. Hence, you must call lbm_config() before creating objects (lbm_*_create()).

Environment variable LBM_DEFAULT_CONFIG_FILE
Reads configuration file when your application is started. You can set this variable to a full pathname or a URL; for example:
export LBM_DEFAULT_CONFIG_FILE=/home/lbm/lbtrm.cfg

(You can still use the lbm_config() API on a different file to make additional changes.)


Plain Text Configuration File Format  <-

A plain text configuration file contains lines that each take the form:

scope_keyword option_name option_value

where:

scope_keyword - the scope to which the option applies,

option_name - the predefined name for the option, and

option_value - the new value to be assigned to that option.

Allowable values for these parameters are given throughout the rest of this document. Any text following a hash character # (also known as a pound sign, number sign, or octothorp) is interpreted as comment text and is ignored.

For example:

# Set transport_tcp_port_low to 4901
context transport_tcp_port_low 4901
# And set transport_tcp_port_high to 4920
context transport_tcp_port_high 4920
Note
For plain text configuration files, do not enclose any fields in double quotation marks (").