Configuration Guide
|
Ultra Messaging (Version 6.16.1)
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.
(C) Copyright 2004,2023 Informatica Inc. All Rights Reserved.
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.
There are different kinds of configuration.
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.
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.
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.
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:
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:
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:
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.
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.