.. include:: /../getting_started/vars.rst .. _section-General-610: General Compatibility 6.1.0 *************************** This section describes compatibility issues that affect the *Connext* suite in release 6.1.0. Unless noted otherwise, the issues in this section do not apply to |CONNEXT| *Micro*. .. attention:: For important information on new and removed platforms and features in 6.1.0, see :link_connext_whats_new_610:`What's New in 6.1.0 <>`. See also individual products' :link_rti_community_doc_s:`Release Notes <610>`. Platforms ========= .. _section-MG-69: Linking static Linux or QNX libraries with object files built with -fPIC will fail ---------------------------------------------------------------------------------- In 6.1.0, RTI no longer builds Linux or QNX static libraries with the ``-fPIC`` flag (whereas previously RTI did build with this flag). Therefore, you cannot link Linux or QNX static libraries in 6.1.0 with object files built with the ``-fPIC`` flag. You will likely run into this problem if you use the static Linux or QNX library in 6.1.0 while building a shared library. This problem is fixed in release 6.1.1. See :ref:`section-MG-69-611`. New Linux® Linker Flag ---------------------- For GCC 6 or higher, there is a new required linker flag for compiling: ``-no-pie``. See the "Building Instructions for Linux Architectures" table in the :link_connext_platform_notes_610:`Core Libraries Platform Notes <>` for more information. Additional Build Flags for Backtrace Feature -------------------------------------------- Additional build flags, including ``-rydynamic``, are now required for a proper debug build using the backtrace feature. (Backtrace support was added in 6.0.1 and enhanced in 6.1.0.) If these flags are not included, some details like the line number associated with each stack frame may not be available. For further details, look for "Backtrace Support" for your operating system in the :link_connext_platform_notes_610:`Core Libraries Platform Notes <>`. VxWorks Installation Changes ---------------------------- In previous releases, VxWorks® libraries came in one target package, such as ``rti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3.rtipkg``. In this release, the VxWorks targets come in separate files, one for the kernel libraries and one for the rtp libraries: - ``rti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3.rtipkg`` for kernel - ``rti_connext_dds-6.0.1-pro-target-pentium64Vx6.9gcc4.3.3_rtp.rtipkg`` for rtp The rtp libraries are now packaged/installed separately from the kernel package. VxWorks Library Name Changes ---------------------------- In VxWorks rtp architectures, the names of the utilities are now suffixed with a "z" to indicate that they are statically linked: *RTI DDS Ping* is called ``rtiddspingz.vxe``, *RTI DDS Spy* is called ``rtiddsspyz.vxe``, and *RTI DDS Prototyper* is called ``rtiddsprototyperz.vxe``. For more information, see :link_vxworks_embedded_610:`Using DDS Ping and Spy, in the Getting Started Guide Addendum for Embedded Systems <>`. Android Static Libraries no Longer Supported -------------------------------------------- Starting in 6.1.0, RTI no longer supports Android™ static libraries. Android dynamic libraries are still supported. .. MG-94 .. _section-General-Wire-610: Wire Compatibility ================== RTPS Versions ------------- For information about the RTPS versions supported for each |CONNEXT| release, see :link_release_notes_comp:`Compatibility, in the RTI Connext DDS Core Libraries Release Notes <>`. Protocol Changes ---------------- New RTPS BINDING_PING submessage when using RTI Real-Time WAN Transport ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ *Real-Time WAN Transport* uses special RTPS messages called BINDING_PING messages to open NAT bindings and to resolve endpoint locators into public IP transport addresses. These messages are sent periodically at a period configured by the parameter ````, in ``/``. For additional information, see :link_rwt_usersman_610:`RTI Real-Time WAN Transport, in the RTI Connext Core Libraries User's Manual <>`. Changes to PID_DIRECTED_WRITE inline QoS parameter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The `OMG RTPS 2.3 specification `_ defines the GUID in a PID_DIRECTED_WRITE inline QoS parameter as a ****. Previous releases incorrectly serialized the GUID as four integers in native endianness, as opposed to an array of 16 bytes. To conform with the specification, |CONNEXT| now serializes the GUID as an array of 16 bytes. To avoid breaking backward compatibility with previous releases, the GUID is still serialized natively when the remote |DP| has an older |CONNEXT| product version. .. CORE-10122 New DATA_FRAG_SESSION submessage when using fragmentation with MultiChannel DataWriters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ MultiChannel |DWs| (including |DWs| of TopicQuery samples) send fragmented data using a new RTPS submessage called DATA_FRAG_SESSION (submessage ID: 0x81). It is similar to DATA_FRAG, except that there is an additional virtual sequence number field in the submessage. .. important:: This protocol change breaks compatibility with previous releases. A |DR| in a previous release cannot receive MultiChannel or TopicQuery RTPS fragmented data from a |DW| in 6.1.0. See :numref:`section-General-CORE-9335` for additional information. New bit in PID_VENDOR_BUILTIN_ENDPOINT_SET sent with DATA(P) messages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This release introduces a new bit, RTPS_VENDOR_BUILTIN_ENDPOINT_CDS_ANNOUNCER_WRITER (0x00000001 << 6), into the PID_VENDOR_BUILTIN_ENDPOINT_SET parameter sent with DATA(P) messages to indicate that the DATA(P) message is coming from *Cloud Discovery Service*. .. SEC-1244 Extension to DATA_REPRESENTATION PID ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The compression QoS settings are included as part of the :link_datarep_usersman_610:`DATA_REPRESENTATION QosPolicy <>` and are used for endpoint matching during discovery. In general, |CONNEXT| attempts to save bandwidth during endpoint discovery by only propagating QoSs that are set differently from an assumed default value. In the case of ``compression_ids``, if they are not sent during endpoint discovery, the assumed default is that the endpoint (|DW| or |DR|) does not support any compression algorithms. The default setting for a |DR|, however, is to support all available builtin compression algorithms, meaning that the ``compression_ids``, and therefore the entire DataRepresentationQosPolicy, is sent by default in the SubscriptionBuiltinTopicData. This adds an additional 16 bytes to the SubscriptionBuiltinTopicData by default. Setting a |DR|'s ``compression_ids`` to ``COMPRESSION_ID_MASK_NONE`` gets rid of these additional bytes. When ``compression_ids`` are sent to endpoints (|DWs| and |DRs|) during discovery, the additional number of bytes sent is as follows: * 4 bytes for the QoS mutable header: * 2 bytes for parameterId * 2 bytes for parameterLength * 6 bytes for the struct DDS_DataRepresentationIdSeq value: * 4 bytes of sequence length * 2 bytes of default sequence value (short integer) * 2 bytes for padding * 4 bytes for DDS_CompressionIdMask ``compression_ids`` (dds ulong) TOTAL = 16 Bytes New inline QoS Parameters for coherent set samples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 6.1.0 introduces support for coherent access with group presentation (see :link_connext_whats_new_610:`What's New in 6.1.0 <>`). This feature adds the following inline parameters sent with samples that are part of a coherent set: * PID_END_COHERENT_SET (0x8022): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the sequence number of the first sample update belonging to the coherent set from the |DW| publishing the sample. The size of this parameter is 12 bytes. * PID_GROUP_COHERENT_SET (0x0063): Contains the group sequence number of the first sample update belonging to the coherent set across all |DWs| within the *Publisher*. The size of this parameter is 12 bytes. * PID_END_GROUP_COHERENT_SET (0x8023): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the sequence number of the first sample update belonging to the coherent set across all |DWs| within the *Publisher*. The size of this parameter is 12 bytes. * PID_END_COHERENT_SET_SAMPLE_COUNT (0x8024): Vendor-specific parameter associated with an end coherent set sentinel sample. This parameter contains the number of samples contained in the coherent set for a |DW|. The size of this parameter is 8 bytes. .. _section-General-CORE-9335: |DR| in previous release cannot receive MultiChannel or TopicQuery RTPS fragmented data from |DW| in 6.1.0 ---------------------------------------------------------------------------------------------------------- The fix for RTI Issue ID CORE-9335 required breaking backward compatibility with the existing support for RTPS data fragmentation with MultiChannel and TopicQuery. This means that you will not be able to have a |DR| from a previous release receiving MultiChannel or TopicQuery RTPS fragmented data from a 6.1.0 |DW|. .. CORE-9335 .. _section-General-Type-610: Type System Compatibility ========================= Connext applications from previous releases will not interoperate with 6.1.0 and later, for types containing optional primitive members, when data representation is XCDR2 -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- In previous releases, a bug (RTI Issue IDs CORE-10254 and MICRO-2307) led to an incorrect XCDR2 serialization of samples for a type with the following properties: - The type had a primitive member 'Pn' (it could be external but not optional) following another primitive member 'Pn-1' that was marked as optional. - The required alignment for 'Pn' was smaller than or equal to the required alignment for 'Pn-1'. - The optional member was set to NULL in the sample. This issue affected both |CONNEXT| *Micro* and |CONNEXT| *Professional*. It affected the following language bindings: C, C++ (traditional and modern), and DynamicData in all languages. It affected all languages if using ContentFilteredTopics. After fixing this issue, |CONNEXT| applications from before 6.1.0 will not interoperate with |CONNEXT| applications 6.1.0 and later, for *Topics* using the types with the properties described above. .. CORE-10254 C/C++ applications may not interoperate for keyed types under certain conditions -------------------------------------------------------------------------------- In previous releases, a bug (RTI Issue IDs CORE-11290 and MICRO-2987) led to an incorrect XCDR (Extensible CDR version 1) instance keyhash generation for C/C++ applications. This issue only occurred when: - The type was a keyed type containing a key member whose type was a typedef of a keyed struct/valuetype type. - The data representation was XCDR (Extensible CDR version 1). - You generated code using the command-line option ``-optimization 0``. This issue affected both |CONNEXT| *Micro* and |CONNEXT| *Professional*. It affected the following language bindings: C, C++ (traditional and modern). After fixing this issue, C/C++ |CONNEXT| applications from before 6.1.0 will not fully interoperate with |CONNEXT| applications 6.1.0 and later, for *Topics* using the types with the properties described above. As a result, the subscribing application may observe some unexpected behavior related to instances. Specifically, the call to ``DataReader::lookup_instance()`` might fail and return ``HANDLE NIL`` even if the instance was received. .. CORE-11290 .. _section-General-Transport-610: Transport Compatibility ======================= IP Mobility events may stop communication with applications from previous releases ---------------------------------------------------------------------------------- In previous releases, IP mobility events that qualified as a change (for example, the change of the IP address of one of the local interfaces) always triggered the sending of both Participant and Endpoint discovery updates to all the matched remote entities. This was true even in scenarios where, due to the nature of the change, it was enough just to send Participant Discovery updates—for example, when |DWs| and |DRs| were using the default Participant locators (as opposed to setting specific locators through TransportSelection or TransportUnicast QoS policies). This release changes the behavior of |CONNEXT| in this scenario: a Participant will now only send Participant Discovery updates, saving the network bandwidth associated with sending Endpoint Discovery updates. |CONNEXT| will still propagate Endpoint Discovery updates in scenarios where |DWs| and |DRs| are using specific locators instead of the ones inherited from the Participant. This change breaks backwards compatibility with pre-6.1.0 versions of |CONNEXT| once an IP mobility change occurs. Previous versions of |CONNEXT| still need to receive the redundant Endpoint Discovery traffic to process the change. For backwards compatibility, set the property ``dds.participant.discovery_config.force_endpoint_announcement_on_ip_mobility_event`` to true in 6.1.0. .. CORE-10197 .. _section-General-XML-610: XML Compatibility ================= Summary of XML schema changes for XML-Based Application Creation and QoS profiles --------------------------------------------------------------------------------- Release 6.1.0 introduces some changes to the XML schema for |CONNEXT| applications, some of which can break XML configurations from previous releases. :numref:`XMLChanges` lists the changes, which are described in more detail below. .. list-table:: XML Tag Name Changes :name: XMLChanges :widths: 40 60 20 :header-rows: 1 * - Pre-6.1.0 - 6.1.0 - See ... * - Comma-separated decimal or hexadecimal element values for ````, ````, and ```` - ``xs:hexBinary`` format for ````, ````, and ```` - :numref:`section-General-XML-610-CORE-9636` * - ```` - ```` - :numref:`section-General-XML-610-CORE-9734` * - ```` - ```` - :numref:`section-General-XML-610-CORE-9734` * - ```` in ```` - ```` in ```` - :numref:`section-General-XML-610-CORE-9734` * - ```` in ```` and ```` in ```` - ```` in ```` - :numref:`section-General-XML-610-CORE-9734` * - Single-type ```` - Complex-type ```` - :numref:`section-General-XML-610-MAG-136` .. _section-General-XML-610-CORE-9636: |CONNEXT| applications from 6.1.0 and later may fail to parse XML configuration files from previous releases if , , or tags are used ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ Release 6.1.0 updated the type used by ````, ````, and ````. The new representation is an ``xs:hexBinary`` value. The old format, in which the content is provided as a set of comma-separated decimal or hexadecimal element values, will still be accepted by the *Connext* XML parser, except when the value contains a single byte in non-hexadecimal (0x) notation. If a value is a single byte, the XML parser cannot tell whether the value uses the old format or the new one ``xs:hexBinary``. To distinguish between them, a new Processing Instruction, ````, has been added. This Processing Instruction indicates whether the format is hexadecimal or decimal, and it is only needed when the value is a single byte in non-hexadecimal notation. As a result of this change, the following XML example was valid in 6.0.1, but not in 6.1.0: .. code-block:: xml :emphasize-lines: 8,9,10 10 ... ... ... ... Using the above XML will produce an error similar to the following: .. code-block:: text DDS_XMLQos_onEndOctetSequenceElement:Parse error at line XXX: processing instruction missing Pre-6.1.0 XML files that use a single byte value for ````, ````, and ```` will need to be updated as follows by adding the new Processing Instruction. For example: .. code-block:: xml :emphasize-lines: 4 10 ... ... ... ... In the above example, the type of ```` will be considered ``xs:hexBinary``. The old format is still accepted by the *Connext* XML parser, but it will fail validation with the XSD schema. Therefore, even if an XML file with the old format is accepted by the parser, you should transition to the new ``xs:hexBinary`` format, because the XSD schema for QoS profiles will fail to validate the old format. .. Fernando, above says, "The old format is still accepted by the Connext XML parser, but it will fail validation with the XSD schema." What does this mean? Does the XML parser not use the XSD schema for validation? I'm confused: why are we making this distinction? Infrastructure Services use XSD validation to verify the correctness of the input configuration file, and they will fail to load an XML configuration using the old format. In *RTI Routing Service* and *RTI Cloud Discovery Service*, you can use the command-line option ``-ignoreXsdValidation`` to disable XSD validation, but this is not recommended. .. CORE-9636 .. Juanlu, should I move the above paragraph to the Routing Service section? .. _section-General-XML-610-CORE-9734: Use new XML tag names , , and ----------------------------------------------------------------------- Some XML tags were renamed to make the schema compliant with the latest `DDS-XML specification `_. See :numref:`XMLTagNameChanges`. .. note:: These renamed tags affect only XML-Based Application creation and QoS profiles, not Infrastructure Services schemas. See :numref:`section-product-routing-610` if you are using *Routing Service*. .. list-table:: XML Tag Name Changes :name: XMLTagNameChanges :widths: 60 60 :header-rows: 1 * - Pre-6.1.0 tag - 6.1.0 tag * - ```` - ```` * - ```` - ```` * - ```` in ```` - ```` in ```` * - ```` in ```` and ```` in ```` - ```` in ```` The old tags are still accepted by the *Connext* XML parser and the XSD schema to maintain backward compatibility. However, you should transition to the new tags. This issue also affects the Micro Application Generator (MAG). .. CORE-9734 XML fields of type duration have unset tags default to 0 with a warning log message ----------------------------------------------------------------------------------- The duration type tag has two subfields, ```` and ````. Some QoS policies that use these fields, such as the DEADLINE QoS Policy, set the default duration to INFINITE. In previous releases, if you had set just one of these fields (````, but not ````, or vice-versa), the resulting duration value was still INFINITE. This was a problem that is now resolved in 6.1.0. In 6.1.0, if you set only one of these fields (```` or ````) in the XML file, the other value defaults to 0. (If you set neither one of them, the default duration for that policy will be used.) A warning message will also be logged by the parser specifying the parent tag, the missing subfield, and the line number. This change is only a migration issue if you are using XML inheritance in your QoS XML file, expecting the missing value to be inherited from an ancestor. (Setting only one of two duration fields and relying on partial inheritance isn't best practice, however.) This issue also affects the Micro Application Generator (MAG). .. CORE-10075 .. _section-General-XML-610-MAG-136: Instance replacement changes affect XML files in Micro Application Generator (MAG) ---------------------------------------------------------------------------------- This issue only affects XML files used by Micro Application Generator (MAG) for use in |CONNEXT| *Micro*. The issue affects only MAG because the ```` tag was added in 6.0.1 for MAG, but it is new in 6.1.0 for the *Connext* Core Libraries. (See :link_connext_instancerep_whats_new_610:`Configure how instances will be replaced ..., in What's New in 6.1.0 <>`.) As a result of this new functionality in the Core Libraries, the type used by ```` in MAG has been changed from a single type to a complex type. Because of this change, XML files used by MAG in previous releases won't work out of the box in 6.1.0. For example, the following XML worked in 6.0.1 in MAG, but will not in 6.1.0: .. code-block:: xml OLDEST_INSTANCE_REPLACEMENT To work in 6.1.0, change the above XML to the following: .. code-block:: xml ANY_INSTANCE_REMOVAL ANY_INSTANCE_REMOVAL ANY_INSTANCE_REMOVAL .. MAG-136