Configuration Guide

Ultra Messaging Queuing Options

The options described in this section are for queuing, and are invalid for users of the UMS (streaming-only) and UMP (streaming and persistent) products.

See the Guide for Queuing for more information.

# Reference <-

## umq_command_interval (context) <-

  The interval at which all currently outstanding UMQ commands (registrations, de-registrations, message list commands, indexed queueing commands, etc.) are re-sent if they have not yet been acknowledged by the queue.

  Applies to brokered queue and ULB. For general information on queuing, see Queuing.

  Scope: | context
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 500 (0.5 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_command_outstanding_maximum (context) <-

  The maximum number of UMQ commands (registrations, de-registrations, message list commands, indexed queueing commands, etc.) that may be outstanding at one time for each configured queue.

  This option value must be greater than 0. Reducing this value may help alleviate some load on the UMQ queue daemon, but may potentially cause registrations and other commands to take longer to complete.

  Scope: | context
  Type: | lbm_uint32_t
  Units: | number of outstanding commands
  Default value: | 1000
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UMQ 5.3.1.

## umq_delayed_consumption_report_interval (receiver) <-

  The maximum interval to delay sending consumption reports on the receiver.

  Applies to ULB. For general information on queuing, see Queuing.

  Delaying consumption reports allows them to be batched together for efficiency but at the expense of delaying the consumption reports themselves individually. The value of 0 indicates the consumption reports should not be delayed.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 0
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_hold_interval (receiver) <-

  The maximum interval to hold control and data information within the ULB delivery controller.

  For ULB only. For general information on queuing, see Queuing.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 10000 (10 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_index_assignment_eligibility_default (receiver) <-

  Controls whether new ULB receivers are immediately eligible for index assignment upon registration with a ULB source (the default), or whether they are ineligible upon registration and must be explicitly made eligible via a call to lbm_rcv_umq_index_start_assignment().

  For ULB only. For general information on queuing, see Queuing.

  Scope: | receiver
  Type: | int
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.2/UME 3.2/UMQ 1.2

  String value | Integer value | Description
  --- | --- | ---
  "Eligible" | LBM_RCV_TOPIC_ATTR_UMQ_INDEX_ASSIGN_ELIGIBILITY_ELIGIBLE | The receiver may be assigned indices as soon as it registers with a queue. Default for all.
  "Ineligible" | LBM_RCV_TOPIC_ATTR_UMQ_INDEX_ASSIGN_ELIGIBILITY_INELIGIBLE | The receiver must first call lbm_rcv_umq_index_start_assignment() before it can be assigned any indices.

## umq_message_stability_notification (source) <-

  Flag indicating the source is interested in receiving notifications of message stability from UMQ via the source event mechanism.

  Even when turned off, UMQ continues to send message stability notifications to the source for retention purposes. However, UMQ delivers no notification to the application.

  Scope: | source
  Type: | int
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

  Value | Description
  --- | ---
  1 | The source wishes to receive message stability notification. Default for all.
  0 | The source does not wish to receive message stability notifications.

## umq_msg_total_lifetime (source) <-

  Establishes the period of time from when a queue enqueues a message until the time the message cannot be assigned or reassigned to a receiver. The queue deletes the message upon expiration of the lifetime.

  Applies to brokered queue and ULB. For general information on queuing, see Queuing.

  The default value of 0 (zero) disables this option. See also Message Lifetime.

  Scope: | source
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 0 (disable lifetime)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.2 / UME 3.2 / UMQ 2.1

## umq_queue_activity_timeout (context) <-

  The timeout value used to indicate when a queue is marked inactive.

  The queue must be active within this interval to be marked inactive. This value must be much larger than the check interval.

  Scope: | context
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 3000 (3.0 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_queue_participation (receiver) <-

  Flag indicating if the receiver desires to participate in Queuing operations or not.

  For general information on queuing, see Queuing.

  Scope: | receiver
  Type: | int
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

  String value | Integer value | Description
  --- | --- | ---
  "1" | 1 | The receiver desires to participate in Queuing operations. Default for all.
  "0" | 0 | The receiver does not wish to participate in Queuing operations.

## umq_queue_registration_id (context) <-

  Add a broker/registration ID pair to the current list of broker/registration ID pairs.

  Assigns a Registration ID when connected to the given broker name, using the format "BrokerName:RegID". If a broker is not named or a broker does not support names, the broker will be given the name "Default".

  If a Registration ID is set for a given broker, that Registration ID is passed from the source through to the receiver. This information can be used to identify the source from which the data originated.

  Each time you set this option, it adds another BrokerName:RegID pair to a list and does not overwrite previous specifications. If you supply an empty name, the list resets.

  When the binary form of option setting is used, UM does NOT expect an array of structures. Instead, only one broker/registration ID pair specification can be supplied for each call to lbm_context_attr_setopt(). However, when the binary form of option retrieval lbm_context_attr_getopt() is used, the list of broker/registration ID pairs is returned as an array, and the `optlen` parameter should be set as:

      optlen = (max_num_regid_broker_pairs * sizeof(lbm_umq_queue_entry_t));

  Scope: | context
  Type: | lbm_umq_queue_entry_t
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_receiver_type_id (receiver) <-

  32-bit value that is used as an identifier to instruct the ULB source as to the type of receiver the receiver should be.

  Used by the ULB source to associate various settings with the connecting receiver.

  For ULB receivers, see Application Sets and Receiver Type IDs for more information.

  Scope: | receiver
  Type: | lbm_uint_t
  Units: | identifier
  Default value: | 0
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_retransmit_request_interval (receiver) <-

  The interval between retransmission request messages to the ULB source.

  Applies to ULB. For general information on queuing, see Queuing.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 500 (0.5 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_retransmit_request_outstanding_maximum (receiver) <-

  The maximum number of messages to request at a single time from the ULB source.

  Applies to ULB. For general information on queuing, see Queuing.

  A value of 0 indicates no maximum.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | messages
  Default value: | 100
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 3.6/UME 3.0/UMQ 1.0.

## umq_session_id (context) <-

  Specifies the Session ID to use for managing ULB sources and receivers within a context.

  For ULB only.

  A value of 0 (zero) indicates no Session ID is to be set. Valid formats for session IDs are as follows: A hexadecimal string with a maximum value of FFFFFFFFFFFFFFFE, prefixed with '0x'. An octal string with a maximum value of 1777777777777777777776 prefixed with '0'. A decimal string with a maximum value of 18446744073709551614.

  Scope: | context
  Type: | lbm_uint64_t
  Default value: | 0 (no session ID)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in UMQ 5.3.

## umq_ulb_application_set (source) <-

  Defines the application sets for a ULB source. Format: "Index1:ID1,ID2,...;Index2:ID3,ID4,..."

  "Index1" is the numeric index which defines an application set, and "ID1" is the numeric receiver type ID associated with one or more receivers (see umq_receiver_type_id (receiver)).

  At least one application set must be specified for the source to use ULB.

  The application set indices in the string can be specified in any order. However, they must be numbered contiguously starting with 0 when the topic is allocated.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  For more information on application sets, see Application Sets and Receiver Type IDs.

  Scope: | source
  Type: | lbm_umq_ulb_receiver_type_entry_t
  Default value: | empty (at least one is required)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_assignment_function (source) <-

  The assignment function for one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the desired assignment function associated that application set.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

  String value | Integer value | Description
  --- | --- | ---
  "default" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_ASSIGNMENT_DEFAULT | The default assignment function. Default for all.
  "random" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_ASSIGNMENT_RANDOM | Randomized assignment function.

## umq_ulb_application_set_events (source) <-

  The events mask of one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the event mask to be set associated that application set.

  The values may follow the same format as described in umq_ulb_events (source).

  Application sets not listed default to a mask of 0.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a mask of 0)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_load_factor_behavior (source) <-

  The behavior for the load factor for one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the load factor behavior associated that application set.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

  String value | Integer value | Description
  --- | --- | ---
  "ignored" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_IGNORED | Load Factor information not sent and not processed or taken into assignment consideration. Default for all.
  "provisioned" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_PROVISIONED | Load Factor information on number of sources sent and processed as well as taken into consideration to reduce the active portion size for each receiver.
  "dynamic" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_LF_BEHAVIOR_DYNAMIC | Load Factor information sent and processed as well as taken into consideration during assignment to weight receiver choice.

## umq_ulb_application_set_message_lifetime (source) <-

  The message lifetime in milliseconds of one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the message lifetime to be set associated that application set. A message lifetime of 0 means UMQ never discards the message.

  Application sets not listed default to a timeout of 0 [forever].

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a timeout of 0 [forever])
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_message_max_reassignments (source) <-

  The maximum number of message reassignments before UMQ discards a message for one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the maximum number of reassignments associated that application set.

  UMQ applies the initial assignment to this maximum. Setting this option to 1 means that the message will never be reassigned. The default value of 0 means UMQ never discards the message due to too many reassignments.

  Application sets not listed default to a maximum of 0.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a maximum 0 [never discard due to reassignment])
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_message_reassignment_timeout (source) <-

  The message reassignment timeout (in milliseconds) of one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the message reassignment timeout to be set associated that application set.

  Application sets not listed default to a timeout of 10000 (10 seconds).

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a timeout of 10000 [10 sec])
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_receiver_activity_timeout (source) <-

  The receiver activity timeout (in milliseconds) of one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the receiver activity timeout associated that application set.

  Application sets not listed default to an activity timeout of 10000 (10 seconds).

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a timeout of 10000 [10 sec])
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_receiver_keepalive_interval (source) <-

  The interval (in milliseconds) between keepalive messages to receivers for one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the receiver keepalive interval associated that application set.

  Application sets not listed default to an activity timeout of 1000 (1 second).

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | empty (all application sets have a timeout of 1000 [1 sec])
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_application_set_round_robin_bias (source) <-

  The bias assignment towards unassigned receivers for one or more application sets specified as a list of entries in the format, "Index1:value1;Index2:value2;..."

  "Index1" is the numeric index which defines an application set, and "value1" is the round robin bias associated that application set.

  Large values increase the bias toward unassigned receivers. Zero (0) disables the bias.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_application_set_attr_t
  Default value: | 1
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_check_interval (source) <-

  The interval upon which ULB sources check for message reassignment, message discards, and receiver liveness.

  See Ultra Load Balancing (ULB).

  Scope: | source
  Type: | unsigned long int
  Units: | milliseconds
  Default value: | 1000 (1 second)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_events (source) <-

  A mask indicating what ULB events should be delivered to the source event callback. Applies to all application sets and receiver types for the source.

  For the configuration file as well as string API method of setting this option, the string value may be formatted as hexadecimal value or a list of enumerated values separated by a '|' or ','.

  Scope: | source
  Type: | lbm_ulong_t
  Units: | mask
  Default value: | 0
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

  String value | Integer value | Description
  --- | --- | ---
  "MSG_CONSUME", "MsgConsume" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_CONSUME (0x1) | Deliver message consumption events.
  "MSG_TIMEOUT", "MsgTimeout" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_TIMEOUT (0x2) | Deliver message timeout/discard events.
  "MSG_ASSIGNMENT", "MsgAssignment" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_ASSIGNMENT (0x4) | Deliver message assignment events.
  "MSG_REASSIGNMENT", "MsgReassignment" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_REASSIGNMENT (0x8) | Deliver message reassignment events.
  "MSG_COMPLETE", "MsgComplete" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_MSG_COMPLETE (0x10) | Deliver message completion events. Messages are complete once they are consumed or discarded from all application sets.
  "RCV_TIMEOUT", "RcvTimeout" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_TIMEOUT (0x20) | Deliver receiver timeout events.
  "RCV_REGISTRATION", "RcvRegistration" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_REGISTRATION (0x40) | Deliver receiver registration events.
  "RCV_DEREGISTRATION", "RcvDeregistration" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_DEREGISTRATION (0x80) | Deliver receiver deregistration events.
  "RCV_READY", "RcvReady" | LBM_SRC_TOPIC_ATTR_UMQ_ULB_EVENT_RCV_READY (0x100) | Deliver receiver ready events.

## umq_ulb_flight_size (source) <-

  Specifies the number of messages allowed to be in flight (unconsumed) before a new message send either blocks or triggers a notification (source event).

  See Ultra Load Balancing (ULB).

  Scope: | source
  Type: | unsigned int
  Units: | messages
  Default value: | 1000
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1.1/UME 3.1.1/UMQ 1.1.1

## umq_ulb_flight_size_behavior (source) <-

  The behavior that UMQ follows when a message send exceeds the source's flight size.

  See umq_ulb_flight_size (source).

  Scope: | source
  Type: | int
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1.1/UME 3.1.1/UMQ 1.1.1

  String value | Integer value | Description
  --- | --- | ---
  "Block" | LBM_FLIGHT_SIZE_BEHAVIOR_BLOCK | The send call blocks when a message send exceeds the source's flight size. If the message send is a non-blocking send, the send returns an LBM_EWOULDBLOCK. Default for all.
  "Notify" | LBM_FLIGHT_SIZE_BEHAVIOR_NOTIFY | A message send that exceeds the configured flight size does not block but triggers a flight size notification (source event), indicating that the flight size has been surpassed. UMQ also sends a source event notification if the number of in-flight messages falls below the configured flight size.

## umq_ulb_receiver_events (source) <-

  Set the events mask of one or more receiver types specified as a list of entries in the format, "ID1:value1;ID2:value2;..."

  "ID1" is the numeric receiver type ID associated with one or more receivers (see umq_receiver_type_id (receiver)), and "value1" is the evet mask to be associated with receivers of that type.

  The values may follow the same format as described in umq_ulb_events (source).

  Receivers with types not listed default to a mask of 0.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_receiver_type_attr_t
  Default value: | empty (all receiver types have a mask of 0)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_receiver_portion (source) <-

  The portion size of one or more receiver types specified as a list of entries in the format: "ID1:value1;ID2:value2;..."

  "ID1" is the numeric receiver type ID associated with one or more receivers (see umq_receiver_type_id (receiver)), and "value1" is the portion size to be associated with receivers of that type.

  Receivers with types not listed default to a portion size of 1.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_receiver_type_attr_t
  Default value: | empty (all receivers have portion size of 1)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_receiver_priority (source) <-

  The priority of one or more receiver types specified as a list of entries in the format, "ID1:value1;ID2:value2;..."

  "ID1" is the numeric receiver type ID associated with one or more receivers (see umq_receiver_type_id (receiver)), and "value1" is the priority to be associated with receivers of that type.

  Receivers with types not listed default to a priority of 0.

  When the binary form of option setting is used, UM expects an array of structures. See Setting an Option from Arrays of Binary Values.

  Scope: | source
  Type: | lbm_umq_ulb_receiver_type_attr_t
  Default value: | empty (all receivers have priority of 0)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.1/UME 3.1/UMQ 1.1.

## umq_ulb_source_activity_timeout (receiver) <-

  The timeout value used to indicate when a ULB source is unresponsive.

  The ULB source must not be active within this interval to be considered unresponsive. This value must be much larger than the source check interval.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 10000 (10 seconds)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.2 / UME 3.2 / UMQ 2.1

## umq_ulb_source_check_interval (receiver) <-

  The interval between activity checks of a ULB source.

  Allow a ULB receiver to proactively attempt re-registration with a ULB source if the receiver has not seen any activity (including keepalives) from that source in a specified amount of time, provided the source's transport session is still alive and valid.

  Scope: | receiver
  Type: | lbm_ulong_t
  Units: | milliseconds
  Default value: | 1000 (1 second)
  When to Set: | Can only be set during object initialization.
  Version: | This option was implemented in LBM 4.2 / UME 3.2 / UMQ 2.1