.. _section-index430: ******************************** Upgrading from 2.4.14.3 to 4.3.0 ******************************** See :ref:`section-Install-Upgrade`, if you haven't already. The following sections describe how to upgrade from |me| 2.4.14.3 to |me| 4.3.0. They describe general, wire, and other compatibility issues between |me| 4.3.0 and previous releases. .. attention:: For important information on new and removed platforms and features in |me| 4.3.0, see `Supported Platforms and Programming Languages `__ and `What's New in 4.3.0 `__ in the |me| documentation. See `RTI Connext Performance Benchmarks `__ for performance details in this release. New Installation Procedure -------------------------- Starting with release 3.0.0, |me| is now distributed as an |rti_core| platform package. |me| 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 |me| in the |me| *User's Manual.* Application Binary Interface ---------------------------- |me| does not provide Application Binary Interface (ABI) compatibility with previous versions of |me|. Therefore, an application compiled using a version of |me| prior to 3.0.0 must be recompiled when moving to a version of |me| at or after 3.0.0. In most cases, to upgrade your application to |me| 4.3.0, you must recompile your application source using the new header files and link with the new |me| libraries. .. note:: If you have a source bundle, you must do the following to upgrade your application: 1. Build the |me| 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 |me| source. Refer to `Building the source `__ for instructions on how to build |me| from source. In some cases, minor modifications to your application code may be required; any such changes are noted in this Migration Guide. 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 `__. Subscription unicast locator ............................ To reduce the memory usage of discovery in |me| 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. Changed return code ................... In |me| 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. Wchar and wstring language binding changes .......................................... Starting in |core| 6.0.0 (and |me| 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 |core| applications with libraries in *Connext* 6 (and |me| 3.0.0) and higher. If so, you will need to fix these compilation warnings. Wire interoperability with |core| 5.x and lower (and |me| 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. Generated code compatibility ............................ For |me| applications defining types in IDL, XML, or XSD, moving from a previous |me| version to |me| 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. Generated applications compatibility .................................... Micro Application Generator (MAG) templates were updated in |me| 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 |me|, instead of MAG's own set of default values. If you are migrating XML source files to *rtiddsmag* in |me| 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. 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. 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. 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. Library Compatibility --------------------- Library structure ................. |me| 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 |me|, as well as the required operating system (OS) and network stack integration. We referred to these as “integrated libraries.” Starting with |me| 4.1.0, RTI provides two core library types: *Platform Independent Libraries* (PILs), which contain the basic |me| 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 |me| documentation. When migrating an application to |me| 4.3.0, refer to the following subsections for instructions on how to maintain compatibility with split libraries. Build the PSL (optional) '''''''''''''''''''''''' RTI provides precompiled |me| PSLs for several common platforms. Refer to `Supported Platforms and Programming Languages `__ for a list of these platforms. If you plan to use |me| 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 |me| installation. Alternatively, you can build the PSL from source code included in your |me| installation. For instructions, refer to `Building the PSL `__ in the |me| documentation. Link your application ''''''''''''''''''''' Because |me| 4.3.0 uses split libraries instead of an integrated core library, you must link your application to both library types (PIL and PSL). Refer to `Link applications and libraries `__ in the |me| documentation for instructions. XTypes ...... Starting in |me| 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 |me| 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 |me| documentation for information on linking your applications. Transport Compatibility ----------------------- Zero Copy v2 ............ Due to a fixed bug in |me| 4.2.0, the Zero Copy v2 transport is not backwards compatible with applications using previous versions of |me| (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 |me| 4.2.0. UDP ... Starting in 4.1.0, |me| 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*: .. code-block:: c /* 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://");