1.1.1. Assignment Methods

UM provides four basic methods for using configuration options to set attributes:

• XML configuration files - customized defaults used during object creation

• plain text configuration files - a different manner of customized defaults, also used during object creation

• attributes objects - application-specific option values used during object creation

• function calls (setopt) - used after object creation

Figure 1-1 shows the different ways option values are stored and assigned before, during, and after primitive object creation (primitive objects being sources, receivers, wildcard receivers, event queues, contexts, or HFX objects). The ultimate result is a primitive object created with the desired values residing in current attributes.

The initial default attributes is the set of factory defaults residing in UM. The current default attributes are derived from the initial default attributes, but modified by option setting in the plain text configuration file. This is the starting point for all created primitive objects.

An instantiated primitive object has its attribute settings held in current attributes, which are influenced by the current default attributes, the XML config table, and, if applicable, any settings stored in a custom attributes objects.

An XML configuration file can pass its setting to an object being created in two ways: by directly populating UM's XML config table, or by creating a custom attributes object with its settings.

1.1.2. 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 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().

1.1.3. 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 a function 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.

1.1.4. 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 functions lbm_*_attr_create_default() to change a current default value back to the initial (factory) default value. 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. Figure 1-1 illustrates the relationships between attributes and the various UM API function calls that affect them.

1.1.5. Configuration Files

There are two types of UM Configuration files:

• Plain Text Configuration Files

• XML Configuration Files

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

1.2.1. 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 function 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() function on a different file to make additional changes.)

1.2.2. 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 octothorpe) 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
       

1.3.1. Reading XML Configuration Files

There are several ways to read an XML configuration file to assign values while creating a primitive object.

• API function lbm_config_xml_file() - reads an XML configuration file into UM's XML config table. Call this before the primitive create function. This does not change the current default attributes.

• API function lbm_config_xml_string() - populates the XML config table directly from your application. Call this before the primitive create function. This does not change the current default attributes.

• API function lbm_*_attr_create_from_XML() - creates a custom attributes object containing the values from an XML configuration file. The values can then be applied to a primitive object being created by calling function lbm_*_create() and specifying this custom attributes object in the second parameter.

• Environment variable LBM_XML_CONFIG_FILENAME - reads the file into UM's XML config table. These settings are then is available to all applications when they start.

  export LBM_XML_CONFIG_FILENAME=filename

• Environment variable LBM_XML_CONFIG_APPNAME - reads options for a specific application from the above variable's filename. This initiates the specified application's configuration; set this environment variable for every application.

  export LBM_XML_CONFIG_APPNAME=application_name

• Environment variable LBM_UMM_INFO - initiates UMM Daemon to read options for an application and user from the above variable's filename. Set this variable for every application/user combination, in this format:

  export LBM_UMM_INFO=application_name:user_name:password@ip:port

1.3.2. Using XML Configuration Files With a UM Application

The following procedure describes a general approach to implementing XML configuration files.

1. Create an XML configuration file using an XML editor or text editor. Just for this example, name the file, UM_CONFIG.XML.

2. Insert any desired templates in the <templates> element to hold configuration option values shared by multiple applications or primitive UM objects (context, source, receiver, wildcard receiver or event queue). You can create and apply multiple templates to applications and primitive UM objects, however, if the same option appears in multiple templates, the option value in the last template overrides the option value in the previous template. See <templates>.

3. Insert an <application> element for your UM application in the <applications> element and include any relevant templates created in the previous step. Just for this example, name the application, SENDAPP. See <applications>.

4. Within the <Contexts> element, configure the application's <Context> element and context options. And since our example application, SENDAPP is a sending application, also configure its Source options. (If this was a receiving application, you would configure Receiver or Wildcard Receiver options. If your application creates multiple Contexts, enter multiple <Context> elements within the Contexts element, inserting the appropriate source, receiver or wildcard receiver options. See <contexts>.

5. Configure the applications Event Queue options. See <event-queues>

6. Save the XML configuration file, UM_CONFIG.XML, and load it onto the machine where the application (SENDAPP) runs.

7. Set the following environment variables on the machine where SENDAPP runs.

   • Set LBM_XML_CONFIG_FILENAME to UM_CONFIG.XML.

   • Set LBM_XML_CONFIG_APPNAME to SENDAPP.

   • Optionally, you could also use lbm_config_xml_file(UM_CONFIG.XML,SENDAPP) in the SENDAPP source.

8. Start SENDAPP.

1.3.3. XML Configuration File Format

An XML Configuration File follows standard XML conventions. Element declarations or a pointer to a DTD file are not needed, as these are handled by UM.

An XML configuration file generally comprises two primary elements: templates and applications. Organized and contained within these are option value assignments. Applications containers let you set options for specific applications. To provide more global control over applications, or to simply reduce repetition, you can create templates to hold option settings that are to be used in one or more different applications.

XML configuration files use the high-level structure shown in the following example. This example includes only some container elements, and no options.

<um-configuration version="1.0"/>
  <templates>
    <template name="SENDING">
      <options type="source">
      </options>
      <options type="context">
      </options>
    </template>
   </templates>
  <applications>
    <application name="SENDING-TOPIC1">
      <contexts>
        <context name="SENDING-LBTRM">
          <sources>
            <topic topicname="TOPIC1">
              <options type="source">
              </options>
            </topic>
          </sources>
        </context>
      </contexts>
      <event-queues>
        <event-queue/>
        <event-queue name="EQ-1"/>
      </event-queues>
    </application>
  </applications>
</um-configuration>
       

Following are descriptions of the XML configuration file elements.

• <um-configuration>

• <license>

• <options>

• <option>

• <allow>

• <deny>

• <templates>

• <template>

• <applications>

• <application>

• <contexts>

• <context>

• <sources>

• <topic>

• <receivers>

• <wildcard-receivers>

• <wildcard-receiver>

• <event-queues>

• <event-queue>

• <hfxs>

• <application-data>

See also Sample XML Configuration File and XML Configuration File DTD.

<um-configuration version="1.0">
  <applications>
    <application>
      . . .
      . . .
    </application>
  </applications>
</um-configuration>
           

<um-configuration>
  <license format=filename>
  path/license-file-name
  </license>
  <applications>
    <application>
      . . . 
           

      <options type="context">
        <option/>
        . . .
        <application-data/>
      </options>
           

    <option default-value="tcp" name="transport" order="deny,allow">
      <deny>LBTRU</deny>
    </option>
           

    <option default-value="tcp" name="transport" order="allow,deny">
      <allow>LBTRU</allow>
      <allow>LBTRM</allow>
    </option>
           

    <option default-value="tcp" name="transport" order="allow,deny">
      <allow>LBTRU</allow>
      <allow>LBTRM</allow>
    </option>
           

    <option default-value="tcp" name="transport" order="deny,allow">
      <deny>LBTRU</deny>
    </option>
           

  <templates>
    <template name="SENDING">
      <options/>
    </template>
  </templates>               
           

  <templates>
    <template name="SENDING",name="SENDING-LBTRM">
      <options/>
    </template>
  </templates>               
           

  <applications>
    <application name="SENDING-IXCM-LBTRM" template="SENDING">
      <contexts/>
      <event-queues/>
      <application-data/>
    </application>
  </applications>
           

  <applications>
    <application name="SENDING-IXCM-LBTRM" template="SENDING">
      <application-data/>
      <contexts/>
      <event-queues/>
    </application>
    <application name="SENDING-IXCM-TCP" template="SENDING">
      <application-data/>
      <contexts/>
      <event-queues/>
  </applications>
           

  <applications>
    <application>
      <contexts template="SENDING" order="deny,allow">
        <context name="SENDING-95" template="SENDING-LBTRM" rule="allow">
          <sources/>
          <receivers/>
          <wildcard-receivers/>
          <options/>
        </context>
      </contexts>
      <event-queues/>
      <application-data/>
    </application>
  </applications>
               

  <applications>
    <application>
      <contexts template="SENDING" order="deny,allow">
        <context name="SENDING-95" template="SENDING-LBTRM" rule="allow">
          <sources/>
          <receivers/>
          <wildcard-receivers/>
          <options/>
        </context>
      </contexts>
    </application>
  </applications>
               

  <applications>
    <application>
      <contexts>
        <context>
          <sources template="SENDING" order="deny,allow">
            <topic topicname="ICXM" template="SENDING-LBTRM" rule="allow"/>
          </sources>
          <receivers/>
          <wildcard-receivers/>
          <options/>
        </context>
      </contexts>
      <event-queues/>
      <application-data/>
    </application>
  </applications>
           

<applications>
<application name="Sending">
  <contexts order="deny,allow">
    <context rule="allow" template="Sending-LBTRM">
      <sources order="deny,allow">
        <topic rule="allow" topicname="IXCM">
          <options type="source">
            <option default-value="224.12.5.101" name="transport_lbtrm_multicast_address"/>
          </options>
        </topic>
      </sources>
    </context>
  </contexts>
</application>
</applications>
           

  <applications>
    <application>
      <contexts>
        <context>
          <sources/>
          <receivers template="RECEIVING" order="deny,allow">
            <topic topicname="ICXM" template="RECEIVING" rule="allow"/>
          </receivers>
          <wildcard-receivers/>
          <options/>
        </context>
      <event-queues/>
      <application-data/>
    </application>
  </applications>
           

  <applications>
    <application>
      <contexts>
        <context>
          <sources>
          <receivers/>
          <wildcard-receivers template="RECEIVING" order="deny,allow">
            <wildcard-receiver template="RECEIVING-LBTRM" rule="allow" pattern="I*M" pattern-type="pcre"/>
          </wildcard-receivers>
        <options/>
        </context>
      <event-queues/>
      <application-data/>
    </application>
  </applications>
           

  <applications>
    <application>
      <contexts>
        <context>
          <wildcard-receivers template="RECEIVING" order="deny,allow">
            <wildcard-receiver template="RECEIVING-LBTRM" rule="allow" pattern="I*M" pattern-type="pcre"/>
          </wildcard-receivers>
        </context>
    </application>
  </applications>
           

  <applications>
    <application>
      <contexts/>
      <event-queues template="RECEIVING" order="deny,allow">
        <event-queue name="EVQ-1" template="SENDING-LBTRM" rule="allow"/>
      </event-queues>
      <application-data/>
    </application>
  </applications>
           

  <applications>
    <application>
      <contexts/>
      <event-queues template="RECEIVING" order="deny,allow">
        <event-queue name="EVQ-1" template="SENDING-LBTRM" rule="allow"/>
      </event-queues>
      <application-data/>
    </application>
  </applications>
           

  <applications>
    <application>
      <hfxs template="SENDING" order="deny,allow">
        <topic topicname="ICXM" template="SENDING-LBTRM" rule="allow"/>
      </hfxs>
    </application>
  </applications>
           

  <applications>
    <application name="SENDING-IXCM-LBTRM" template="SENDING">
      <application-data>
      SENDING-IXCM-LBTRM options application data string
      <application-data/>
      <contexts/>
        <options type="context">
          <option/>
          . . .
          <application-data>
          context options application data string
          <application-data/>
        </options>
      <event-queues/>
    </application>
  </applications>
           

1.3.4. Sample XML Configuration File

A sample XML configuration file appears below and has the following notable aspects.

• Contains object attributes for a UM context and source.

• Application name is Sending.

• Uses a template of attributes also called Sending-LBTRM.

• The template, Sending-LBTRM, uses the order attribute for the fd_management_type to allow all file descriptor types except DEVPOLL. However the Sending-LBTRM application further restricts the file descriptor types to exclude EPOLL in addition to DEVPOLL.

<um-configuration version="1.0">
<templates>
<template name="Sending-LBTRM">
  <options type="source">
    <option default-value="0" name="late_join"/>
    <option default-value="500" name="resolver_advertisement_maximum_initial_interval"/>
    <option default-value="5000" name="resolver_advertisement_minimum_initial_duration"/>
    <option default-value="10" name="resolver_advertisement_minimum_initial_interval"/>
    <option default-value="60" name="resolver_advertisement_minimum_sustain_duration"/>
    <option default-value="1000" name="resolver_advertisement_sustain_interval"/>
    <option default-value="lbtrm" name="transport"/>
    <option default-value="14400" name="transport_lbtrm_destination_port"/>
    <option default-value="0.0.0.0" name="transport_lbtrm_multicast_address"/>
  </options>
  <options type="context">
    <option default-value="wsaeventselect" name="fd_management_type" order="deny,allow">
      <deny>wincompport</deny>
    </option>
    <option default-value="5000" name="mim_delivery_control_activity_check_interval"/>
    <option default-value="60000" name="mim_delivery_control_activity_timeout"/>
    <option default-value="6000" name="mim_delivery_control_loss_check_interval"/>
    <option default-value="2000000" name="resolver_initial_advertisement_bps"/>
    <option default-value="2000" name="resolver_initial_advertisements_per_second"/>
    <option default-value="2000" name="resolver_initial_queries_per_second"/>
    <option default-value="2000000" name="resolver_initial_query_bps"/>
  </options>
</template>
</templates>
<applications>
<application name="Sending">
  <contexts order="deny,allow">
    <context rule="allow" template="Sending-LBTRM">
      <sources order="deny,allow">
        <topic rule="allow" topicname="IXCM">
          <options type="source">
            <option default-value="1" name="late_join"/>
            <option default-value="lbtrm" name="transport"/>
            <option default-value="14488" name="transport_lbtrm_destination_port"/>
            <option default-value="224.12.5.101" name="transport_lbtrm_multicast_address"/>
          </options>
        </topic>
      </sources>
      <receivers order="deny,allow"/>
      <wildcard-receivers order="deny,allow"/>
      <options type="context">
        <option default-value="224.9.10.11" name="resolver_multicast_address"/>
        <option default-value="224.9.10.11" name="resolver_multicast_incoming_address"/>
        <option default-value="12965" name="resolver_multicast_incoming_port"/>
        <option default-value="224.9.10.11" name="resolver_multicast_outgoing_address"/>
        <option default-value="12965" name="resolver_multicast_outgoing_port"/>
        <option default-value="12965" name="resolver_multicast_port"/>
        <option default-value="224.9.10.12" name="resolver_multicast_interface"/>
        <option default-value="0" name="resolver_multicast_receiver_socket_buffer"/>
        <option default-value="wsaeventselect" name="fd_management_type" order="deny,allow">
          <deny>wincompport</deny>
        </option>
      </options>
    </context>
  </contexts>
  <event-queues order="deny,allow">
    <event-queue rule="allow">
      <options type="event-queue">
        <option default-value="lbm" name="monitor_transport"/>
        <option default-value="" name="monitor_appid"/>
      </options>
    </event-queue>
  </event-queues>
</application>
</applications>
</um-configuration>

      <sources order="deny,allow">
        <topic topicname="CDEF" rule="deny"/>
        <!-- all other source topics allowed -->
      </sources>
               

      <receivers order="allow,deny">
        <topic topicname="AARM" rule="allow"/>
        <!-- all other receive topics denied -->
      </receivers>
               

      <sources order="deny,allow">
        <topic topicname="ISM" rule="deny"/>
        <topic topicname="IRM" rule="allow"/>
        <topic pattern="*R*" rule="deny"/>
        <topic topicname="SRM" rule="allow"/>
      </sources>
               

1.3.5. XML Configuration File DTD

The XML configuration file DTD is integrated into UM and appears below.

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT um-configuration (license | templates | applications)*>
<!ATTLIST um-configuration version CDATA #REQUIRED>

<!ELEMENT license ( #PCDATA )>
<!ATTLIST license format (filename | string) "string">
<!ATTLIST license xml:space (default | preserve) "default">

<!ELEMENT templates (template*)>

<!ELEMENT template (options+)>
<!ATTLIST template name CDATA #REQUIRED>

<!ELEMENT options (option | application-data)*>
<!ATTLIST options type (event-queue | context | source | receiver | wildcard-receiver | hfx) #IMPLIED>

<!ELEMENT option (allow | deny)*>
<!ATTLIST option name CDATA #REQUIRED>
<!ATTLIST option default-value CDATA #IMPLIED>
<!ATTLIST option order CDATA #IMPLIED>

<!ELEMENT application-data ( #PCDATA )>
<!ATTLIST application-data xml:space (default | preserve) "default">

<!ELEMENT allow ( #PCDATA )>
<!ATTLIST allow xml:space (default | preserve) "default">

<!ELEMENT deny ( #PCDATA )>
<!ATTLIST deny xml:space (default | preserve) "default">

<!ELEMENT applications (application*)>

<!ELEMENT application (contexts | event-queues | hfxs | application-data)+>
<!ATTLIST application name CDATA #IMPLIED>
<!ATTLIST application template CDATA #IMPLIED>

<!ELEMENT contexts (context*)>
<!ATTLIST contexts template CDATA #IMPLIED>
<!ATTLIST contexts order CDATA #IMPLIED>

<!ELEMENT event-queues (event-queue*)>
<!ATTLIST event-queues template CDATA #IMPLIED>
<!ATTLIST event-queues order CDATA #IMPLIED>

<!ELEMENT hfxs (topic*)>
<!ATTLIST hfxs template CDATA #IMPLIED>
<!ATTLIST hfxs order CDATA #IMPLIED>

<!ELEMENT event-queue (options*)>
<!ATTLIST event-queue name CDATA #IMPLIED>
<!ATTLIST event-queue template CDATA #IMPLIED>
<!ATTLIST event-queue rule (allow | deny) "allow">

<!ELEMENT context (sources | receivers | wildcard-receivers | options)+>
<!ATTLIST context name CDATA #IMPLIED>
<!ATTLIST context template CDATA #IMPLIED>
<!ATTLIST context rule (allow | deny) "allow">

<!ELEMENT sources (topic*)>
<!ATTLIST sources template CDATA #IMPLIED>
<!ATTLIST sources order CDATA #IMPLIED>

<!ELEMENT receivers (topic*)>
<!ATTLIST receivers template CDATA #IMPLIED>
<!ATTLIST receivers order CDATA #IMPLIED>

<!ELEMENT wildcard-receivers (wildcard-receiver*)>
<!ATTLIST wildcard-receivers template CDATA #IMPLIED>
<!ATTLIST wildcard-receivers order CDATA #IMPLIED>

<!ELEMENT topic (options*)>
<!ATTLIST topic template CDATA #IMPLIED>
<!ATTLIST topic rule (allow | deny) "allow">
<!ATTLIST topic pattern CDATA #IMPLIED>
<!ATTLIST topic topicname CDATA #IMPLIED>

<!ELEMENT wildcard-receiver (options*)>
<!ATTLIST wildcard-receiver template CDATA #IMPLIED>
<!ATTLIST wildcard-receiver rule (allow | deny) "allow">
<!ATTLIST wildcard-receiver pattern CDATA #IMPLIED>
<!ATTLIST wildcard-receiver pattern-type (pcre | regex | application-callback) #IMPLIED>
           

1.5.1. Creating An Attributes Object

In the following example, the call to lbm_context_attr_create() creates the custom attributes object, and initializes each attribute from the current default values. Subsequent calls to lbm_context_attr_setopt() or lbm_context_attr_str_setopt() modify only the attributes object values.

lbm_context_attr_t * attrib;
int rc;
int errnum;
const char * errmsg;

rc = lbm_context_attr_create(&attrib);
if (rc != 0)
{
   errnum = lbm_errnum();
   errmsg = lbm_errmsg();
   fprintf(stderr, "Error %d returned from lbm_context_attr_create(), %s\n",
      errnum, errmsg);
}

This example also illustrates the proper way to determine the success or failure of an UM API call. Most UM API calls return 0 to indicate success, and -1 to indicate failure. To retrieve the specific UM error code for the failure, call lbm_errnum(). To retrieve a text string describing the error code, call lbm_errmsg().

1.5.2. Setting an Option from a Binary Value

For an option of type other than "string", call lbm_context_attr_setopt() to set its value. (See the C API reference for details on this function.) The final two parameters in the function are a pointer to a variable containing the option value, and a pointer to a variable of type size_t that contains the correct length of the option value variable.

UM options are of three general types that:

• accept values in a well-defined range (Examples include context transport_tcp_port_low and context transport_tcp_port_high. Each requires a value which corresponds to a valid TCP port number.)

• accept values from an enumerated set, (For example, context operational_mode. Manifest constants are provided in lbm.h for each permitted value. In the case of context operational_mode, those constants are LBM_CTX_ATTR_OP_EMBEDDED and LBM_CTX_ATTR_OP_SEQUENTIAL.)

• act as switches, enabling or disabling a particular feature (For example, context resolver_cache. The set of allowed values is limited to 0 (indicating off, no, false, or disabled), and 1, indicating on, yes, true, or enabled.)

The example code below sets four options. First, we set the operational mode to sequential. Then we set the transport TCP port low and high values to 4901 and 4920, respectively. Finally, we tell UM that our application will not be using multiple sending threads per transport session.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
unsigned short int optval;
size_t optlen;

/* Set the operational_mode */
optlen = sizeof(optval);
optval = LBM_CTX_ATTR_OP_SEQUENTIAL;
rc = lbm_context_attr_setopt(attrib, "operational_mode", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_low */
optlen = sizeof(optval);
optval = 4901;
rc = lbm_context_attr_setopt(attrib, "transport_tcp_port_low", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_high */
optlen = sizeof(optval);
optval = 4920;
rc = lbm_context_attr_setopt(attrib, "transport_tcp_port_high", &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_session_multiple_sending_threads */
optlen = sizeof(optval);
optval = 0;
rc = lbm_context_attr_setopt(attrib, "transport_session_multiple_sending_threads",
                             &optval, optlen);
if (rc != 0)
{
   /* Handle error */
}

1.5.3. Setting an Option from a String Value

Setting an option from a string value effectively does the same thing that setting an option from a binary value does. However, the option value is passed as a null-terminated string, rather than as value and length pointers. UM uses this mechanism to process options in a configuration file. Thus, the format used for option values must match the format you would use in a configuration file.

In the following example, as before, we set the operational mode to sequential. Then we set the transport TCP port low and high values to 4901 and 4920, respectively. Finally, we tell UM that our application will not be using multiple sending threads per transport session.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;

/* Set the operational_mode */
rc = lbm_context_attr_str_setopt(attrib, "operational_mode", "sequential");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_low */
rc = lbm_context_attr_str_setopt(attrib, "transport_tcp_port_low", "4901");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_tcp_port_high */
rc = lbm_context_attr_str_setopt(attrib, "transport_tcp_port_high", "4920");
if (rc != 0)
{
   /* Handle error */
}

/* Set transport_session_multiple_sending_threads */
rc = lbm_context_attr_str_setopt(attrib, "transport_session_multiple_sending_threads",
                                 "0");
if (rc != 0)
{
   /* Handle error */
}

1.5.4. Getting an Option as a Binary Value

Getting an option as a binary value is very similar to setting an option from a binary value: it requires knowledge of not only the option name, but its type as well. The final two parameters in the call to lbm_context_attr_getopt() are a pointer to a variable to receive the current option value, and a pointer to a variable of type size_t which contains the length of the option value variable. This length must be be correct for the specified option.

In the example code below, we set the option values for operational mode, the transport TCP port low and high values, and retrieve multiple sending threads.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
unsigned short int optval;
size_t optlen;

/* Get the operational_mode */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "operational_mode", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains LBM_CTX_ATTR_OP_EMBEDDED or LBM_CTX_ATTR_OP_SEQUENTIAL */

/* Get transport_tcp_port_low */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_tcp_port_low", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_tcp_port_low, which should be 4901 */

/* Get transport_tcp_port_high */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_tcp_port_high", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_tcp_port_high, which should be 4920 */

/* Get transport_session_multiple_sending_threads */
optlen = sizeof(optval);
rc = lbm_context_attr_getopt(attrib, "transport_session_multiple_sending_threads",
                             &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of transport_session_multiple_sending_threads,
   which should be 0. */

1.5.5. Getting an Option as a String Value

Getting an option as a string value effectively does the same thing that getting an option as a binary value does. However, the option value is returned as a null-terminated string, just as you would specify the option value in a configuration file. The final two parameters in the call to lbm_context_attr_str_getopt() are a pointer to a string variable to receive the current option value, and a pointer to a variable of type size_t which contains the maximum size of the option value string variable.

In the example code below, the option values for operational mode, the transport TCP port low and high values, and multiple sending threads are retrieved.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;
char optval_string[256];

/* Get the operational_mode */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "operational_mode", optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains either "embedded" or "sequential" */

/* Get transport_tcp_port_low */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_tcp_port_low",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the string value of transport_tcp_port_low,
   which should be "4901" */

/* Get transport_tcp_port_high */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_tcp_port_high",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the string value of transport_tcp_port_high,
   which should be "4920" */

/* Get transport_session_multiple_sending_threads */
optlen = sizeof(optval_string);
rc = lbm_context_attr_str_getopt(attrib, "transport_session_multiple_sending_threads",
                                 optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval_string now contains the value of transport_session_multiple_sending_threads,
   which should be "0". */

1.5.6. Deleting an Attributes Object

Once the attributes object is no longer needed, it should be deleted.

lbm_context_attr_t * attrib; /* Must have already been created */
int rc;

rc = lbm_context_attr_delete(attrib);
if (rc != 0)
{
   /* Handle error */
}

1.5.7. Restrictions

There are no restrictions on setting options via attributes objects. Any option which can be set via a configuration file, can also be set via an attributes object. In addition, attributes objects allow setting certain options (such as function pointers) which cannot be set with a configuration file.

1.6.1. Setting An Option from a Binary Value

Setting an option from a binary value requires knowledge of not only the option name, but its type and allowable values as well. The final two parameters in the call to lbm_event_queue_setopt() are a pointer to a variable which contains the option value to be set, and a pointer to a variable of type size_t which contains the length of the option value variable. This length must be be correct for the specified option.

In the example code below, we set the queue size warning to 5000 events.

unsigned long int optval;
size_t optlen;
lbm_event_queue_t evq; /* must be previously created */
int rc;

/* Set the queue size warning */
optlen = sizeof(optval);
optval = 5000;
rc = lbm_event_queue_setopt(&evq, "queue_size_warning", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}

1.6.2. Setting An Option from a String Value

Setting an option from a string value effectively does the same thing that setting an option from a binary value does. However, the option value is passed as a null-terminated string, rather than as value and length pointers. This is similar to the mechanism used by UM to process options in a configuration file. Thus, the format used for option values must match the format you would use in a configuration file.

As before, we set the queue size warning to 5000 events.

lbm_event_queue_t evq; /* must be previously created */
int rc;

/* Set the queue size warning */
rc = lbm_event_queue_setopt(&evq, "queue_size_warning", "5000");
if (rc != 0)
{
   /* Handle error */
}

1.6.3. Restrictions

Modifying the current attributes of a object allows only a very limited subset of options to be set or retrieved. Consult subsequent sections of this document to determine if a particular option can be specified.

1.7.1. Getting An Option as a Binary Value

Getting an option as a binary value is very similar to setting an option from a binary value: it requires knowledge of not only the option name, but its type as well. The final two parameters in the call to lbm_event_queue_getopt() are a pointer to a variable to receive the current option value, and a pointer to a variable of type size_t which contains the length of the option value variable. This length must be be correct for the specified option.

In the example code below, the option value for the queue size warning is retrieved.

unsigned long int optval;
size_t optlen;
lbm_event_queue_t evq; /* must be previously created */
int rc;

/* Get the queue size warning value */
optlen = sizeof(optval);
rc = lbm_event_queue_getopt(&evq, "queue_size_warning", &optval, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of queue_size_warning, which should be 5000 */

1.7.2. Getting An Option as a String Value

Getting an option as a string value effectively does the same thing that getting an option as a binary value does. However, the option value is returned as a null-terminated string, just as you would specify the option value in a configuration file. The final two parameters in the call to lbm_event_queue_str_getopt() are a pointer to a string variable to receive the current option value, and a pointer to a variable of type size_t which contains the maximum size of the option value string variable.

In the example code below, the option value for the queue size warning is retrieved.

char optval_string[256];
size_t optlen;
lbm_event_queue_t evq; /* must be previously created */
int rc;

/* Get the queue size warning value */
optlen = sizeof(optval_string);
rc = lbm_event_queue_str_getopt(&evq, "queue_size_warning", optval_string, &optlen);
if (rc != 0)
{
   /* Handle error */
}
/* optval now contains the value of queue_size_warning, which should be "5000" */

2.4.1. Disabling Topic Advertisements

You can disable topic advertisements in the Initial Phase, Sustaining Phase or both phases of topic resolution.

source resolver_advertisement_minimum_initial_interval 0
source resolver_advertisement_maximum_initial_interval 0

source resolver_advertisement_sustain_interval 0

2.4.2. Disabling Receiver Topic Queries

You can disable the querying of topics by receivers in the Initial Phase, Sustaining Phase or both phases of topic resolution.

receiver resolver_query_minimum_initial_interval 0
receiver resolver_query_maximum_initial_interval 0

receiver resolver_query_sustain_interval 0
receiver resolution_number_of_sources_query_threshold 0

2.4.3. Disabling Wildcard Topic Queries

Use one or both of the following options to disable topic queries by wildcard receivers.

wildcard_receiver resolver_query_minimum_interval 0
wildcard_receiver resolver_query_maximum_interval 0

2.4.4. Disabling All But the Minimum Topic Resolution Traffic

A minimalist approach to topic resolution can take different forms based on you requirements. One approach is to disable all traffic except for queries in the sustaining phase. Add the following settings to your Ultra Messaging configuration file to implement this approach.

source resolver_advertisement_minimum_initial_interval 0
source resolver_advertisement_sustain_interval 0
receiver resolver_query_minimum_initial_interval 0
receiver resolution_number_of_sources_query_threshold 1
wildcard_receiver resolver_query_minimum_interval 0

2.4.5. Re-establish Pre-4.0 Topic Resolution

Ultra Messaging topic resolution prior to LBM Version 4.0 did not have resolution phases. To implement pre-4.0 topic resolution, include the following configuration option changes in your Ultra Messaging configuration file.

# ----- Disable Advertisements in 4.0 Initial Phase
source resolver_advertisement_minimum_initial_interval 0

# ----- Re-establish pre-4.0 Advertisement Behavior
source resolver_advertisement_minimum_sustain_duration 0
context resolver_sustain_advertisement_bps 0

# ----- Disable Queries in 4.0 Initial Phase
receiver resolver_query_minimum_initial_interval 0

# ----- Re-establish pre-4.0 Query Behavior
receiver resolver_query_sustain_interval 100
receiver resolver_query_minimum_sustain_duration 0
context resolver_sustain_query_bps 0
receiver resolution_number_of_sources_query_threshold 1

# ----- Re-establish pre-4.0 Wildcard Query Behavior
wildcard_receiver resolver_query_minimum_interval 0

2.5.1. Unicast Resolution Across Administrative Domains

The following network architecture shows a source or publisher (src) on a private LAN.

The following lbmrd configuration file allows rcv1 and rcv2 to connect to src for receipt of topic messages.

<?xml version="1.0" encoding="UTF-8" ?>
<lbmrd version="1.0">
   <domains>
      <domain name="NAT">
         <network>192.168.130.0/24</network>
      </domain>
      <domain name="OPEN">
         <network>10.200.2.31</network>
         <network>10.200.2.30</network>
      </domain>
   </domains>
   <transformations>
      <transform source="NAT" destination="OPEN">
         <rule>
            <match address="192.168.130.14" port="*"/>
            <replace address="10.200.1.14" port="*"/>
         </rule>
      </transform>
   </transformations>
</lbmrd>

2.8.1. Preventing NAK Storms with NAK Interval Options

The NAK generation interval should be sufficiently longer than the NAK backoff interval so that the source, after receiving the first NAK from a receiver, has time to retransmit the missing datagram and prevent a NAK storm from all receivers. LBTRM, LBTRU, and MIM all use NAK generation and backoff intervals. The NAK behavior for all transports is the same.

Interrelated Options:

• transport_lbtrm_nak_backoff_interval

• transport_lbtrm_nak_generation_interval

• transport_lbtru_nak_backoff_interval

• transport_lbtru_nak_generation_interval

• mim_nak_backoff_interval

• mim_nak_generation_interval

Recommendation:

• Set the NAK generation interval to at least 2x the NAK backoff interval.

For more, see also Transport LBT-RM Reliability Options, Transport LBT-RU Reliability Options, or Multicast Immediate Messaging Reliability Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid NAK storms, set NAK generation interval to at least 2x the          |
# | NAK backoff interval.                                                        |
# +------------------------------------------------------------------------------+
#
receiver transport_lbtrm_nak_backoff_interval       200
receiver transport_lbtrm_nak_generation_interval  10000

2.8.2. Preventing Tail Loss With TSNI and NAK Interval Options

Tail loss describes a situation where the last few messages sent by a publisher before it exits are not received by a subscriber. A TSNI active threshold that is too small relative to the TSNI and/or NAK generation interval may cause tail loss, especially with ordered delivery.

Interrelated Options:

• transport_topic_sequence_number_info_active_threshold

• transport_topic_sequence_number_info_interval

• transport_lbtrm_nak_generation_interval

• transport_lbtru_nak_generation_interval

Recommendation:

• set the TSNI active threshold to at least 4x the topic sequence number info interval (TSNI) plus the NAK generation interval.

For more, see Transport LBT-RM Reliability Options or Transport LBT-RU Reliability Options.

Example:

#
# +-------------------------------------------------------------------------------+
# | To avoid tail loss, set transport_topic_sequence_number_info_active_threshold |
# | to at least the sum of 4x the topic sequence number interval plus the NAK     |
# | generation interval.                                                          |
# | NOTE: resolver_active_threshold is in seconds.                                |
# +-------------------------------------------------------------------------------+
#
source   transport_topic_sequence_number_info_interval          2000
receiver transport_lbtrm_nak_generation_interval               10000
source   transport_topic_sequence_number_info_active_threshold    60

2.8.3. Preventing IPC Receiver Deafness With Keepalive Options

With an LBT-IPC transport, an activity timeout that is too small relative to the session message interval may cause receiver deafness. If a timeout is too short, the keepalive messages might not be received in time to prevent the receiver from being deleted or disconnecting because the source appears to be gone.

Interrelated Options:

• transport_lbtipc_activity_timeout

• transport_lbtipc_sm_interval

Recommendations:

• set the activity timeout to at least 2x the session message interval

For more, see Transport LBT-IPC Operation Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid receiver deafness:                                                  |
# | - set client activity timeout to at least 2x the acknowledgement interval.   |
# | - set activity timeout to at least 2x the session message interval.          |
# +------------------------------------------------------------------------------+
#
receiver transport_lbtipc_activity_timeout          60000 
source   transport_lbtipc_sm_interval               10000

2.8.4. Preventing Erroneous LBT-RM/LBT-RU Session Timeouts

An LBT-RM or LBT-RU receiver-side quiescent timeout may delete a transport session that a source is still active on. This can happen if the timeout is too short relative to the source's interval between session messages (which serve as a session keepalive).

Interrelated Options:

• transport_lbtrm_activity_timeout

• transport_lbtrm_sm_maximum_interval

• transport_lbtru_activity_timeout

• transport_lbtru_sm_maximum_interval

Recommendations:

• set the receiver LBT-RM or LBT-RU activity timeout to at least 3x the source session message maximum interval

For more, see Transport LBT-RM Operation Options or Transport LBT-RU Operation Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid erroneous session timeouts, set receiver transport activity         |
# | timeout to at least 3x the source session message maximum interval.          |
# +------------------------------------------------------------------------------+
#
receiver transport_lbtrm_activity_timeout       60000  
source   transport_lbtrm_sm_maximum_interval    10000 
receiver transport_lbtru_activity_timeout       60000 
source   transport_lbtru_sm_maximum_interval    10000

2.8.5. Preventing Errors Due to Bad Multicast Address Ranges

Sometimes it is easy to accidentally reverse the low and high values for LBT-RM multicast addresses, which actually creates a very large range. Aside from excluding intended addresses, this can cause error conditions.

Interrelated Options:

• transport_lbtrm_multicast_address_low

• transport_lbtrm_multicast_address_high

Recommendations:

• ensure that the intended low and high values for LBT-RM multicast addresses are not reversed

For more, see Transport LBT-RM Network Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid incorrect LBT-RM multicast address ranges, ensure that you have not |
# | reversed the low and high values.                                            |
# +------------------------------------------------------------------------------+
#
context  transport_lbtrm_multicast_address_low  224.10.10.10
context  transport_lbtrm_multicast_address_high 224.10.10.14

2.8.6. Preventing Store or Queue Timeouts

A store or queue may be erroneously declared unresponsive if its activity timeout expires before it has had adequate opportunity to verify it is still active via activity check intervals.

Interrelated Options:

• ume_store_activity_timeout

• ume_store_check_interval

• umq_queue_activity_timeout

• umq_queue_check_interval

Recommendations:

• set the store or queue activity timeout to at least 5x the activity check interval

For more, see the UM Configuration Guide, 4.29. Ultra Messaging Persistence Options and/or (if using UM Queuing Edition), the UM Configuration Guide, 4.30. Ultra Messaging Queuing Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid erroneous store or queue activity timeouts, set the activity        |
# | timeout to at least 5x the activity check interval.                          |
# +------------------------------------------------------------------------------+
#
source ume_store_activity_timeout               3000   
source ume_store_check_interval                  500 
context umq_queue_activity_timeout              3000 
context umq_queue_check_interval                 500

2.8.7. Preventing ULB Timeouts

A ULB source or receiver may be erroneously declared unresponsive if its activity timeout expires before it has had adequate opportunities to attempt to re-register via activity check intervals if the source appears to be inactive. It is also possible for sources to attempt to reassign messages that have already been processed.

Interrelated Options:

• umq_ulb_source_activity_timeout

• umq_ulb_source_check_interval

• umq_ulb_application_set_message_reassignment_timeout

• umq_ulb_application_set_receiver_activity_timeout

• umq_ulb_check_interval

Recommendations:

• set the ULB source activity timeout to at least 5x the ULB source activity check interval

• set the ULB application set message reassignnment timeout to at least 5x the ULB check interval

• set the ULB receiver activity timeout to at least 5x the ULB check interval

For more (if using UM Queuing Edition), see the UM Configuration Guide, 4.30. Ultra Messaging Queuing Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid erroneous ULB source, receiver or application set message activity  |
# | timeouts, set the activity timeout to at least 5x the activity check         |
# | interval.                                                                    |
# +------------------------------------------------------------------------------+
#
receiver umq_ulb_source_activity_timeout                    10000   
receiver umq_ulb_source_check_interval                       1000 
source umq_ulb_application_set_message_reassignment_timeout 50000 
source umq_ulb_application_set_receiver_activity_timeout    10000
source umq_ulb_check_interval                                1000

2.8.8. Preventing Unicast Resolver Daemon Timeouts

A unicast resolver daemon may be erroneously declared inactive if its activity timeout expires before it has had adequate opportunity to verify that it is still alive.

Interrelated Options:

• resolver_unicast_activity_timeout

• resolver_unicast_check_interval

Recommendations:

• Set the unicast resolver daemon activity timeout to at least 5x the activity check interval. Or, if activity notification is not desired, set both options to 0.

For more, see Resolver Operation Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid erroneous unicast resolver daemon timeouts, set the activity        |
# | timeout to at least 5x the activity check interval.                          |
# +------------------------------------------------------------------------------+
#
context  resolver_unicast_activity_timeout       1000 
context  resolver_unicast_check_interval          200

2.8.9. Preventing Undetected Late Join Loss

If during a Late Join operation, a transport times out while a receiver is requesting retransmission of missing messages, this can cause lost messages to go undetected and likely become unrecoverable.

Interrelated Options:

• retransmit_request_generation_interval

• transport_tcp_activity_timeout

• transport_lbtrm_activity_timeout

• transport_lbtru_activity_timeout

• transport_lbtipc_activity_timeout

Recommendations:

• set the Late Join retransmit request interval to a value less than its transport's activity timeout value

For more, see Late join Options and also the applicable Transport LBT-RU Operation Options section.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid a transport inactivity timeout while requesting Late Join           |
# | retransmissions, set the Late Join retransmit request interval to a value    |
# | less than its transport's activity timeout.                                  |
# +------------------------------------------------------------------------------+
#
receiver retransmit_request_generation_interval 10000 
receiver transport_lbtrm_activity_timeout       60000

2.8.10. Preventing Undetected Loss

It is possible that an unrecoverable loss due to unsatisfied NAKs or a transport activity timeout may go unreported if the delivery controller loss check is disabled or has too long an interval. For UMP stores, the loss check interval must be enabled. Two options (three, if using LBT-RM) are interrelated and must be set according to the guidelines below.

Interrelated Options:

• delivery_control_loss_check_interval

• transport_lbtrm_activity_timeout

• transport_lbtrm_nak_generation_interval

• transport_lbtru_activity_timeout

Recommendations:

• For LBT-RM, set the transport activity timeout to value greater than the sum of the delivery control loss check interval and the NAK generation interval. Also, set the NAK generation interval to at least 4x the delivery control loss check interval.

• for LBT-RU, set the transport activity timeout to value greater than the delivery control loss check interval

• for UMP, always enable and set accordingly the delivery control loss check interval when configuring a store

For more, see Delivery Control Options.

Example:

#
# +------------------------------------------------------------------------------+
# | To avoid undetected or unreported loss, set NAK generation to 4x the delivery|
# | control check interval, and ensure that these two combined are less than the |
# | transport activity timeout                                                   |
# +------------------------------------------------------------------------------+
#
receiver delivery_control_loss_check_interval     2500 
receiver transport_lbtrm_activity_timeout        60000 
receiver transport_lbtrm_nak_generation_interval 10000

4.1.1. Case Sensitivity

All Ultra Messaging scope, option, and value strings are case-insensitive. Thus, any of context, CONTEXT, and Context are recognized as specifying the "context" scope.

4.1.2. Specifying Interfaces

The *_interface options require a network interface, usually supplied as a string (from a config file via lbm_config() or in source code via *_attr_str_setopt()), the syntax used for network interface specifications is:

a.b.c.d/num

context resolver_unicast_interface 192.168.0.0/24

context resolver_unicast_interface "interfacename"

4.1.3. Socket Buffer Sizes

When specifying send or receive socket buffer sizes, keep the following platform-specific information in mind.

• Linux

  The kernel value net.core.rmem_max dictates the highest value allowed for a receive socket. The kernel value net.core.wmem_max dictates the highest value allowed for a sending socket. Increase these values to increase the amount of buffering allowed.

• Windows

  Windows should allow socket buffer sizes to be set very high if needed without requiring registry changes.

See our whitepaper Topics in High Performance Messaging for background and guidelines on UDP buffer sizing.

4.1.4. Reference Entry Format

This section describes the format of each option reference entry.

Each entry begins with a brief description of the option. Following the description is a series of items which define the permissible usage and describes the values for the option.

• Scope

  Defines the scope to which the option applies.

• Type

  Defines the data type of the option. The type is required for calls to the *_setopt() and *_getopt() API functions.

• Units

  Defines the units in which the option value is expressed. This item is optional.

• Default value

  For range-valued options, indicates the base default value for the option.

• Byte order

  For options whose value is an IP address or port, defines the byte ordering (Host or Network) expected by the API for *_setopt() calls, and returned by the API for *_getopt() calls.

• May be set during operation

  If an option may be set during operation, it is so indicated here.

Next, for enumerated-valued options, a table is provided which details the permissible string and integer values, a description of each value, and optional notes for each value. The default value is noted within the description.

Alternately, for switch-valued options, a table is provided which describes the meaning of each of the two possible values. The default value is noted within the description.

4.1.5. Network Compatibility Mode

This section lists the values for the network_compatibility_mode option, that attempts to maintain wire-level backwards compatibility with older releases by blocking the sending of some (though possibly not all) newer message header types. An application using an older UM release typically logs a warning message when receiving an unknown message header type that did not yet exist in that older release. In a mixed UM version environment, Informatica recommnends that your applications filter these unknown message header warning log messages. This option should only be used if such filtering is undesired or not possible.

Note that this option does not change any internal behaviors. It merely prevents the sending new message header types which disables any new functionality that relies on the new message header types for both old and new applications. Other than the warning log message for an application using an earlier release, new message header types do not cause any harm.

4.2.1. context_event_function (context)

Callback function (and associated client data pointer) that is called when a context event occurs. This callback may be called inline or from an event queue, if one is given. If called inline, the callback function used should not block or it will block the context thread processing. A value of NULL for the callback turns off the callback being called.

4.2.2. context_name (context)

The name of the context, limited to 128 alphanumeric characters, hyphens or underscores.

4.2.3. fd_management_type (context)

Define the mechanism UM uses for socket file descriptor (FD) management. For more information, search on "file descriptors" in the Informatica Knowledge Base.

4.2.4. message_selector (receiver)

Enables UM to pass a message selector string to any receiver. The value must be an expression that conforms to JMS message selector syntax as defined in the Oracle JMS specification. For a UM receiver used with UMP, please see the Native Applications section in UM JMS Guide.

4.2.5. network_compatibility_mode (context)

This option attempts to maintain wire-level backwards compatibility with older releases by blocking the sending of some (though possibly not all) newer message header types. See Network Compatibility Mode for more information and option values.

4.2.6. operational_mode (context)

The mode in which UM operates to process events. Refer to Embedded and Sequential Mode for additional information.

4.2.7. ordered_delivery (receiver)

For LBT-RM, LBT-RU, TCP-LB or LBT-IPC transport sessions only. (This option also applies to TCP when using Late Join because the Late Join messages are not part of the TCP message stream.) Indicates whether or not the topic should have its data delivered in order and reassembled. The default value guarantees ordering and reassembly of large messages. Reassembly of large messages is optional. Changing this option from the default value to a value of 0 (zero) results in messages being delivered as soon as they arrive. Value -1 allows arrival order delivery after the reassembly of large messages. See also Ordered Delivery for more information about large message fragmentation and reassembly.

4.2.8. rcv_sync_cache (receiver)

Ultra Messaging Cache only - a valid cache address (such as TCP:192.168.5.11:4567) in the standard form of TCP:address:port enables a UM receiver to use UMCache to receive a snapshot of larger, multiple-field messages stored by UMCache. Receiving applications can then become synchronized with the live stream of messages sent on the receiver's topic. address is the IP address of the machine where the UMCache runs and port is the configured port where the cache request handler listens.

4.2.9. rcv_sync_cache_timeout (receiver)

Ultra Messaging Cache only - The maximum time period that a UM receiver waits for a snapshot message from the UMCache .

4.2.10. receive_thread_pool_size (context)

For LBT-RM, LBT-RU, or TCP-LB transport sessions only. Defines the maximum number of threads available for transports (excluding the context thread). See Multi-Transport Threads.

4.2.11. resolver_context_advertisement_interval (context)

Interval between context advertisements. Setting this option to 0 disables context advertisements, though gateway and other functionality depends upon context advertisements, so a value of 0 is not generally recommended.

4.2.12. resolver_source_notification_function (context)

Callback function (and associated client data pointer) that is called when a new source is seen for any topic. This callback is called directly in line and does not use the event queue. Therefore the callback function used should not block or it will block the context thread processing. A value of NULL for the callback turns off the callback being called.

4.2.13. source_cost_evaluation_function (context)

Callback function that you can use in the lbm_src_cost_function_cb() to evaluate or determine the cost of a message path. The UM Gateway evaluates the cost of any new topic it detects. The callback supplied with this option can affect the cost of topics to bias the UM Gateway toward certain message paths. A value of NULL for the callback turns off the callback being called. See also Applications Can Also Set the Topic Cost.

4.2.14. source_event_function (context)

Callback function (and associated client data pointer) that is called when a context source event (such as a multicast immediate mode source wakeup event) occurs. This callback may be called inline or from an event queue, if one is given. If called inline, the callback function used should not block or it will block the context thread processing. A value of NULL for the callback turns off the callback being called.

4.2.15. source_includes_topic_index (context)

Determines whether the topic index is included in the source string generated for messages and new source notifications.

4.2.16. transport (source)

The transport type to be used for created sources.

4.2.17. transport_demux_tablesz (receiver)

Specifies the size of the table used for storing receiver delivery controllers used by UM for message delivery. Must be a power of two (1, 2, 4, 8, 16, etc.). If not a power of two, UM generates a log warning and uses the next highest power of two. For most use cases with low to moderate numbers of topics per transport session, the default suffices. For large numbers of topics and in cases where the lowest latency is desired, set the option to the next highest power of two for the number of topics expected on the transport session.

4.2.18. transport_session_multiple_sending_threads (context)

Flag to indicate the application intends to use multiple sending threads per transport session.

4.2.19. transport_source_side_filtering_behavior (source)

The filtering behavior desired when TCP and LBT-RU clients are connected. Any other value besides none requires that the clients send unicast messages to the source. These control messages are sent to the TCP request port of the senders context and processed internally. This option affects the transport session underlying the source rather than the source itself. Refer to Source Configuration and Transport Sessions for additional information.

4.2.20. transport_topic_sequence_number_info_active_threshold (source)

Duration in seconds that an inactive source sends contiguous Topic Sequence Number Info (TSNI) messages. (Inactive sources send TSNI messages according to the transport_topic_sequence_number_info_interval.) A value of 0 indicates that sources continue sending TSNIs until data messages resume, with no timeout. See also Interrelated Configuration Options.

4.2.21. transport_topic_sequence_number_info_interval (source)

The interval between Topic Sequence Number Info (TSNI) messages that a source sends. TSNI messages are enabled on all transports and they carry the topic sequence number of the latest message sent by the source. The interval is also a source inactivity threshold. In other words, a source does not send TSNIs during normal data transmission, but once the source is inactive for as long as this interval, it starts sending TSNI messages. A value of 0 turns off TSNI messages for the source. See also Interrelated Configuration Options.

4.2.22. use_extended_reclaim_notifications (source)

Specifies which reclaim notification your application receives. The expanded notification, LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX, contains a flag, LBM_SRC_EVENT_UME_MESSAGE_RECLAIMED_EX_FLAG_FORCED that UMP sets if the reclamation is a forced reclaim.

4.2.23. use_transport_thread (receiver)

For LBT-RM, LBT-RU, or TCP-LB transport sessions only. Determines whether UM uses a thread from the receiver thread pool to process message data or if it uses the context thread, which is the default. See Multi-Transport Threads.

4.3.1. Minimum Values for Advertisement and Query Intervals

These intervals have the following effective minimal values.

• 10 ms for Initial Phase Advertisements

• 20 ms for Initial Phase Queries

• 30 ms Wildcard Queries

• 100 ms for Sustaining Phase Advertisements and Queries

These effective minimums exist because the internal timer that schedules advertisements and queries fires at the stated interval, i.e., every 10 ms for Initial Phase Advertisements, every 20 ms for Initial Phase Queries, etc. If you set the option's value below the minimum, after the the initial advertisement or query at 0 ms, the resolver schedules the second advertisement or query at the first timer "tick", which is the minimum. Subsequent advertisements or queries can only be issued at the next timer "tick". If you increase this option from the default to a value that is not a multiple of the minimum, the resolver maintains the rate you establish as an average over subsequent "ticks".

As an example, If you set resolver_advertisement_sustain_interval or resolver_query_sustain_interval at 10 ms, the resolver schedules the second advertisement or query after the initial (0 ms) at the first timer "tick", which is 100 ms. Subsequent advertisements or queries can only be issued at the next timer "tick" (every 100 ms). If you increase either option from the default to 1.25 seconds, for example and not a multiple of 100 ms, the resolver maintains the rate you establish as an average over subsequent "ticks". That is, the second advertisement or query goes out at the 1300 ms "tick". The resolver tracks the tardiness of this advertisement (50 ms) and adjusts the next advertisement or query, which goes out at 2500 ms, giving an average of 1250 ms or 1.25 seconds.

4.3.2. disable_extended_topic_resolution_message_options (context)

This is a topic resolution compatibility option that, when set to 1, lets LBM 4.0 (or later) installations work with LBM 3.5.3 / UME 2.2.4 (or earlier) installations. If you do not have early-version installations in the network, leave this option at 0.

4.3.3. resolution_no_source_notification_threshold (receiver)

The threshold for the number of unanswered topic resolution queries before UM delivers a LBM_MSG_NO_SOURCE_NOTIFICATION for the topic. The receiver does not stop querying after the delivery of this notification. A value of 0 indicates no notifications will be sent.

4.3.4. resolution_number_of_sources_query_threshold (receiver)

The threshold for the number of sources a topic must have before topic resolution queries are not sent. A value of zero results in no topic resolution queries being generated. See also Disabling Aspects of Topic Resolution .

4.3.5. resolver_advertisement_maximum_initial_interval (source)

The longest - and last - interval in the initial phase of topic advertisement. A value of 0 disables the initial phase of advertisement. See also Disabling Aspects of Topic Resolution.

4.3.6. resolver_advertisement_minimum_initial_duration (source)

The duration of the initial phase of topic advertisement. A value of 0 guarantees that the initial phase of advertisement never completes.

4.3.7. resolver_advertisement_minimum_initial_interval (source)

Interval between the first topic advertisement sent upon creation of the source and the second advertisement sent by the source. A value of 0 disables the initial phase of advertisement. See also Disabling Aspects of Topic Resolution. This option has an effective minimum of 10 ms. See Minimum Values for Advertisement and Query Intervals.

4.3.8. resolver_advertisement_minimum_sustain_duration (source)

The duration of the sustaining phase of topic advertisement. A value of 0 guarantees that the sustaining phase of advertising never completes.

4.3.9. resolver_advertisement_send_immediate_response (source)

Allows you to disable the normal immediate response to queries and wildcard queries. Sources normally send topic advertisements (TIR) immediately in response to topic queries (TQR) for a local topic or wildcard queries (WC-TQR) with a pattern that matches a local topic. If you configure sources to delay sending advertisements, UM delays advertisements by the limits defined by the advertisement rate limiter options, resolver_*_bps and resolver_*_per_second.

4.3.10. resolver_advertisement_sustain_interval (source)

Interval between sending topic advertisements in the sustaining phase of topic advertisement. A value of 0 disables the sustaining phase of advertisement. See also Disabling Aspects of Topic Resolution. This option has an effective minimum of 100 ms. See Minimum Values for Advertisement and Query Intervals.

4.3.11. resolver_cache (context)

Whether or not to cache topic resolution information. When topic resolution information is not cached, it takes up less memory. However, wildcard receivers will only see topics that have other UM receivers created. And source notification only occurs for topics that have UM receivers created.

4.3.12. resolver_datagram_max_size (context)

The maximum datagram size that can be generated for topic resolution advertisements and queries. The default value is 8192, the minimum is 500 bytes, and the maximum is 65535.

4.3.13. resolver_initial_advertisement_bps (context)

Maximum advertisement rate during the initial phase of topic advertisement. A value of 0 sets no rate limit on advertisements in the initial phase of topic advertisement.

4.3.14. resolver_initial_advertisements_per_second (context)

Maximum number of advertisements sent within a one second period during the initial phase of topic advertisement. A value of 0 sets no rate limit on advertisements in the initial phase of topic advertisement.

4.3.15. resolver_initial_queries_per_second (context)

Maximum number of queries sent within a one second period during the initial phase of topic querying. A value of 0 sets no rate limit on queries in the initial phase of topic querying.

4.3.16. resolver_initial_query_bps (context)

Maximum query rate during the initial phase of topic querying. A value of 0 sets no rate limit on queries in the initial phase of topic querying.

4.3.17. resolver_query_maximum_initial_interval (receiver)

The longest - and last - interval in the initial phase of topic querying. A value of 0 disables the initial phase of querying. See also Disabling Aspects of Topic Resolution.

4.3.18. resolver_query_minimum_initial_duration (receiver)

The duration of the initial phase of topic querying. A value of 0 guarantees that the initial phase of querying never completes.

4.3.19. resolver_query_minimum_initial_interval (receiver)

Interval between the first topic query sent upon creation of the receiver and the second query sent by the receiver. A value of 0 disables the initial phase of querying. See also Disabling Aspects of Topic Resolution. This option has an effective minimum of 20 ms. See Minimum Values for Advertisement and Query Intervals.

4.3.20. resolver_query_minimum_sustain_duration (receiver)

The duration of the sustaining phase of topic querying. A value of 0 guarantees that the sustaining phase of querying never completes.

4.3.21. resolver_query_sustain_interval (receiver)

Interval between sending topic queries in the sustaining phase of topic querying. A value of 0 disables the sustaining phase of querying. See also Disabling Aspects of Topic Resolution. This option has an effective minimum of 100 ms. See Minimum Values for Advertisement and Query Intervals.

4.3.22. resolver_receiver_map_tablesz (context)

The size of the hash table used for storing receiver topic information used for topic resolution. This value should be a prime number.

4.3.23. resolver_send_initial_advertisement (source)

Controls whether or not a source sends an advertisement upon creation. Turning off this advertisement speeds source creation and reduces the number of messages on your network through application initialization.

4.3.24. resolver_source_map_tablesz (context)

The size of the hash table used for storing source topic information used by topic resolution. This value should be a prime number.

4.3.25. resolver_string_hash_function (context)

The hash function to use for hashing topic name strings for source and receiver topics. The application may choose from a list of defined hash functions or it may define its own hash function, as identified by the string value of this option. When setting a hash function, note that:

• If set through a configuration file or a call to lbm_context_attr_str_setopt(), only the string values classic, djb2, sdbm, or murmur2 are valid. (If retrieved by a call to lbm_context_attr_str_getopt(), one of these string values is returned.)

• If set through a call to lbm_context_attr_setopt(), you must pass a pointer to a hash function. Use this method for hash functions other than the four pre-defined functions.

4.3.26. resolver_string_hash_function_ex (context)

This option is similar to the resolver_string_hash_function above, except for the following differences:

• This option can be set via only lbm_context_attr_setopt() (not from a configuration file or lbm_context_attr_str_setopt()). Hence, this also means you cannot use the string options (classic, etc).

• You can pass a string length to the hash function, allowing it to then possibly run faster by operating on multiple-character strings at a time. Note that if -1 is passed in, you must use a strlen to calculate the length.

• The hash function accepts a clientd pointer, which you can set as needed, and which is passed back in each time the function is called.

4.3.27. resolver_sustain_advertisement_bps (context)

Maximum advertisement rate during the sustaining phase of topic advertisement. A value of 0 sets no rate limit on advertisements in the sustaining phase of topic advertisement.

4.3.28. resolver_sustain_advertisements_per_second (context)

Maximum number of advertisements sent within a one second period during the sustaining phase of topic advertisement. A value of 0 sets no rate limit on advertisements in the sustaining phase of topic advertisement.

4.3.29. resolver_sustain_queries_per_second (context)

Maximum number of queries sent within a one second period during the sustaining phase of topic querying. A value of 0 sets no rate limit on queries in the sustaining phase of topic querying.