Configuration Guide

Attributes Objects

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.

# Creating An Attributes Object <-

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.

lbm_context_attr_t * attrib;
int rc;
rc = lbm_context_attr_create_from_xml(&attrib, "MyCtx");
if (rc != 0)
{
/* Immediately after UM returns error, capture error details. */
int errnum = lbm_errnum();
const char * errmsg = lbm_errmsg();
fprintf(stderr, "Error %d returned from lbm_context_attr_create_from_xml(), %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().

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

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 */
}

## Setting an Option from Arrays of Binary Values <-

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:

lbm_umq_ulb_receiver_type_entry_t appsets[32]; /* This application's worst case need. */
int optlen, num_valid_elements;
...
/* We need three entries, the equiv of "source umq_ulb_application_set 0:10,20;1:100". */
appsets[0].application_set_index = 0;
appsets[0].id = 10; /* Receiver type ID. */
appsets[1].application_set_index = 0;
appsets[1].id = 20; /* Receiver type ID. */
appsets[2].application_set_index = 1;
appsets[2].id = 100; /* Receiver type ID. */
num_valid_elements = 3;
optlen = num_valid_elements * sizeof(lbm_umq_ulb_receiver_type_entry_t);
rc = lbm_src_topic_attr_setopt(tattr, "umq_ulb_application_set", appsets, optlen);
if (rc != 0) {
/* Handle error */
}

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

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 */
}

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

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

# 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, we get the option values for operational mode and the transport TCP port low and high values.

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" */

# 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 */
}