Configuration Guide

Access to Current Operating Options

After a UM object is created, the current operating option values can be retrieved, and a small subset of its current operating options can be modified. UM API functions supporting such actions operate on the object itself, rather than on an attributes object.

# Retrieving Current Option Values <-

Almost all UM objects allow their current attributes' option values to be retrieved during operation. UM API functions supporting such actions operate on the object itself.

The UM objects which support these actions are lbm_src_t, lbm_rcv_t, lbm_context_t, and lbm_event_queue_t. For each such object, there are corresponding API functions to get an option as a binary value, and get an option as a string value. These API names are based on the object name, suffixed with _getopt(), and _str_getopt(). As an illustration of this convention, the API functions for working with lbm_event_queue_t objects are shown in the following table.

Action | UM API function
--- | ---
Get Option from Binary Value | lbm_event_queue_getopt()
Get Option from String Value | lbm_event_queue_str_getopt()

For other object types, replace event_queue with context, src_topic, rcv_topic, wildcard_rcv, or hfx.

## Getting Current 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 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 */

## Getting Current 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" */

# Modifying Current Option Values <-

A small subset of UM object options may be modified after the object is created. See the individual option descriptions to determine if an options value may be changed after the UM object is created.

The UM objects which support these actions are lbm_src_t, lbm_rcv_t, lbm_context_t, and lbm_event_queue_t. For each such object, there are corresponding API functions to set an option from a binary value and set an option from a string value. These API names are based on the object name, suffixed with _setopt() and _str_setopt().

As an illustration of this convention, the API functions for working with lbm_event_queue_t objects are shown in the following table.

Action | UM API function
--- | ---
Set Option from Binary Value | lbm_event_queue_setopt()
Set Option from String Value | lbm_event_queue_str_setopt()

For other object types, replace event_queue with context, src_topic, rcv_topic, wildcard_rcv, or hfx.

The following sections describe in detail the use of these UM API functions. The APIs related to lbm_event_queue_t objects are used for the purpose of illustration, but the instructions (if not the specifics) apply to all such UM objects.

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

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