2. Upgrading from 2.4.14.3 to 4.3.0

See Important: How to Use this Guide, if you haven’t already.

The following sections describe how to upgrade from Connext Micro 2.4.14.3 to Connext Micro 4.3.0. They describe general, wire, and other compatibility issues between Connext Micro 4.3.0 and previous releases.

Attention

For important information on new and removed platforms and features in Connext Micro 4.3.0, see Supported Platforms and Programming Languages and What’s New in 4.3.0 in the Connext Micro documentation.

See RTI Connext Performance Benchmarks for performance details in this release.

2.1. New Installation Procedure

Starting with release 3.0.0, Connext Micro is now distributed as an RTI Connext platform package. Connext Micro is installed as any other additional package from RTI. See Installing RTI Connext.

The Connext Micro User’s Manual is also available from the Help panel in RTI Launcher. You can find information about how to build Connext Micro in the Connext Micro User’s Manual.

2.2. Application Binary Interface

Connext Micro does not provide Application Binary Interface (ABI) compatibility with previous versions of Connext Micro. Therefore, an application compiled using a version of Connext Micro prior to 3.0.0 must be recompiled when moving to a version of Connext Micro at or after 3.0.0.

In most cases, to upgrade your application to Connext Micro 4.3.0, you must recompile your application source using the new header files and link with the new Connext Micro libraries.

Note

If you have a source bundle, you must do the following to upgrade your application:

  1. Build the Connext Micro libraries from the provided source code.

  2. Recompile your application source using the new header files.

  3. Link with the new libraries built from the Connext Micro source.

Refer to Building the source for instructions on how to build Connext Micro from source.

In some cases, minor modifications to your application code may be required; any such changes are noted in this Migration Guide.

2.3. API Compatibility

The following Application Program Interfaces (APIs) have been changed or deprecated in 4.3.0. For new APIs, see the Connext Micro Release Notes.

2.3.1. Subscription unicast locator

To reduce the memory usage of discovery in Connext Micro 4.3.0, the DDS_SubscriptionBuiltinTopicData.unicast_locator API has been changed to a DDS_LocatorExSeq and must be accessed using the DDS_LocatorExSeq API.

2.3.2. Changed return code

In Connext Micro 4.3.0, DPSE_DiscoveryPluginProperty_initialize returns BAD_PARAMETER instead of PRECONDITION_NOT_MET. If your application checks for PRECONDITION_NOT_MET for this API, update it to check for BAD_PARAMETER instead.

2.3.3. Wchar and wstring language binding changes

Starting in Connext 6.0.0 (and Connext Micro 3.0.0), for C, traditional C++, and Ada languages, the mapping of an IDL wchar has changed from a 4-byte integer to a 2-byte integer. DDS_Wchar is now mapped to DDS_UnsignedShort instead of DDS_UnsignedLong. This change may lead to some compilation warnings when compiling old Connext applications with libraries in Connext 6 (and Connext Micro 3.0.0) and higher. If so, you will need to fix these compilation warnings.

Wire interoperability with Connext 5.x and lower (and Connext Micro 2.4.x and lower) is not broken as long as you continue using the Extended CDR encoding version 1 data representation (see the Data Representation chapter in the RTI Connext Core Libraries Getting Started Guide Addendum for Extensible Types), because the wire representation of a wchar and wstring is still the same.

2.3.4. Generated code compatibility

For Connext Micro applications defining types in IDL, XML, or XSD, moving from a previous Connext Micro version to Connext Micro 4.3.0 requires code regeneration and recompilation.

You will need to regenerate the code for your application types using the Code Generator shipped with this release. The regeneration process is very simple; you only need to run the new version of Code Generator using the original input IDL file. (You should see a message that says you are running rtiddsgen version 4.3.1.) This process will regenerate the header and source files, which can then be compiled along with the rest of your application.

2.3.5. Generated applications compatibility

Micro Application Generator (MAG) templates were updated in Connext Micro 4.3.0. If a QoS policy is only partially specified in the XML file, rtiddsmag will fill in the missing attributes with the corresponding default values defined in Connext Micro, instead of MAG’s own set of default values.

If you are migrating XML source files to rtiddsmag in Connext Micro 4.3.0, check that your QoS policies are fully defined OR that the default values defined in the API Reference will not break your application’s functionality.

2.3.6. Default UDP socket buffer size on QNX changed to 64KB

In 3.0.0, the default socket buffer size on QNX has changed from 256KB to 64KB. You can change the default socket buffer sizes when you configure the UDP transport. Please refer to the Connext Micro User’s Manual for more information.

2.3.7. Misspelled macro name

The macro OSAPI_LogProperty_INIITALIZER was misspelled and has been corrected to OSAPI_LogProperty_INITIALIZER in 4.3.0. While the previous macro still exists, we recommend changing to the correct name.

2.3.8. DDS_DURATION_INFINITE value changed

The numerical value for the constant DURATION_INFINITE_SEC has changed to 0x7fffffff for standards compliance. If your application used 0xffffffff directly, it should be updated to use 0x7fffffff. We recommend using DURATION_INFINITE_SEC instead of the numeric value.

2.4. Library Compatibility

2.4.1. Library structure

Connext Micro 3.0.3 and earlier versions were provided as source code to compile into core libraries. These core libraries included all the basic functionality of Connext Micro, as well as the required operating system (OS) and network stack integration. We referred to these as “integrated libraries.”

Starting with Connext Micro 4.1.0, RTI provides two core library types: Platform Independent Libraries (PILs), which contain the basic Connext Micro functionality, and Platform Support Libraries (PSLs), which include the OS and network stack integration for a specific platform. We refer to these as “split libraries.” RTI provides PILs and PSLs as precompiled binaries, with the option to build your own PSL from source code if desired. For more information, refer to Library types in the Connext Micro documentation.

When migrating an application to Connext Micro 4.3.0, refer to the following subsections for instructions on how to maintain compatibility with split libraries.

2.4.1.1. Build the PSL (optional)

RTI provides precompiled Connext Micro PSLs for several common platforms. Refer to Supported Platforms and Programming Languages for a list of these platforms. If you plan to use Connext Micro on a supported platform, you can use the provided PSL without building it yourself. The precompiled PSLs are located in the lib/ directory of your Connext Micro installation.

Alternatively, you can build the PSL from source code included in your Connext Micro installation. For instructions, refer to Building the PSL in the Connext Micro documentation.

2.4.2. XTypes

Starting in Connext Micro 4.2.0, support for Extensible Types (XTypes) has been extracted from the core library rti_me into a new, separate library rti_me_ddsxtypes. The XTypes module was integrated into rti_me in Connext Micro 4.1.0. The functionality remains unchanged.

By default, rtiddsgen will generate code that requires the rti_me_ddsxtypes library. However, if you pass -interpreted 0 to rtiddsgen when generating code, this library is not needed.

Note

The CERT profile does not support the rti_me_ddsxtypes library. You must pass -interpreted 0 to rtiddsgen when compiling IDL code for the CERT profile.

Refer to Link applications and libraries in the Connext Micro documentation for information on linking your applications.

2.5. Transport Compatibility

2.5.1. Zero Copy v2

Due to a fixed bug in Connext Micro 4.2.0, the Zero Copy v2 transport is not backwards compatible with applications using previous versions of Connext Micro (4.1.0 and below). Refer to What’s Fixed in 4.2.0 for more information. To ensure compatibility, migrate other applications using Zero Copy v2 to Connext Micro 4.2.0.

2.5.2. UDP

Starting in 4.1.0, Connext Micro does not automatically register the UDP transport, due to the structure of split libraries. In order to use the UDP transport included in the PSL, you must add the following code to your application before creating a DomainParticipant:

/* Register the UDP transport */
struct UDP_InterfaceFactoryProperty *udp_property;

/* allocate and set udp_property */

RT_Registry_register(registry,NETIO_DEFAULT_UDP_NAME,
        UDP_InterfaceFactory_get_interface(),
        (struct RT_ComponentFactoryProperty*)udp_property,NULL),

DDS_StringSeq_set_maximum(&participant_qos.transports.enabled_transports,1);
DDS_StringSeq_set_length(&participant_qos.transports.enabled_transports,1);
*DDS_StringSeq_get_reference(&participant_qos.transports.enabled_transports,0) = DDS_String_dup("_udp");

DDS_StringSeq_set_maximum(&participant_qos.discovery.enabled_transports,1);
DDS_StringSeq_set_length(&participant_qos.discovery.enabled_transports,1);
*DDS_StringSeq_get_reference(&participant_qos.discovery.enabled_transports,0) = DDS_String_dup("_udp://");

DDS_StringSeq_set_maximum(&participant_qos.user_traffic.enabled_transports,1);
DDS_StringSeq_set_length(&participant_qos.user_traffic.enabled_transports,1);
*DDS_StringSeq_get_reference(&participant_qos.user_traffic.enabled_transports,0)
= DDS_String_dup("_udp://");