Configuration Guide
|
Ultra Messaging (Version 6.12.1)
© 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.
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.
You can use the following ways to set attributes with configuration options:
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.
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:
Before discussing how UM options can be set, some terminology is in order.
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().
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.
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.
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.
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.
There are two ways to read a plain text configuration file to set values in current default attributes.
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()).
(You can still use the lbm_config() API on a different file to make additional changes.)
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: