|
Configuration Guide
|
Many UM primitive objects have a corresponding attributes object, which contains the configuration information specific to that UM object type. You can set configuration options in an attributes object, and supply the attributes when creating the UM object. This allows assignment of different options for different instances of UM objects. The following table lists the UM primitive objects and corresponding attributes objects.
| UM object | Corresponding Attributes Object(s) |
|---|---|
| lbm_context_t | lbm_context_attr_t |
| lbm_topic_t | lbm_src_topic_attr_t, lbm_rcv_topic_attr_t |
| lbm_wildcard_rcv_t | lbm_wildcard_rcv_attr_t |
| lbm_event_queue_t | lbm_event_queue_attr_t |
| lbm_hfx_t | lbm_hfx_attr_t |
You call API functions to create attributes objects and set, retrieve, or delete their values. These API names are based on the attributes object name and are shown in the following table, using the context object as an example. See the C API for all attributes APIs.
| Action | UM API function |
|---|---|
| Create Attributes Object | lbm_context_attr_create_from_xml() |
| Set Option from Binary Value | lbm_context_attr_setopt() |
| Set Option from String Value | lbm_context_attr_str_setopt() |
| Get Option as Binary Value | lbm_context_attr_getopt() |
| Get Option as String Value | lbm_context_attr_str_getopt() |
| Delete Attributes Object | lbm_context_attr_delete() |
For other object types, replace context with src_topic, rcv_topic, wildcard_rcv, event_queue, or hfx.
The following sections describe in detail the use of these UM API functions. The APIs related to lbm_context_attr_t objects are used for the purpose of illustration, but the instructions (if not the specifics) apply to all UM attributes objects.
In the following example, the call to lbm_context_attr_create_from_xml() creates the custom attributes object, and initializes each option from the current default values. Subsequent calls to lbm_context_attr_setopt() or lbm_context_attr_str_setopt() modify only the option values in the attributes object.
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().
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 API.) The final two parameters in the API are a pointer to a variable containing the option value, and a variable of type size_t that contains the correct length of the option value variable.
The example code below sets three options. First, we set operational_mode (context) to sequential. Then we set the transport_tcp_port_low (context) and transport_tcp_port_high (context) values to 4901 and 4920, respectively.
There are some configuration options which expect an array of a particular type. The *_setopt() API uses its "optlen" parameter to determine the number of valid elements in the array.
For example, when using umq_ulb_application_set (source) to configure a ULB source's application sets, the lbm_umq_ulb_receiver_type_entry_t structure is used to define one mapping between receiver type ID and application set index. It is common to have more than one receiver type and/or more than one application set, so the application code must pass an array of lbm_umq_ulb_receiver_type_entry_t structures. Note how lbm_src_topic_attr_setopt()'s "optlen" is calculated in the following code:
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.
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 correct for the specified option.
In the example code below, we get the option values for operational mode and the transport TCP port low and high values.
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, we get the option values for operational mode and the transport TCP port low and high values.
Once the attributes object is no longer needed, it should be deleted.