Ultra Messaging® Configuration Guide
Prev	Chapter 1. Configuring Ultra Messaging® Options	Next

1.3. XML Configuration Files

XML configuration files let you address many different applications and operating requirements, removing the need to programmatically set and reset options for them. A single XML file can contain options for multiple applications. Moreover, for a single application, you can configure multiple named contexts, event queues, etc., with different values for the same options.

See Example Configuration Scenarios for example configuration files.

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

Note: Since these API functions and environment variables can be used without the UMM Daemon, no username or password can be set.

1.3.2. Using XML Configuration Files With a UM Application

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

Create an XML configuration file using an XML editor or text editor. Just for this example, name the file, UM_CONFIG.XML.
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>.
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>.
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>.
Configure the applications Event Queue options. See <event-queues>
Save the XML configuration file, UM_CONFIG.XML, and load it onto the machine where the application (SENDAPP) runs.
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.
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.

1.3.3.1. <um-configuration>

Description. The <um-configuration> element is a required container for all UM configuration options residing in the XML configuration file. This is the top-level element.

Parents. None.

Children. <templates> <applications> <license>

XML Attributes:

XML Attribute	Description	Default Value
`version`	The version of the DTD.	none

Example:

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

1.3.3.1.1. <license>

Description. The <license> element identifies the UM product license, either as the license key or as a pointer to a license file, as an alternative to setting it in an environment variable.

Parents. <um-configuration>

Children. None.

XML Attributes:

XML Attribute	Description	Default Value
`format`	The format for the license element data. `filename` points to the file containing the license key. `string` identifies the data as the license key itself.	`string`
`xml:space`	How whitespace is handled. `default` trims leading and trailing whitespace (e.g., tabs, spaces, linefeeds, etc.), and compresses multiple whitespace characters into a single space character. `preserve` preserves the whitespace exactly as read.	`default`

Example:

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

1.3.3.2. <options>

Description. The <options> element is a container element for individual options. You specify the primitive object in the attribute type.

Parents. <template> <context> <topic> <wildcard-receiver> <event-queue>

Children. <option> <application-data>

XML Attributes:

XML Attribute	Description	Default Value
`type`	The type of primitive object, which can be `event-queue`, `context`, `source`, `receiver`, `wildcard-receiver`, or `hfx`).	None

Example:

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

1.3.3.2.1. <option>

Description. The <option> element corresponds to any UM configuration option.

Parents. <options>

Children. <allow> <deny>

XML Attributes:

XML Attribute	Description	Default Value
`name`	Name of the UM configuration option. See Reference for all options.	N/A
`default-value`	The value you are setting for this option.	The default value for the option.
`order`	Permit or restrict particular option values. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). If using this XML attribute, follow this element with <allow> or <deny> elements as needed. See also Sample XML Configuration File.	`deny,allow`

Examples:

To permit any application to choose any transport method except LBT-RU, configure the following in a template included in sending applications.

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

To restrict any application to only the LBT-RM or LBR-RU transport method, configure the following in a template included in sending applications.

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

1.3.3.2.2. <allow>

Description. Use the <allow> element with <option> to set a condition for for that option to permit only a certain subset of possible default value values for the option. See also Using the Order and Rule XML Attributes.

Parents. <option>

Children. None.

XML Attributes:

XML Attribute	Description	Default Value
`xml:space`	How whitespace is handled. `default` trims leading and trailing whitespace (e.g., tabs, spaces, linefeeds, etc.), and compresses multiple whitespace characters into a single space character. `preserve` preserves the whitespace exactly as read.	`default`

Example:

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

1.3.3.2.3. <deny>

Description. Use the <deny> element with <option> to set a condition for that option that restricts certain (otherwise) possible default value values from being used by the option. See also Using the Order and Rule XML Attributes.

Parents. <option>

Children. None.

XML Attributes:

XML Attribute	Description	Default Value
`xml:space`	How whitespace is handled. `default` trims leading and trailing whitespace (e.g., tabs, spaces, linefeeds, etc.), and compresses multiple whitespace characters into a single space character. `preserve` preserves the whitespace exactly as read.	`default`

Example:

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

1.3.3.3. <templates>

Description. The <templates> element is a container element for all templates that contain configuration options that can be used in other templates or applications. A template can be very specific, such as configuring options only for LBT-RM sources, or more comprehensive, configuring common options for your applications.

Insert any desired templates in the <templates> element to hold configuration option values shared by multiple applications or primitive objects. You can create and apply multiple templates to applications and primitive UM objects in a comma separated value (CSV) format. However, if the same option appears in multiple templates, the option value in the last or lower-level template overrides the option value in the previous or higher-level template.

Parents. <um-configuration>

Children. <template>

XML Attributes: None.

Example:

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

1.3.3.3.1. <template>

Description. The <template> element is a container for one uniquely named set of options.

Parents. <templates>

Children. <options>

XML Attributes:

XML Attribute	Description	Default Value
`name`	Name of the configuration template, which can be referenced elsewhere in this XML configuration file to assign to other configuration elements. Multiple templates can be specified in a comma separated value (CSV) format.	None

Example:

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

1.3.3.4. <applications>

Description. The <application> element is a container element for all applications configured in the XML configuration file. UM lets you configure one or more applications.

Parents. <um-configuration>

Children. <application>

XML Attributes: None.

Example:

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

1.3.3.4.1. <application>

Description. The application element contains option values for all object elements within a single, uniquely named, application.

Parents. <applications>

Children. <application-data> <contexts> <event-queues> <hfxs>

XML Attributes:

XML Attribute	Description	Default Value
`name`	Name of the application. Used as an optional parameter for `lbm_config_from_xml()`. If a name is not supplied, this must be the only occurrence of this element in the XML configuration file.	None
`template`	Name of the configuration template to use for the application.	None

Example:

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

1.3.3.5. <contexts>

Description. The <contexts> element is a container element for all UM contexts configured for an application. UM lets you create one or more contexts for an application.

Parents. <application>

Children. <context>.

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual context object configured within this element. Multiple templates can by applied by specifying them in a comma-separated-value manner, i.e., `"SENDING1,SENDING2"`. Can be overridden by a different template configured for an individual context.	None
`order`	Establishes the permission semantic for each individual context configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <context> XML attribute, `rule`.	`deny,allow`

Example:

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

1.3.3.5.1. <context>

Description. The <context> element contains option values for a single context, organized into its child elements.

Parents. <contexts>

Children. <sources> <receivers> <wildcard-receivers> <options>

XML Attributes:

XML Attribute	Description	Default Value
`name`	Name of the context. Used as a parameter for `lbm_context_attr_create_from_xml()` and `lbm_context_attr_set_from_xml()`. If no name is supplied, the contained settings are matched with all NULL-named contexts.	None
`template`	Name of the configuration template to use for the context object's options.	None
`rule`	Permits or restricts the creation of the context object. If `rule="deny"`, the context object errors upon creation.	`allow`

Example:

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

1.3.3.6. <sources>

Description. The <sources> element is a container for all UM sources configured for an application. UM lets you create one or more sources for an application.

Parents. <context>

Children. <topic>

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual source object configured within this element. Multiple templates can by applied by specifying them in a comma-separated-value manner, i.e., `"SENDING1,SENDING2"`. Can be overridden by a different template configured for an individual source.	None
`order`	Establishes the permission semantic for each individual source configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <topic> XML attribute `rule`.	`deny,allow`

Example:

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

1.3.3.6.1. <topic>

Description. The <topic> element contains option values for a single source or receiver.

Parents. <hfxs> <receivers>. <sources>

Children. <options>.

XML Attributes:

XML Attribute	Description	Default Value
`topicname`	The topic string for the topic that the source sends or the receiver accepts. Used as a parameter for `lbm_src_topic_alloc()`, `lbm_rcv_topic_lookup()`, `lbm_src_attr_create_from_xml()`, `lbm_src_attr_set_from_xml()`, `lbm_rcv_attr_create_from_xml()` and `lbm_rcv_attr_set_from_xml()`. Do not use with the `pattern` attribute.	None
`template`	Name of the configuration template to use for this topic's source or receiver options.	None
`rule`	Permits or restricts the creation of the source or receiver object. If `rule="deny"`, the object errors upon creation.	`allow`
`pattern`	Identify the set of options for this topic with a topic string pattern. Any source created with a topic string that matches this pattern receives the configured option values. Do not use with the `topicname` attribute.	None

Example:

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

1.3.3.7. <receivers>

Description. The <receivers> element is a container element for all UM receivers configured for an application. You can create one or more receivers for an application.

Parents. <context>

Children. <topic>

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual receiver object configured within this element. You can apply multiple templates by specifying them in a comma-separated-value manner, e.g., `"RECEIVING1,RECEIVING2"`. A template applied to an individual receiver will override a `<receivers>`-level template.	None
`order`	Establishes the permission semantic for each individual receiver configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <topic> XML attribute `rule`.	`deny,allow`

Example:

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

1.3.3.8. <wildcard-receivers>

Description. The <wildcard-receivers> element is a container element for all UM wildcard receivers configured for an application. UM lets you create one or more wildcard receivers for an application.

Parents. <context>

Children. <wildcard-receiver>.

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual wildcard receiver object configured within this element. Multiple templates can by applied by specifying them in a comma-separated-value manner, i.e., `"RECEIVING1,RECEIVING2"`. Can be overridden by a different template configured for an individual wildcard receiver.	None
`order`	Establishes the permission semantic for each individual wildcard receiver configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <wildcard-receiver> XML attribute `rule`.	`deny,allow`

Example:

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

1.3.3.8.1. <wildcard-receiver>

Description. The <wildcard-receiver> element contains option values for a single wildcard receiver.

Parents. <wildcard-receivers>.

Children. <options>.

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to use for the wildcard receiver object's options.	None
`rule`	Permits or restricts the creation of the wildcard receiver object. If `rule="deny"`, the object errors upon creation.	`allow`
`pattern`	The wildcard receiver topic string pattern for this wildcard receiver object.	None
`pattern-type`	The type of pattern matching to use for the wildcard receiver object. Valid values are `pcre`, `regex` or `application-callback`.	`pcre`

Example:

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

1.3.3.9. <event-queues>

Description. The <event-queues> Element is a container element for all UM event queues configured for an application. UM lets you create one or more event queues for an application.

Parents. <application>.

Children. <event-queue>.

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual event queue object configured within this element. You can apply multiple templates specifying them in a comma-separated-value manner, e.g., `"EVQ-1,EVQ-2"`. A template applied to an individual event queue will override an `<event-queues>`-level template.	None
`order`	Establishes the permission semantic for each individual event queue configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <event-queue> XML attribute, `rule`.	`deny,allow`

Example:

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

1.3.3.9.1. <event-queue>

Description. The <event-queue> element contains option values for a single event queue.

Parents. <event-queues>.

Children. <options>.

XML Attributes:

XML Attribute	Description	Default Value
`name`	Name of the event queue. Used as a parameter for `lbm_event_queue_attr_create_from_xml()` and `lbm_event_queue_attr_set_from_xml()`.	None
`template`	Name of the configuration template to use for the event queue object's options.	None
`rule`	Permits or restricts the creation of the event queue object. If `rule="deny"`, the object errors upon creation.	`allow`

Example:

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

1.3.3.10. <hfxs>

Description. The <hfxs> element is a container for all UM HFX objects configured for an application. Within the <hfxs> element, options are organized by topic.

Parents. <application>

Children. <topic>

XML Attributes:

XML Attribute	Description	Default Value
`template`	Name of the configuration template to apply to each individual HFX object configured within this element. Multiple templates can by applied by specifying them in a comma-separated-value manner, i.e., `"SENDING1,SENDING2"`. Can be overridden by a different template configured for an individual HFX object.	None
`order`	Establishes the permission semantic for each individual HFX object configured within this element. Valid values are `deny,allow` (deny what you specify, allow everything else) or `allow,deny` (allow what you specify, deny everything else). Works in conjunction with the <topic> XML attribute, `rule`.	`deny,allow`

Example:

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

1.3.3.11. <application-data>

Description. The <application-data> element is a free-form text comment field that you can use to store application-specific or options-group-specific metadata. When defined at the options level, this content overrides <application-data> elements defined at the application level.

Your application can retrieve this data via the lbm_*_attr_getopt() and lbm_*_attr_str_getopt() API functions under the option name application_data. You can also programmatically set it using the equivalent *_setopt() APIs. The application_data option is defined for all option scopes.

Also, you can set or retrieve this value at runtime via the *_getopt() and *_setopt() functions defined for the following types:

lbm_context_t
lbm_src_t
lbm_rcv_t
lbm_wildcard_rcv_t
lbm_event_queue_t
lbm_hfx_t

Parents. <application>. <options>.

Children. None.

XML Attributes:

XML Attribute	Description	Default Value
`xml:space`	How whitespace is handled. `default` trims leading and trailing whitespace (e.g., tabs, spaces, linefeeds, etc.), and compresses multiple whitespace characters into a single space character. `preserve` preserves the whitespace exactly as read.	`default`

Example:

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

1.3.4.1. Using the Order and Rule XML Attributes

The order and rule XML attributes combine to enable you to permit or restrict the creation of primitive UM objects. The container elements such as the <contexts>, <sources>, <receivers>, etc. have the order attribute. The single object elements, such as the <context>, <topic>, etc., have the rule attribute. The default for both attributes allows creation of all objects. You can however, exert some administrative control over your applications by allowing the creation of only certain objects.

You can vary the order attribute values to suit whether permission or restriction is more prevalent. In the example below, only a single topic needs to be restricted, so we use the default values for the order attribute with only a single topic restricted with a rule="deny" attribute.

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

In contrast, the following example requires the creation of only a single receiver topic object, so you can change the order attribute to allow,deny, which restricts the creation of all receiver topic objects except the one allowed.

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

You can also combine topic names with topic patterns. In the example below, we set the order attribute to the default. Topic ISM is denied with its order attribute. Topics IRM and SRM satisfy both their own allow rules and the pattern *R* deny rule. So when you allocate a source topic with lbm_src_topic_alloc(), UM accepts the rule that matches the order attribute default, which is allow.

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

As a result of the above configuration, UM allows the creation of source topic objects IRM and SRM, and all other topics, except those that match the pattern *R*.

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>

Prev	Home	Next
Plain Text Configuration Files	Up	Configuration File Restrictions