Release Notes

UM Version 6.7

The most significant update to UM version 6.7 is interoperability with pre-6.0 versions of UM. Applications and persistent stores at version 6.7 are able to exchange messages and control information with 5.x applications, especially 5.3.6.

However, note that 6.7 applications are not able to interoperate with daemon components of 5.x, including the persistent store and the 5.x gateway. Also, 5.x applications are not able to interoperate with version 6.7 DRO.

Attention
  There are some special upgrade instructions for UM versions 6.7 and beyond that will affect a small percentage of users upgrading from pre-6.7 versions of UM. See Special Upgrade Instructions for 6.7. For general upgrade instructions, see Upgrade Procedure. You are also advised to inspect the full list of Deprecations.

# Enhancements for 6.7 <-

## Streaming Enhancements for 6.7 <-

The following new features and enhancements apply to UMS, UMP, and UMQ products.

- Receive-Side Batching - reduces latency and increases throughput in UM applications by bundling multiple messages to deliver. This bypasses the need to perform a boundary crossing for each delivered message.

  You enable Receiver-Side Batching with configuration option delivery_control_message_batching (context). With C and .NET applications, you must be using an event queue for this feature (this is not a requirement for Java applications).

- The unicast resolver daemon, lbmrd, no longer requires an Ultra Messaging license to run.

- The unicast resolver daemon, lbmrd, now has command-line options to set buffer size in bytes for the receive socket buffer ("-r" flag) and the send socket buffer ("-s" flag).

- In addition to Receive-Side Batching, other improvements have further reduced the latency and increased the throughput of the Java API.

- When an error occurs on a socket while sending an ACK in LBT-RU, UM now generates an EOS immediately.

- You can now set a source activity timeout for LBT-TCP sessions, with new configuration option transport_tcp_activity_timeout (source).

- For UM XML configuration files and UMP store daemon XML configuration files you can use the '`XInclude`' mechanism to merge multiple configuration files.

## Persistence Enhancements for 6.7 <-

The following new features and enhancements apply to UMP and UMQ products.

- Throttled Delivery - you can limit the number of message fragments that a persistent receiver delivers to a receiver application beyond the current highest consumed message fragment. This limits the amount of memory a receiver uses when that receiver consumes messages at rate much slower than the recovery rate from a UMP store or slower than the UMP source stream. To use UMP Throttled Delivery, set the new option ume_application_outstanding_maximum (receiver).

- Enhanced Quorum/Consensus Store Registration and Message Stability

  - Quorum/Consensus functionality is enhanced in the following ways:
    - When setting option ume_retention_intragroup_stability_behavior (source) to '`all-active`', the source requires, minimally, a quorum of stores to successfully stabilize a message within the group.
    - The ume_retention_intragroup_stability_behavior (source) and ume_retention_intergroup_stability_behavior (source) options now apply to registration behavior, as well as message stability behavior. With versions earlier than 6.7, intragroup registration was quorum-based only, and intergroup registration completion always occurred after the first store group was registered.
    - During the first cycle of the ume_registration_interval (source) period, a source does not declare Registration Complete unless all stores in all groups respond. With versions earlier than 6.7, a source declares Registration Complete as soon as all stores in one group respond.
    - During subsequent cycles of the ume_registration_interval (source) period, a source declares Registration Complete as soon as the configured settings for the ume_retention_intragroup_stability_behavior (source) and ume_retention_intergroup_stability_behavior (source) options are satisfied. With versions earlier than 6.7, a source declares Registration Complete as soon as a quorum of stores in one group respond.

- UM now propagates a source's session ID to receivers. The session ID is visible during registration events as well as during the recovery sequence number callback.

## Queuing Enhancements for 6.7 <-

Note
  The brokered queuing and UM JMS functionalities were replaced in version 6.8, so most of these notes do not apply to more-recent versions of UM. However, ULB functionality is retained.

The following new features and enhancements apply to the UMQ product.

## Dynamic Router Enhancements for 6.7 <-

The following new features and enhancements apply to the Dynamic Routing Option (DRO).

- The DRO now checks configuration option values to ensure that they are within valid ranges.
- For DRO XML configuration files you can use the '`XInclude`' mechanism to merge multiple configuration files.

# Fixed Problems and Limitations for 6.7 <-

## Streaming Fixed Problems and Limitations for 6.7 <-

The following bug fixes apply to UMS, UMP, and UMQ products.

Change Request | Description
--- | ---
2551 | With adaptive batching enabled, applications sometimes issue a warning assertion, `WARNING: failed assertion [imbq->stats.ttss_mean<=imbq- >stats.ttcs_mean]` As a solution, since the condition is harmless, the warning is removed.
5242 | Web monitor support link text displays, "29West Ultra Messaging Support". This is now changed to display, "Informatica Ultra Messaging Support".
5626 | Ultra Messaging client XML configuration validation sometimes fails needlessly. As a solution, XML configuration parsing now tolerates invalid values such that you can use a single XML config file or UMM configuration template across multiple platforms, even if it contains option values that are not valid for all platforms.
7261 | If automatic monitoring is misconfigured, instead of silently failing the creation and proceeding with a context or event queue setup, Ultra Messaging now logs the following messages: `Could not create automon controller: CoreApi-5688-3059: automatic monitoring initialization failed [4099] [Transport module source init function returned -1, lbmaux_context_attr_setopt_from_file() failed CoreApi-5688-4374: invalid configuration line in mcast.cfg, line 1: xxxxxxx
7917 | Destroying a source that matches a wildcard pattern, while dispatching an event queue with events from that source, creates a race condition.
7939 | LBT-RU does not indicate in the packet when a datagram is a retransmission. As a solution, Ultra Messaging now marks retransmitted LBT-RU datagrams with a retransmit flag. This flag is visible only with packet dissection tools such as Wireshark.
7944 | Using the function lbm_context_attr_dup() might cause a `src->res_ucast_daemons!=NULL` assert when the original attributes do not contain a setting for the UM configuration option resolver_unicast_daemon (context) and when that option is then set after the original is created.
8024 | For Late Join, OTR, or Request/Response, Ultra Messaging does not perform NAT translation correctly.
8065 | When using DROs, Ultra Messaging applications can cache old data that later can cause errors when creating and deleting wildcard receivers. The Ultra Messaging application context now cleans out this old data when it receives DRO proxy source delete messages.
8108 | Ultra Messaging accepts configuration option resolver_unicast_daemon (context) when it specifies more than one address. As a solution, incorrectly setting this option now issues message `CoreApi-7875-1` indicating that multiple values are not allowed for this option.
8114 | The lbmrd resolver sometimes issues message `LOG Level 6: Core-5688-3375: unicast resolver xxx.xxx.xxx.xxx:xxxx went inactive` while the resolver is active.
8153 | When a receiver receives increasingly large messages, a memory leak might occur.
8150 | Ultra Messaging may now declare fragments requested for retransmission by a receiver from a store as unrecoverable prior to the retransmission request timeout, if all stores have declared that fragment unrecoverable.
8160 | On a 64-bit UNIX platform using a UM XML configuration file, certain context names, event queue names, topic names, and wildcard patterns are not picked up, even though the configuration file specifies them.
8198 | Mellanox Ultra Messaging applications with option ud_acceleration (context) set to 1 were forcing the VMA_SELECT_POLL environment variable to 0, resulting in poor latency performance. Applications can now set VMA_SELECT_POLL to the desired value, or can allow the Mellanox default value.
8277 | LBT-SMX transport statistics include unsupported request/response statistics. As a solution the field lbm_reqs_rcved is renamed to '`reserved1`' in the lbm_rcv_transport_stats_lbtsmx_t structure.
8283 | LBMMON statistics receivers now report correct values for SMX transport statistics.
8295 | The lbmrd unicast resolver daemon propagates certain non-LBMR messages to clients. As a solution, lbmrd now ignores these messages.
8444 | When using LBT-RU and Source Side Filtering, a `bvec->buffs[0]!=NULL` fatal assert can occur when receivers are connecting, messages are being sent, and there is loss and retransmissions. As a solution, Ultra Messaging now takes the proper lock when sending the Source Side Filtering initialization message.
8557 | When you configure LBT-RU context and receiver port ranges to overlap, Ultra Messaging allows this and logs many copies of `Core-5688-1796` messages. As a solution, Ultra Messaging now throttles this message as shown in the following example: `LOG Level 6: THROTTLED MSG: Core-5688-1796: LBT-RU receiver received unknown packet type 6. Origin: 10.29.3.187:16001 0.9995 secs. 0 msgs/sec. 0 bps` `LOG Level 6: ...previous THROTTLED MSG repeated 25 times in 3 seconds`
8591 | Sometimes for invalid receiver configuration combinations, Ultra Messaging repeats warning log messages for every transport joined. As a solution, invalid receiver configuration combinations now issue this warning once at receiver creation time.
8608 | A Java or .NET hot failover receiver that experiences loss might assert with fatal assertion:[d_entry->topic_entry != NULL].
8610 | Message properties do not clear in Java and C# before loading the properties of the next message to be delivered.
8633 | The function lbm_context_process_events() returns -1 for non-critical errors without further description. As a solution, Ultra Messaging no longer returns -1 from lbm_context_process_events() for non-critical errors.
8662 | In the Java API, the array of stores returned by com::latencybusters::lbm::LBMSourceAttributes::getStores() contains an incorrect number of entries when using named stores. In addition to the solution for this, the com::latencybusters::lbm::UMEStoreEntry class now contains a new field to provide store name information.
8682 | The lbm_serialize_response() function does not include the Domain ID in the serialized message. When a serialized response message traverses a DRO to a different topic resolution domain, the message cannot reach the requester, and the lbm_deserialize_response() function logs the following warning: `Core-6259-25: Deserialize Response: Context in domain 1 received response with no domain...` As a solution, serialized response messages now include the topic resolution domain ID.
8726 | If you set ume_retention_unique_confirmations (source) to 0 and ume_confirmed_delivery_notification (source) to 3, the first delivery confirmation sets the UNIQUE_ACKS flag. As a solution, this flag now sets only if you set option ume_retention_unique_confirmations (source) to a value greater than 0 and the number of confirmations received are enough to exceed the threshold.
8732 | With option hf_duplicate_delivery (receiver) and ordered delivery enabled, hot failover receivers might deliver duplicate messages before the original messages. With this solution, messages flagged as duplicate are always be delivered after messages not flagged as duplicate.
8733 | Hot failover receivers might leak memory when processing HF reset commands or when deleted.
8743 | An Ultra Messaging application or daemon fatally asserts with message: `[dest] at line 481 in ../../../../src/lib/lbm/lbmrxrctlr.c` if the application receives malformed data on an Ultra Messaging tcp socket or under other rare conditions.
8797 | Java method com::latencybusters::lbm::LBM::setDebugMask() sets incorrect mask values on 32-bit platforms.
8868 | In the Java and .NET APIs, some objects accessible from an LBMMessage object are sometimes newly created for each LBMMessage delivered, in violation of the Zero Object Delivery (ZOD) functionality. The affected objects include com::latencybusters::lbm::LBMMessageChannelInfo for messages received on a spectrum channel, com::latencybusters::lbm::UMQIndexInfo for queueing messages with an index, and com::latencybusters::lbm::UMQMessageId for all queueing or ULB messages received. As a solution, com::latencybusters::lbm::LBMMessage objects now re-use these object types for each new message delivery, rather than creating new objects. Note You might have applications that no longer work correctly because of this change. To use the '`LBMMessageChannelInfo`', '`UMQIndexInfo`', or '`UMQMessageId`' objects outside of the onReceive callback, you must first make a copy of the object using its constructor, or call promote() on the LBMMessage object.

## Persistence Fixed Problems and Limitations for 6.7 <-

The following bug fixes apply to UMP and UMQ products.

Change Request | Description
--- | ---
1013 | When a umestored configuration file sets the '`<log>`' type attribute to the unsupported value of syslog, the umestored daemon reports the following error message: `daemon section log entity must have a value` As a solution, the umestored daemon now reports the following error message: `daemon log does not currently support syslog type`
3894 | When both registration IDs and session IDs are present, Ultra Messaging issues a log message stating that registration IDs are being ignored, but then fails to ignore them.
5273 | Upon startup, a store could delay persistence of messages for up to the configured retransmit_request_generation_interval value, while attempting to recover messages from the source that the source has already reclaimed. As a solution, the source reports the non-availability of the requested messages back to the store, and the store can begin persistence without extra delay.
5498 | The umestored daemon warns that option resolver_active_threshold (context) is deprecated. This warning is now removed. Setting this option continues to have no effect.
6112 | The umercv sample application prints session IDs in decimal format. As a resolution, all sample applications now print Session IDs in hexadecimal, and continue to print registration IDs in decimal.
7282, 8223 | A store might fail in certain incorrect registration scenarios. As a solution, if applications present invalid session ID and registration ID combinations, they now receive a registration error.
8171 | An RPP-configured source can get an assert with the following log message: `LOG Level 1: FATAL: failed assertion [info->sqn==ctlr->trail_sqn] at line 305 in ../../../../src/lib/lbm/lbmrxsctlr.c` This can happen when the source re-registers with a reduced-fd repository.
8185 | RPP stores can now send a stability ack for a message that was lost but later recovered via retransmission.
8245 | Configuring UMP stores using non-increasing group index order, such as configuring storeA in group 2 before storeB in group 1, causes erroneous registration changes and indeterminate receiver behavior.
8677 | With the Java API, on a Persistence deregistration event, the Ultra Messaging library delivers a com::latencybusters::lbm::UMEDeregistrationCompleteInfo with invalid contents. As a solution, since there is no information associated with this event, the com::latencybusters::lbm::LBMMessage::deregistrationCompleteInfo() method now always returns null.
8704 | Ultra Messaging handles stability acknowledgements on the same thread as retransmissions, affecting the consistency of latency. As a solution, stability acknowledgements now use a different thread.
8710 | With option ume_confirmed_delivery_notification (source) set to 3, after ume_retention_unique_confirmations (source) is reached, the whole message confirmed flag is not set for delivery confirmations for all receivers.
8711 | In the .NET (C#) API, there are no methods to access objects com::latencybusters::lbm::UMESourceEventDeregistrationSuccessInfo and com::latencybusters::lbm::UMESourceEventDeregistrationCompleteInfo. As a solution, the C# library now includes accessor methods.
8747 | Sometimes an application receives and acts upon retransmit response information intended for a different application. This solution makes retransmit requests more unique to the application issuing the request to prevent potential cross-contamination of retransmit response information during application restarts.
8766 | UMP stores might accept messages from a UMP source that has not completed the registration process, resulting in the following fatal assertion: `[EMERGENCY]: FATAL: failed assertion [MUL_SQN_GTE(info->sqn, next_avail_sqn)] at line 1221 in ../../../../src/stored/umerepo.c`
8804 | If there is a disk error modifying the state file on receiver registration, the umestored daemon writes to an invalid location, possibly causing a corrupted state file or umestored segmentation fault. As a solution, umestored no longer writes to an invalid location but instead issues a log-message warning.
8808 | Store daemons sometimes issue a Store-5688-5258 message. As a solution, the umestored configuration code now disallows using multiple async write callbacks. This prevents situations where multiple writes could be executed out of order, causing data corruption.

## Queuing Fixed Problems and Limitations for 6.7 <-

Note
  The brokered queuing and UM JMS functionalities were replaced in version 6.8, so most of these notes do not apply to more-recent versions of UM. However, ULB functionalty is retained.

The following bug fixes apply to the UMQ product.

Change Request | Description
--- | ---
8315 | In the .NET API, Ultra Messaging reuses com::latencybusters::lbm::LBMMessageChannelInfo, com::latencybusters::lbm::UMQMessageId, and com::latencybusters::lbm::UMQIndexInfo objects between different com::latencybusters::lbm::LBMMessage objects for delivery, reducing garbage collection overhead.
8325 | ULB reassigns messages even if option umq_ulb_application_set_message_max_reassignments (source) is set to 1.
8536 | When restarting the UMQ daemon while handling zero-length-messages, the daemon sometimes fails with the following fatal assertion: `[EMERGENCY]: FATAL: failed assertion [msg->lbm_msg!=NULL] at line 3896 in ../../../../src/stored/umqsinc.c`
8601 | An Ultra Messaging application crashes when ULB or UMQ receivers send a Consumption Report for a message after their source transport had been torn down.

## Dynamic Router Fixed Problems and Limitations for 6.7 <-

The following bug fixes apply to the Dynamic Routing Option (DRO).

Change Request | Description
--- | ---
7276 | When using an aggressive keepalive configuration on a DRO peer link, the DRO might fatally terminate.
8256 | When configuring a DRO Peer Connection on a Microsoft Windows machine, the single-tcp configuration option can result in no message traffic across the link. As a solution, Ultra Messaging now handles all documented error conditions, instead of only '`WSAECONNREFUSED`'. This solution addresses issues where a DRO would not reconnect with a peer under timeout conditions.
8303 | A DRO might crash when peer connections between two DROs quickly disconnect and reconnect.
8446 | For Windows and 32-bit UNIX platforms, the web monitor displays non-zero values for the statistic "Transport topic fragments/bytes dropped due to blocking", but Ultra Messaging does not log the message `[information] Gwd-6945-2: Portal [xxx] dropping data due to high volume.`
8459 | Single TCP connections repeatedly disconnect and reconnect under certain conditions.
8461 | DRO peer connections, both dual and single TCP, might encounter an error and not be restarted. One side effect for the solution to this is that the DRO now logs every connection attempt failure, resulting in more log messages if the other peer is not up.
8752 | Error message: `Core-5688-1890: handle events returned error 4 [CoreApi-5688-3837: WFMO: (87) The parameter is incorrect]` sometimes occurs, primarily in a peer portal connection.
8763 | The DRO sometimes asserts with the messages: `WARNING: failed assertion [Portal->peer.adjacent_node_id==0] at line 2679 in ../../../../src/gateway/tnwgpeer.c` and: `FATAL: failed assertion [void_o_entry!=NULL] at line 4205 in ../../../../src/gateway/ tnwgpeer.c`

# Special Upgrade Instructions for 6.7 <-

UM version 6.7 is the first version that supports a smooth upgrade path for UM versions prior to 6.0.

## Disposing Received Messages in Java <-

In earlier versions of UM, it was possible for Java subscribers to simply release all references to a received message and allow Java to garbage collect the message objects.

In UM version 6.7 and beyond, it is necessary for Java subscribers to dispose of all received message objects by calling the com::latencybusters::lbm::LBMMessage::dispose() method after the application is finished using the message object.

See Java Message Reception for more information.

Note that with .NET, there are some simple use cases where it will work to release all references to a received message and let the .NET framework garbage collect the message objects. However, this capability may change in the future. Informatica recommends following the same rules for .NET as for Java.

## Remove lbm_reqs_rcved from SMX <-

In UM version 6.1, the SMX transport was introduced. The UM transport statistics for SMX, lbm_rcv_transport_stats_lbtsmx_t, mistakenly contained a field named "lbm_reqs_rcved". However, the SMX transport does not support request/response. Starting with UM version 6.7, this field was changed to "reserved1".

Users who have written statistics-oriented code should remove any reference to "lbm_reqs_rcved" and rebuild.

## Upgrading From Version Pre-6.0 <-

With the introduction of the DRO, several changes needed to be made to the "wire format" of UM command and control messages. This resulted in 6.0-based applications not being interoperable with pre-6.0 applications. For many customers, this did not pose a significant problem since they were able to upgrade all of their systems in a single step. I.e. there was no need for pre-6.0 applications to exchange messages with 6.0 applications.

However, for many customers, this kind of "flash" upgrade is simply not practical. Therefore, starting with UM version 6.7, an upgrade path was developed which allows different applications to be upgraded at different times, while still allowing those mixed-version applications to exchange messages.

Note
  When you upgrade from a previous version, you must set option ume_store_activity_timeout (source) to 10,000 and UMP store option keepalive-interval to 3,000. This avoids unexpected behavior during a phased upgrade.

To upgrade Ultra Messaging from version 5.3.x to version 6.7 or beyond, perform the following procedure:

1. If the current installation is earlier than 5.3, upgrade all applications and components except UMDS servers to version 5.3.6 or later. (UMDS customers should contact UM Support for upgrade advice.)

2. Pre-6.0 versions of UM are not ABI compatible with 6.0 and beyond. C language application programs must be re-compiled.

3. If using UMP stores, ensure that all source settings for option ume_store_behavior (source) are set to '`qc`' or '`quorum-consensus`', and not '`rr`' or '`round-robin`'.

4. Upgrade all lbmrd resolver daemons to this release. No configuration changes are required.

5. If using UMP stores, upgrade all umestored daemons in groupings that observe the following requirements:
   - A single source cannot specify a mixture of 5.3.x and this release's umestored daemons.
   - Separate sources on the same context can specify daemons of different versions.
   - Do not start upgraded daemons with 5.3.x state and cache files.
   Note
     When upgrading from 5.3.x, if you neglect to set compatibility_include_pre_um_6_0_behavior (context) to 1, receivers incorrectly receive messages without persistence.

6. Upgrade source and receiver applications. You can upgrade these one by one, in any order. As you upgrade each application, set the following configuration options:

   - compatibility_include_pre_um_6_0_behavior (context) to 1
   - transport_tcp_use_session_id (source) to 0

   These settings must remain during the period when the network contains both applications based on 5.3.x and this release.

7. If you use Late Join or OTR, review the settings for Late Join or OTR per-message timeout options. Note that option otr_request_duration (receiver) was deprecated in 6.0, and the following options are added:

   - late_join_info_request_interval (receiver)
   - late_join_info_request_maximum (receiver)
   - retransmit_request_message_timeout (receiver)
   - otr_message_caching_threshold (receiver)
   - otr_request_message_timeout (receiver)

8. After all components are upgraded to this release, set the following configuration options:
   - compatibility_include_pre_um_6_0_behavior (context) to 0
   - transport_tcp_use_session_id (source) to 1

## Log Messages During Upgrade <-

For 5.3.x applications on the same TRD as this release, you might see the following log messages:

LBMC unknown next header 64
  Informational. You can ignore this message. You can reduce the frequency of this message by increasing the value for context option response_tcp_deletion_timeout (context).

LBMR Topic Info Record malformed. Dropping remainder
  Issued for every TIR that contains a TCP Session ID. You must set option transport_tcp_use_session_id (source) to 0 during the interim migration period.

LOG Level 5: Core-5688-3387: LBMR Extended Type 0x7 incorrect (10.29.3.49:40633 len 102). [...D.....<.............1I...........(>..............store-name............ (>.........................$]. Dropping.
  Informational. This occurs if UMP store umestored daemons are present and configured with a discoverable name. For each name advertisement, all contexts drop the packet and log this warning.

[WARNING]: Core-5688-516: LBMC cntl unknown next header: 55.
  Informational. Issued once per transport session when receiving an SRI from a UMP source.

## Previous Special Instructions <-

If you are upgrading from a UM version prior to 6.5, you must also examine the Special Upgrade Instructions for 6.5.

Also see Deprecations.