The options described in this section are for persistence, and are invalid for users of the UMS (streaming-only) product.

See the Guide for Persistence for more information.

Reference <-

ume_ack_batching_interval (context) <-

: The interval between checks by a persistent receiver of consumed, unacknowledged messages.

: This option is used in conjunction with ume_use_ack_batching (receiver).

: See Persistence Message Consumption for a full explanation of consumption acknowledgements.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

Scope:	context
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	100 (0.1 seconds)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMS 5.0, UME 5.0, UMQ 5.0.

ume_activity_timeout (receiver) <-

: Establishes the period of time from a receiver's last activity to the release of the receiver's Reg ID. Stores return an error to any new request for the receiver's Reg ID during this period.

: Overrides the receiver-activity-timeout setting configured for the receiver's topic on the Store. The default value of 0 (zero) disables this option.

: See also Persistence Proxy Sources.

Scope:	receiver
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	0 (disables timeout)
When to Set:	Can only be set during object initialization.

ume_activity_timeout (source) <-

: Establishes the period of time from a source's last activity to the release of the source's Reg ID. Stores return an error to any new source requesting the source's Reg ID during this period.

: If proxy sources are enabled (ume_proxy_source (source)), the Store does not release the source's Reg ID and UM elects a proxy source. Overrides the source-activity-timeout setting configured for the source's topic on the Store. The default value of 0 (zero) disables this option.

: If neither proxy sources nor ume_state_lifetime (source) are configured, the Store also deletes the source's state and cache.

Warning: When a source registers with the Store, the value provided for ume_activity_timeout is saved in the state file for that source. However, if that source is deleted and re-created, the newly-configured value does not overwrite the value saved in the state file. I.e. if a new value is desired and the source's configuration updated, it is not sufficient to simply "bounce" the source. The Store's state and cache files for that source must also be deleted, meaning that a receiver will not be able to recover those deleted messages. Updating this configuration option should be done only during a maintenance window where the state and cache files can be deleted.

: See also Persistence Proxy Sources.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	0 (disables timeout)
When to Set:	Can only be set during object initialization.

ume_allow_confirmed_delivery (receiver) <-

: Specifies whether a persistent receiver sends confirmed delivery notifications back to the source.

: See also ume_confirmed_delivery_notification (source).

: For more information, see Delivery Confirmation Concept.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UM 5.0.

Value

Description

1

Indicates that receivers can send confirmed delivery notifications. Default for all.

0

Indicates that receivers can not send confirmed delivery notifications.

ume_application_outstanding_maximum (receiver) <-

: This persistent receiver option enables the persistence Throttled Delivery feature and sets an upper threshold on the number of message fragments from a single source that are delivered or in an event queue, but not yet consumed.

: When the number of message fragments exceeds this threshold, the receiver stops buffering all incoming message fragments. Thus, messages from the source transport stream might be dropped and recovered via OTR or persistence late-join mechanisms.

: This feature effectively limits the recovery rate and live stream rate to the receiver message consumption rate. If OTR is disabled for the receiver, this threshold applies only during initial Late Join recovery. Setting this option to 0 (zero) disables the persistence Throttled Delivery feature.

Scope:	receiver
Type:	lbm_ulong_t
Units:	message fragments
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.7

ume_confirmed_delivery_notification (source) <-

: Flag indicating the application is interested in receiving notifications of consumption of messages by receivers (confirmed delivery) via the source event mechanism.

: Generates the source events LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION and/or LBM_SRC_EVENT_UME_DELIVERY_CONFIRMATION_EX. When turned off, receivers do not send delivery confirmation notifications to the source unless the release policy dictates the need for them. For more information, see Delivery Confirmation Concept.

Note: Smart Sources do not support delivery confirmation.

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value	Integer value	Description
"0"	LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_NONE	The source does not wish to receive delivery confirmation notifications. Default for all.
"1"	LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_PER_FRAGMENT	The source wishes to receive delivery confirmation notifications for all messages and message fragments.
"2"	LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_PER_MESSAGE	The source wishes to receive only one delivery confirmation for a message regardless of how many fragments it comprised.
"3"	LBM_SRC_TOPIC_ATTR_UME_CDELV_EVENT_FRAG_AND_MSG	The source wishes to receive delivery confirmation notifications for all messages and message fragments. In addition, the notification contains a WHOLE_MESSAGE_CONFIRMED flag when the last fragment of a message has been delivered.

ume_consensus_sequence_number_behavior (receiver) <-

: The behavior that the receiver will follow when determining the consensus sequence number used as the sequence number to begin reception at upon re-registration after a failure or suspension.

: This option is only used when quorum-consensus is also used on the source.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.

String value

Integer value

Description

"lowest"

LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_LOWEST

Consensus is determined as the lowest of the latest sequence numbers seen from any Store.

"majority"

LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_MAJORITY

Consensus is determined as the latest sequence number agreed upon by the majority of Stores within a group. Between groups, the latest of all majority decisions is used. Default for all.

"highest"

LBM_RCV_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_HIGHEST

Consensus is determined as the highest of the latest sequence numbers seen from any Store.

ume_consensus_sequence_number_behavior (source) <-

: The behavior that the source follows when determining the consensus sequence number used as the first message of a source upon re-registration after a failure or suspension.

: This option is only used when quorum-consensus is also used.

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value

Integer value

Description

"lowest"

LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_LOWEST

Consensus is determined as the lowest of the latest sequence numbers seen from any Store.

"majority"

LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_MAJORITY

Consensus is determined as the latest sequence number agreed upon by the majority of Stores within a group. Between groups, the latest of all majority decisions is used.

"highest"

LBM_SRC_TOPIC_ATTR_UME_QC_SQN_BEHAVIOR_HIGHEST

Consensus is determined as the highest of the latest sequence numbers seen from any Store. Default for all.

ume_explicit_ack_only (receiver) <-

: Transfers responsibility for sending consumption ACKs to the application.

: Normally, the client UM library performs implicit batching of consumption acknowledgements to the Store. This option tells UM that the application will call lbm_msg_ume_send_explicit_ack() to explicitly trigger consumption acknowledgements to the Store. This has historically been done by the application to implement ACK batching.

: However, as of UM 5.0 with the introduction of ume_use_ack_batching (receiver), UM will now perform ACK batching by default.

Warning: If explicit ACKs are used, the application must ensure that messages are ACKed in the order received. See ACK Ordering.

: See Persistence Message Consumption for a full explanation of consumption acknowledgements.

Note: This option is incompatible with ume_use_ack_batching (receiver). If ACK batching is turned on, this option is silently turned off. If both are turned on, the last one configured turns off the other.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.

Value

Description

1

The receiving application will generate acknowledgements explicitly and the persistent receiver should not automatically generate them.

0

The persistent receiver will automatically generate and send acknowledgements based on message consumption. Default for all.

ume_flight_size (source) <-

: Specifies the number of persisted message fragments allowed to be in flight (not stabilized at a Store and without delivery confirmation).

: If an application attempts to exceed flight size, the message send function will either block or trigger a notification source event, depending on ume_flight_size_behavior (source).

: Note that the flight size can also be limited by ume_flight_size_bytes (source), if supplied. Flight size would be exceeded if either one is exceeded.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

: Note: for very small flight sizes, it is recommended to configure the Store's UM config option response_tcp_nodelay (context) to 1.

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

ume_flight_size_behavior (source) <-

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

: See ume_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

String value

Integer value

Description

"Block"

LBM_FLIGHT_SIZE_BEHAVIOR_BLOCK

The send call blocks when a source sends a message that exceeds its flight size. If the source uses 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. UM also sends a source event notification if the number of in-flight messages falls below the configured flight size.

ume_flight_size_bytes (source) <-

: Specifies the number of bytes of persisted message payload allowed to be in flight (not stabilized at a Store and without delivery confirmation).

: If an application attempts to exceed flight size, the message send function will either block or trigger a notification source event, depending on ume_flight_size_behavior (source).

: If this option is not supplied (defaults to 0), a persisted source uses ume_flight_size (source) to determine if a send would exceed flight size.

: If this option is supplied, a persisted source uses both ume_flight_size_bytes and ume_flight_size (source). Flight size would be exceeded if either one is exceeded.

: If the source uses RPP, then this option must be supplied, and its value is sent to the Store during registration. The Store compares it to the configured value of source-flight-size-bytes-maximum. The source's registration will be rejected if ume_flight_size_bytes exceeds the Store's source-flight-size-bytes-maximum.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

: Note: for very small flight sizes, it is recommended to configure the Store's UM config option response_tcp_nodelay (context) to 1.

Scope:	source
Type:	lbm_uint64_t
Units:	bytes
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

ume_force_reclaim_function (source) <-

: Callback function (and associated client data pointer) that is called when a source is forced to release a retained message due to size limitations specified.

: This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.

Scope:	source
Type:	lbm_ume_src_force_reclaim_func_t
Default value:	NULL
When to Set:	Can only be set during object initialization.
Config File:	Cannot be set from an UM configuration file.

ume_late_join (source) <-

: Flag indicating the source should allow late join operation for receivers and persistent Stores.

: This option is retained for backwards compatibility. The late_join (source) option should be used instead.

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

Value

Description

1

The source allows late join receivers and persistent Stores.

0

The source does not allow late join receivers or persistent Stores. Default for all.

ume_message_stability_lifetime (source) <-

: The total time in milliseconds from the initial send of a message before a persistent source gives up entirely on receiving a stability acknowledgement for the message.

: The source then delivers a forced reclaim notice to the application, indicating that UM could not verify stability of the message (not guaranteed).

: See Proactive Retransmissions.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	1200000 (20 minutes)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 6.0

ume_message_stability_notification (source) <-

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

: Even when turned off, Stores continue to send message stability notifications to the source for retention purposes. However, no notification will be delivered to the application.

Note: Smart Sources only support "0" (none) or "2" (per-message).

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value	Integer value	Description
"0"	LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_NONE	The source does not wish to receive message stability notifications from the Store.
"1"	LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_PER_FRAGMENT	The source wishes to receive all message and message fragment stability notifications from the Store. Default for all.
"2"	LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_PER_MESSAGE	The source wishes to receive only a single message stability notifications from the Store when the entire message has been stabilized. This notification contains the Sequence Number of the last fragment of the whole message but does NOT contain Store information.
"3"	LBM_SRC_TOPIC_ATTR_UME_STABLE_EVENT_FRAG_AND_MSG	The source wishes to receive all message and message fragment stability notifications from the Store. In addition, the notification contains a WHOLE_MESSAGE_STABLE flag when the last fragment of a message has been stabilized.

ume_message_stability_timeout (source) <-

: The time in milliseconds from initial send of a message until it is resent by the source because the source has not received a stability acknowledgement for the Store (or a quorum of Stores).

: Setting this option to 0 (zero) disables the Proactive Retransmissions feature.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	5000 (5 seconds)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 6.0

ume_proactive_keepalive_interval (context) <-

: Maximum period of inactivity after which a persistent receiver proactively sends an acknowledgement to the Store.

: A persistent receiver sends consumption acknowledgements to the Store to update that receiver's state in the Store. In the absence of new consumption acknowledgments, a receiver will re-send the most-recent acknowledgement periodically to maintain that state. The ume_proactive_keepalive_interval option specifies the maximum interval between successive acknowledgements. This value should be set less than the ume_activity_timeout (receiver) and the state lifetime, ideally no more than 1/3 of the lesser of those two. Valid settings are greater than or equal to 1500 (1.5 seconds, the effective minimum), or zero to disable proactive keepalives and revert to pre-UM 6.9 keepalive behavior.

: Note that disabling proactive keepalives is generally not recommended, and cannot be done for a persistent receiver which is assigned to a Transport Services Provider (XSP).

Scope:	context
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	3000 (3 seconds)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 6.9.1

ume_proxy_source (source) <-

: Controls whether any Stores with which the source registers should provide a proxy source in the event the actual source terminates.

: Proxy source support is only available for quorum/consensus Store configurations. In addition, proxy source support requires that the source register with an actual registration ID, and not request that the Store assign it a registration ID.

Scope:	source
Type:	int
Default value:	0
When to Set:	Can only be set during object initialization.

Value

Description

1

Enables proxy source support.

0

Disables proxy source support. Default for all.

ume_receiver_liveness_interval (context) <-

: The maximum interval between delivery confirmations or keepalive messages send to the source.

: Expiration of this interval triggers another keepalive and an interval reset.

Scope:	context
Type:	int
Units:	milliseconds
Default value:	0 (disable; do not send keepalives)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.2.

ume_receiver_paced_persistence (receiver) <-

: Enables Receiver-paced Persistence (RPP) for the receiver, and specifies the blocking behavior.

: The source controls whether the Store's repository behavior is SPP or RPP (see ume_receiver_paced_persistence (source)). The receiver's configuration must match how the source set the repository. If the repository and receiver disagree, the receiver's registration is rejected.

: See RPP: Receiver-Paced Persistence for general information on RPP.

Scope:	receiver
Type:	lbm_uint8_t
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3. Value "2" was added in UME 6.9

String value

Integer value

Description

"0"

0

Indicates that the receiver is not a RPP receiver. Default for all.

"1"

1

Indicates that the receiver is a blocking RPP receiver.

"2"

2

Indicates that the receiver is a non-blocking RPP receiver.

ume_receiver_paced_persistence (source) <-

: Requests that the Store operate its repository with Receiver-paced Persistence (RPP).

: During registration with the Store, this option controls whether the source requests RPP behavior. If the source requests RPP, and the Store's repository is configured with repository-allow-receiver-paced-persistence set to 1 (enabled), the registration is accepted and the Store operates with receiver pacing. If repository-allow-receiver-paced-persistence is 0 (disabled), the source's registration is rejected.

: If this option is not set, the Store will default to Source-paced Persistence (SPP), independent of the setting of repository-allow-receiver-paced-persistence. The Store cannot be directly configured to enable RPP; the source must be configured to request it.

: See RPP: Receiver-Paced Persistence for general information on RPP.

Scope:	source
Type:	lbm_uint8_t
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

Value

Description

1

Source requests RPP operation.

0

Source does not request RPP operation. Store will operate with Source-paced Persistence (SPP). Default for all.

ume_recovery_sequence_number_info_function (receiver) <-

: Callback function (and associated client data pointer) that is called when a receiver is about to complete registration from the Stores in use by the source and the low sequence number is to be determined.

: The application has the ability to modify the sequence number to use if it desires.

: This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.

Scope:	receiver
Type:	lbm_ume_rcv_recovery_info_ex_func_t
Default value:	NULL
When to Set:	Can only be set during object initialization.
Config File:	Cannot be set from an UM configuration file.

ume_registration_extended_function (receiver) <-

: Callback function (and associated client data pointer) that is called when a receiver is about to attempt to register with a persistent Store.

: The app must return the registration ID to request from the Store or 0 if it will allow the Store to allocate one. This function passes additional extended information, such as the Store being used and a source client data pointer, etc.

: This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.

Scope:	receiver
Type:	lbm_ume_rcv_regid_ex_func_t
Default value:	NULL
When to Set:	Can only be set during object initialization.
Config File:	Cannot be set from an UM configuration file.

ume_registration_function (receiver) <-

: Callback function (and associated client data pointer) that is called when a receiver is about to attempt to register with a persistent Store.

: The app must return the registration ID to request from the Store or 0 if it will allow the Store to allocate one.

: This callback is called by the context thread and can not use an event queue. Therefore the callback function used should not block or it will delay reception of latency-sensitive messages.

: This option is retained for backwards compatibility. The ume_registration_extended_function (receiver) option should be used instead.

Scope:	receiver
Type:	lbm_ume_rcv_regid_func_t
Default value:	NULL
When to Set:	Can only be set during object initialization.
Config File:	Cannot be set from an UM configuration file.

ume_registration_interval (receiver) <-

: The interval between registration attempts by the receiver to a persistent Store in use by the source.

: For networks with large numbers of receivers connecting to a Store, this value can be increased to reduce the registration load on the Store.

Scope:	receiver
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	3000 (3 seconds)
When to Set:	Can only be set during object initialization.

ume_registration_interval (source) <-

: The interval between registration attempts by the source. Before declaring Registration Complete, sources wait at least one full interval, unless all Stores have registered.

: When using the round-robin Store behavior, this is the value between registration attempts with the various Stores. In other words, attempt to register with primary, wait interval, attempt to register with secondary, wait interval, etc.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	3000 (3 seconds)
When to Set:	Can only be set during object initialization.

ume_repository_ack_on_reception (source) <-

: For RPP, requests that the Store operate its repository with "ack on reception" behavior.

: Normally, the Store sends stability ACKs to the source as messages are written to disk. With "ack on reception" behavior, the Store sends stability ACKs to the source as the messages are received and stored in its memory cache.

: During registration with the Store, this option controls whether the source requests "ack on reception" behavior. If the source requests "ack on reception", and the Store's repository is configured with repository-allow-ack-on-reception set to 1 (enabled), the registration is accepted and the repository operates with "ack on reception" behavior. If repository-allow-ack-on-reception is 0 (disabled), the source's registration is rejected.

: The Store cannot be directly configured to enable "ack on reception"; the source must be configured to request it.

: This option is ignored for SPP repositories.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

Scope:	source
Type:	lbm_uint8_t
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

Value

Description

1

Source requests "ack on reception".

0

Source does not request "ack on reception". Store defaults to sending stability ACKs when messages are written to disk. Default for all.

ume_repository_disk_file_size_limit (source) <-

: For Receiver-paced Persistence (RPP) sources, overrides the Store's configured repository disk file size limit.

: The Store's repository disk file size limit is configured by the repository-disk-file-size-limit option. For RPP, this source option can be used to override the Store's setting.

: See repository-disk-file-size-limit for more information on the option.

: This option is ignored for SPP repositories.

: When the source overrides the Store's configured value, it must not exceed that value. If the source's ume_repository_disk_file_size_limit exceeds the Store's repository-disk-file-size-limit, the source's registration is rejected.

: See Implementing RPP for more information on the coordination between RPP source and Store configuration options.

Scope:	source
Type:	lbm_uint64_t
Units:	bytes
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

ume_repository_size_limit (source) <-

: For Receiver-paced Persistence (RPP) sources, overrides the Store's configured repository size limit.

: The Store's repository size limit is configured by the repository-size-limit option. For RPP, this source option can be used to override the Store's setting.

: See repository-size-limit for more information on the option.

: This option is ignored for SPP repositories.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

: When the source overrides the Store's configured value, it must not exceed that value. If the source's ume_repository_size_limit exceeds the Store's repository-size-limit, the source's registration is rejected.

Scope:	source
Type:	size_t
Units:	bytes
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

ume_repository_size_threshold (source) <-

: For Receiver-paced Persistence (RPP) sources, overrides the Store's configured repository size threshold.

: The Store's repository size threshold is configured by the Store option repository-size-threshold option. For RPP, this source option can be used to override the Store's setting.

: See repository-size-threshold for more information on the option.

: This option is ignored for SPP repositories.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

: When the source overrides the Store's configured value, it must not exceed that value. If the source's ume_repository_size_threshold exceeds the Store's repository-size-threshold, the source's registration is rejected.

Scope:	source
Type:	size_t
Units:	bytes
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3

ume_retention_intergroup_stability_behavior (source) <-

: The behavior that the source will follow when determining, across multiple Store QC groups, both message stability and registration completion.

: A source cannot release a message until the message is stable. To be stable, a message must first be stable within the group and then stable between

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value	Integer value	Description
"any", "any-group"	LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ANY	Registration is complete when it is complete in any group. Messages are stable when they are stable in any group. Default for all.
"all-active"	LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL_ACTIVE	A group is active if it has at least a quorum of registered Stores. Registration is complete when it is complete in all active groups. At least one group must be active. Messages are stable when they are stable in all active groups.
"majority"	LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_MAJORITY	Registration is complete when it is complete in a majority of groups. Messages are stable when they are stable in a majority of groups.
"all", "all-groups"	LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL	Registration is complete when it is complete in all groups. Messages are stable when they are stable in all groups.

ume_retention_intragroup_stability_behavior (source) <-

: The behavior that the source will follow when determining, within a Store QC group, both message stability and group registration completion.

: A source cannot release a message until the message is stable. For a source to consider a message stable, some number of Stores must acknowledge stability to the Source. By default, a quorum of Stores in the Store QC group must acknowledge stability. But there are other choices, indicated below.

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value

Integer value

Description

"quorum"

LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_QUORUM

Registration is complete for the group when a majority of the Stores in the group are registered. A message is stable within the group when a majority of the Stores have acknowledged the message as stable. Default for all.

"all-active"

LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL_ACTIVE

Registration is complete for the group when a majority of the Stores in the group are registered. Stores registered with a source are active Stores. A message is stable within the group when each active Store in that group has acknowledged the message as stable.

"all", "all-stores"

LBM_SRC_TOPIC_ATTR_UME_STABLE_BEHAVIOR_ALL

Registration is complete for the group when all Stores in the group are registered. A message is stable within the group when all Stores in the group are registered and have acknowledged the message as stable.

ume_retention_size_limit (source) <-

: The release policy regarding aggregate size limit before messages are forced to be released.

: This option is retained for backwards compatibility. The retransmit_retention_size_limit (source) option should be used instead.

: With Smart Sources, this option is ignored. Retention buffers are preallocated.

Scope:	source
Type:	size_t
Units:	bytes
Default value:	25165824 (24 MB)
When to Set:	Can only be set during object initialization.

ume_retention_size_threshold (source) <-

: The release policy regarding aggregate size threshold before messages are released.

: With Smart Sources, this option is ignored. Retention buffers are preallocated.

: This option is retained for backwards compatibility. The retransmit_retention_size_threshold (source) option should be used instead.

Scope:	source
Type:	size_t
Units:	bytes
Default value:	0 (no threshold)
When to Set:	Can only be set during object initialization.

ume_retention_unique_confirmations (source) <-

: The release policy regarding the number of confirmations from different receivers required before the source can release a message.

: This option enhances, but does not supersede, message stability notification from the Store(s). If the number of unique confirmations for a message is less than this amount, the message will not be released. If the number of unique confirmations for a message exceeds or equals this amount, then the message may be released if no other release policy setting overrides the decision. A value of 0 indicates there is no unique number of confirmations required for reclamation. For more information, see Delivery Confirmation Concept.

Note: Smart Sources do not support delivery confirmation.

Scope:	source
Type:	size_t
Units:	number of confirmations
Default value:	0 (none required)
When to Set:	Can only be set during object initialization.

ume_session_id (context) <-

: Specifies the default Session ID to use for sources and receivers within a context. A value of 0 (zero) indicates no Session ID is to be set.

: See also Managing RegIDs with Session IDs. 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. Prior to LBM 5.2.2, all persistence session IDs were interpreted as hexadecimal, and did not accept the '0x' prefix. If upgrading from an earlier version to LBM 5.2.2 or later, prepend '0x' to the original setting to use the originally assigned session ID.

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 LBM 4.2/UME 3.2

ume_session_id (receiver) <-

: Specifies the Session ID to use for a receiver. A value of 0 (zero) indicates the context ume_session_id will be used.

: See also Managing RegIDs with Session IDs.

: 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. Prior to LBM 5.2.2, all persistence session IDs were interpreted as hexadecimal, and did not accept the '0x' prefix. If upgrading from an earlier version to LBM 5.2.2 or later, prepend '0x' to the original setting to use the originally assigned session ID.

Scope:	receiver
Type:	lbm_uint64_t
Default value:	0 (uses context session ID)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in LBM 4.2/UME 3.2

ume_session_id (source) <-

: Specifies the Session ID to use for a source. A value of 0 (zero) indicates the context ume_session_id will be used.

: See also Managing RegIDs with Session IDs.

: 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. Prior to LBM 5.2.2, all persistence session IDs were interpreted as hexadecimal, and did not accept the '0x' prefix. If upgrading from an earlier version to LBM 5.2.2 or later, prepend '0x' to the original setting to use the originally assigned session ID.

Scope:	source
Type:	lbm_uint64_t
Default value:	0 (uses context session ID)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in LBM 4.2/UME 3.2

ume_source_liveness_timeout (context) <-

: The expected maximum interval between keepalive or delivery confirmation messages from a receiver.

: If neither are received within the interval, the source declares the receiver "dead".

Scope:	context
Type:	int
Units:	milliseconds
Default value:	0 (disable; do not track receivers)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.2.

ume_sri_flush_sri_request_response (source) <-

: This option determines if a source flushes the Implicit Batching buffer after it sends a Source Registration Information (SRI) record in response to a SRI request from a receiver.

: Flushing this buffer places the SRI record immediately on the transport, which speeds up the process of receivers registering, but also can impose a greater load on the overall network since it can reduce the amount of transport batching.

: See ume_sri_immediate_sri_request_response (source) for more information on SRI messages.

Note: Smart Sources do not support batching, so this option is ignored by a Smart Source.

Scope:	source
Type:	lbm_ulong_t
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.0

Value

Description

1

The source places a SRI record in the Implicit Batching buffer and then flushes the buffer.

0

The source places a SRI record in the Implicit Batching buffer and lets normal batch scheduling determine when to place the SRI on the transport. Default for all.

ume_sri_immediate_sri_request_response (source) <-

: This option controls how quickly a source responds to a receiver's request for an SRI record.

: A persistent source need to send information about its Stores so that the receivers can properly register with those Stores. The information messages sent by the sources, contained in a Source Registration Information (SRI) record, is sent on the source's data transport session, and therefore have an effect on the transfer of application data messages. This configuration option is provided to assist you in managing the impact of SRI messages on the normal flow of data when a registering receiver requests the SRI record.

Note: Smart Sources do not support batching, so this option is ignored by a Smart Source.

Scope:	source
Type:	lbm_ulong_t
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.0

Value

Description

1

Indicates that the source sends an SRI record and also flushes the implicit batching buffer to immediately put the SRI record on the transport. This maximizes the speed at which a receiver completes its registration, but also can impose a greater load on the overall network since it can reduce the amount of transport batching. Default for all.

0

Indicates that the source waits for the period of time defined by ume_sri_request_response_latency (source) before sending an SRI record. This reduces overall system load, especially if multiple receivers are registering, as it allows a single SRI record to satisfy the registration needs of multiple receivers.

ume_sri_inter_sri_interval (source) <-

: This option controls how frequently a source sends SRI records in reaction to a change in the source's registration with its Stores.

: Source Registration Information (SRI) records are sent by a source to its receivers for either of two reasons:

a receiver has requested an SRI, usually because it is in the process of initializing and registering, or

the source sees a change in its registration with its Stores. For example, if a Store becomes unresponsive and the source loses registration with it. Or if a previously failed Store returns to service, and the source successfully registers with it.

: This configuration option is concerned with the latter case (change in a source's registration with its Stores): the source will send SRI records to receivers to inform them of the change. It sends multiple copies over time to maximize the chances of successful reception. It uses this configuration option to determine the interval between these SRI sends.

: The default value results in the source sending 2 SRI packets every second. This value cannot be set to 0. See also ume_sri_max_number_of_sri_per_update (source).

Scope:	source
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 UMP 6.0

ume_sri_max_number_of_sri_per_update (source) <-

: The maximum number of SRI packets sent by a source after a change in the source's registration with its Stores.

: For more information about these SRI messages, see ume_sri_inter_sri_interval (source).

Scope:	source
Type:	lbm_uint16_t
Default value:	20
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.0

ume_sri_request_interval (receiver) <-

: The interval at which a registering receiver requests information about the persistent Store(s) from the source.

: The receiver cannot complete registration with the Store(s) until the source supplies the information, in the form of a Store Information Record (SRI). If no SRI is received within this interval, the receiver will continue to send requests until either the information is received, or until the ume_sri_request_maximum (receiver) is reached. If that limit is reached without having received the SRI, the receiver registration fails.

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

ume_sri_request_maximum (receiver) <-

: The maximum number of requests the receiver issues for a Store Information Record (SRI) from the source.

: If the receiver has not received an SRI after this number of requests, it stops requesting and fails its registration. See ume_sri_request_interval (receiver).

Scope:	receiver
Type:	lbm_ulong_t
Default value:	60
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.0

ume_sri_request_response_latency (source) <-

: The interval a source waits before sending an SRI packet in response to a request from a receiver.

: At the expiration of this interval, the SRI record may also be slightly delayed by normal batch scheduling unless ume_sri_flush_sri_request_response (source) is set to 1.

: See ume_sri_immediate_sri_request_response (source) for more information about how and why to use this.

Note: Smart Sources do not support batching, so this option is ignored by a Smart Source.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	100 (0.1 seconds)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMP 6.0

ume_state_lifetime (receiver) <-

: Establishes the period of time from a receiver's last activity to the deletion of the receiver's state and cache by the Store.

: You can also configure a receiver-state-lifetime for the receiver's topic on the Store. The Store uses whichever is shorter. The default value of 0 (zero) disables this option.

: See also Persistence Proxy Sources.

Scope:	receiver
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	0 (disables lifetime)
When to Set:	Can only be set during object initialization.

ume_state_lifetime (source) <-

: Establishes the period of time from a source's last activity to the deletion of the source's state and cache by the Store, regardless of whether a proxy source has been created or not.

: You can also configure a source-state-lifetime for the source's topic on the Store. The Store uses whichever is shorter. The default value of 0 (zero) disables this option.

: See also Persistence Proxy Sources.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	0 (disables lifetime)
When to Set:	Can only be set during object initialization.

ume_store (source) <-

: Enable persistence for this source and add a Store specification to the current list of Stores specified for the source. Unlike most other UM options, every time this option is supplied, it adds another Store specification to the list and does NOT overwrite previous specifications.

: Each entry contains the IP address, TCP port, registration ID, and group index for the Store. For the configuration file as well as API string setting functions, the string value for this option is formatted as "DomainID:IP:port:RegID:GroupIDX" where DomainID is the Store's UM domain ID, IP is the Store's IP address, port is the TCP port for the Store, RegID is the registration ID that the source desires to use, and GroupIDX is the group index that the Store belongs to. The DomainID, RegID, and GroupIDX pieces may be omitted from the string if desired. If so, UM assumes the value of 0 for them.

: With most configuration options, a previously-specified value can be overridden by simply specifying the option again with a new value. However, because each occurrence of ume_store adds a new Store specification, use the IP address 0.0.0.0 and TCP port 0 to remove all previously specified Stores. This allows subsequent Store specifications to, in effect, override the earlier Stores.

: One or more Stores means the source will use persistence. If no Stores are specified, then persistence will not be provided for the source.

When the binary form of option setting is used, UM does NOT expect an array of structures. Instead, only one Store specification can be supplied for each call to lbm_src_topic_attr_setopt(). However, when the binary form of option retrieval lbm_src_topic_attr_getopt() is used, the list of Stores is returned as an array, and the optlen parameter should be set as:

optlen = (max_num_stores * sizeof(lbm_ume_store_entry_t));

Scope:	source
Type:	lbm_ume_store_entry_t
When to Set:	Can only be set during object initialization.

ume_store_activity_timeout (source) <-

: The timeout value used to indicate when a Store is unresponsive.

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

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	10,000 (10 seconds)
When to Set:	Can only be set during object initialization.

ume_store_behavior (source) <-

: The behavior that the source follows for handling Store failures.

: Only quorum-consensus is allowed. The option is retained for backwards compatibility purposes.

Scope:	source
Type:	int
When to Set:	Can only be set during object initialization.

String value	Integer value	Description
"qc", "quorum-consensus"	LBM_SRC_TOPIC_ATTR_UME_STORE_BEHAVIOR_QC	The source uses multiple Stores at the same time based on Store and Store QC group configuration. Default for all.

ume_store_check_interval (source) <-

: The interval between activity checks of the current Store.

: This interval also governs how often a source checks outstanding unstabilized messages to see if they have reached the configured ume_message_stability_timeout (source) value yet.

Scope:	source
Type:	lbm_ulong_t
Units:	milliseconds
Default value:	500 (0.5 seconds)
When to Set:	Can only be set during object initialization.

ume_store_group (source) <-

: Add a Store QC group specification to the list of Store QC groups specified for the source.

: Unlike other UM settings, every time this option is called, it adds another Store QC group specification to the list and does NOT overwrite previous specifications. Each entry contains the group index and group size for the group. For the configuration file as well as string versions of setting this option, the string value is formatted as "GroupIDX:GroupSZ" where GroupIDX is the index of the group and GroupSZ is the size of the group. Because each entry adds a new Store specification and does not overwrite previous values, an entry or string with the group index of 0 and group size of 0 will cause all previous Store QC group specifications to be removed.

: Note: When setting this option multiple times, you must set this option in group-index order, from lowest to highest. In other words, do not set this option for a group index lower in value than any previously set group index value.

When the binary form of option setting is used, UM does NOT expect an array of structures. Instead, only one group specification can be supplied for each call to lbm_src_topic_attr_setopt(). However, when the binary form of option retrieval lbm_src_topic_attr_getopt() is used, the list of groups is returned as an array, and the optlen parameter should be set as:

optlen = (max_num_store_groups * sizeof(lbm_ume_store_group_entry_t));

Scope:	source
Type:	lbm_ume_store_group_entry_t
When to Set:	Can only be set during object initialization.

ume_store_name (source) <-

: Add a named Store specification to the list of Stores specified for the source.

: Unlike other UM settings, every time this option is called, it adds another Store specification to the list and does NOT overwrite previous specifications. Each entry contains the Store context name, registration ID, and group index for the Store. For the configuration file as well as string versions of setting this option, the string value is formatted as "name:RegID:GroupIDX" where "name" is the context name of the Store, (configured with the Store option context-name), "RegID" is the registration ID that the source desires to use, and "GroupIDX" is the group index that the Store belongs to. The RegID and GroupIDX pieces may be left off the string if desired. If so, then the value of 0 is assumed for them. Store context names are restricted to 128 characters in length, and may contain only alphanumeric characters, hyphens, and underscores.

When the binary form of option setting is used, UM does NOT expect an array of structures. Instead, only one named Store specification can be supplied for each call to lbm_src_topic_attr_setopt(). However, when the binary form of option retrieval lbm_src_topic_attr_getopt() is used, the list of named Stores is returned as an array, and the optlen parameter should be set as:

optlen = (max_num_stores * sizeof(lbm_ume_store_name_entry_t));

Scope:	source
Type:	lbm_ume_store_name_entry_t
When to Set:	Can only be set during object initialization.

ume_use_ack_batching (receiver) <-

: Enables automatic batching of consumption acknowledgements by a persistent receiver.

: Automatic batching of consumption acknowledgements improves average latency and throughput of a persistent receiver. The batching timer is set with ume_ack_batching_interval (context).

Warning: If this option is disabled, the application must ensure that messages are ACKed in the order received. See ACK Ordering.

: See Persistence Message Consumption for a full explanation of consumption acknowledgements.

Note: This option is incompatible with ume_explicit_ack_only (receiver). If explicit ACK is turned on, this option is silently turned off. If both are turned on, the last one configured turns off the other.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UMS 5.0, UME 5.0, UMQ 5.0.

Value

Description

1

UM automatically sends acknowledges of batches of consumed messages to the persistent Store. Default for all.

0

The application directly controls the sending of acknowledgements to the persistent Store.

ume_use_late_join (receiver) <-

: Flag indicating if the receiver should participate in late join operation or not.

: This option is retained for backwards compatibility. The use_late_join (receiver) option should be used instead.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.

Value

Description

1

The receiver will participate in using late join if requested to by the source. Default for all.

0

The receiver will not participate in using late join even if requested to by the source.

ume_use_store (receiver) <-

: Flag indicating if the receiver should participate in using a persistent Store or not.

: If "0" is supplied, the receiver will join as a streaming receiver.

Scope:	receiver
Type:	int
When to Set:	Can only be set during object initialization.

Value

Description

1

The receiver will participate in using a persistent Store if requested to by the source. Default for all.

0

The receiver will not participate in using a persistent Store even if requested to by the source.

ume_user_receiver_registration_id (context) <-

: 32-bit value that is used as a user set identifier to be included as the receiver registration ID in acknowledgements send by any receivers in the context to sources as confirmed delivery notifications.

: The value is not interpreted by UM in any way and has no relation to registration IDs used by the receiver. A value of 0 indicates no user set value is in use and should not be sent with acknowledgements

Scope:	context
Type:	lbm_uint_t
Units:	identifier
Default value:	0 (no user set value in use)
When to Set:	Can only be set during object initialization.

ume_write_delay (source) <-

: For Receiver-paced Persistence (RPP) sources, overrides the Store's configured write delay setting.

: The Store's write delay setting is configured by the repository-disk-write-delay option. For RPP, this source option can be used to override the Store's setting.

: See repository-disk-write-delay for more information on the option.

: This option is ignored for SPP repositories.

: For RPP, see RPP Configuration Specifics for interactions between this and other configuration options. See RPP: Receiver-Paced Persistence for general information on RPP.

: When the source overrides the Store's configured value, it must not exceed that value. If the source's ume_write_delay exceeds the Store's repository-disk-write-delay, the source's registration is rejected.

Scope:	source
Type:	lbm_uint32_t
Units:	milliseconds
Default value:	0 (disabled)
When to Set:	Can only be set during object initialization.
Version:	This option was implemented in UME 5.3