![Abstract composition of orange triangles and scattered points on white background (no text or symbols)](.vortex-opensplice-idl-preprocessor-guide/bf65cf05b0132531bb5114f079af041f8713e86ca08bcb0cd018aad95c176585.jpg)

# VORTEX

# OPENSPLICE

# IDL PreProcessor Guide

# Release 6.x

# Contents

# 1 Preface 1

1.1 About the IDL PreProcessor Guide
1.2 Intended Audience
1.3 Organisation
1.4 Conventions

# 2 Overview 3

2.1 Introduction 3

# 3 Prerequisites 5

4 Command Line Options 6

5 OpenSplice Modes and Languages 9

6 IDL Pre-processor Grammar 10

# 7 Keys 15

7.1 Defining Keys 15
7.2 Bounded strings as character arrays 16

# 8 Modes, Languages and Processing steps 18

8.1 Integrated C++ ORB 18
8.2 C++ Standalone 20
8.3 ISOC++ 20
8.4 ISOC++2 20
8.5 C Standalone 20
8.6 C99 Standalone 22
8.7 Java Standalone 22
8.8 Integrated Java ORB 23

# 9 Extensible and Dynamic Topic Types for DDS annotation support 24

# 10 Built-in DDS data types 26

# 11 References 27

# 12 Contacts & Notices 28

12.1 Contacts 28
12.2 Notices 28

# 1

# Preface

# 1.1 About the IDL PreProcessor Guide

The IDL Pre-processor Guide describes what the Vortex OpenSplice IDL Pre-processor is, and how to use it. The Vortex OpenSplice IDL Pre-processor is included with the Vortex OpenSplice product.

# 1.2 Intended Audience

The IDL Pre-processor Guide is intended to be used by developers creating applications which use Vortex Open-Splice.

# 1.3 Organisation

The Overview gives a general description of and brief introduction to the IDL Pre-processor.

Prerequisites describes the prerequisites needed to run the pre-processor.

IDL Pre-processor Command Line Options gives detailed descriptions of the options that are available for running the pre-processor.

OpenSplice Modes and Languages provides a summary of OpenSplice’s supported modes and languages, as well as an overview of the applicable Vortex OpenSplice libraries.

IDL Pre-processor Grammar shows the IDL grammar that is supported by the Vortex OpenSplice IDL Preprocessor.

Keys describes the mechanism for the use of keys with particular data types.

Modes, Languages and Processing steps describes the steps required for creating programs for each of the modes and languages supported by the Pre-processor.

Extensible and Dynamic Topic Types for DDS annotation support describes how the IDL Pre-processor handles the annotation language extension.

Built-in DDS data types describes the built-in DDS data types and provides language-specific guidelines on how to use them.

Finally, there is a bibliography which lists all of the publications referred to in this Guide.

# 1.4 Conventions

The icons shown below are used in ADLINK product documentation to help readers to quickly identify information relevant to their specific use of Vortex OpenSplice.

<table><tr><td>Icon</td><td>Meaning</td></tr><tr><td>&lt;img src="images/2a05f87a4292bfecb242bff603249f384f86fc8d046326ed5c2af664e82a5224.jpg"/&gt;</td><td>Item of special significance or where caution needs to be taken.</td></tr><tr><td>&lt;img src="images/f556c722c44d0a0aff06b20a2327b066413bdabb9121675ea6a08409e03d1206.jpg"/&gt;</td><td>Item contains helpful hint or special information.</td></tr><tr><td>&lt;img src="images/43aaeb03f8eafa1f6f51af76e2acc2f3047e991cc92f9784b58d668ccb824d61.jpg"/&gt;</td><td>Information applies to Windows (e.g. XP, 2003, Windows 7) only.</td></tr><tr><td>&lt;img src="images/4268d3882b1803e09d6e1956c419d257d2943fd035178c07f2f2598430539c44.jpg"/&gt;</td><td>Information applies to Unix-based systems (e.g. Solaris) only.</td></tr><tr><td>&lt;img src="images/d93759ab4a141e50cccbed72d8b191f7931a602e5f07f510eff7781013ff83df.jpg"/&gt;</td><td>Information applies to Linux-based systems (e.g. Ubuntu) only.</td></tr><tr><td>&lt;img src="images/5839916d1050ec689ba078ad1319d3eb3f5f09669591c732bd40a5e0f38ddf2e.jpg"/&gt;</td><td>C language specific.</td></tr><tr><td>&lt;img src="images/c5109c5b262605546d22f12fa404c06efd87d0b64a830465b8fbe9e1320173c5.jpg"/&gt;</td><td>C++ language specific.</td></tr><tr><td>&lt;img src="images/972cbec6893032a2c89c55a64ab62acf9190061d124d133993dee475c02fd660.jpg"/&gt;</td><td>C# language specific.</td></tr><tr><td>&lt;img src="images/1e61074e9a472338dbbb31ffd08dbe2cd1bda5924b03ac5741887d113ba3618d.jpg"/&gt;</td><td>Java language specific.</td></tr></table>

# 2

# Overview

The Vortex OpenSplice IDL Pre-processor plays a role in generating code for DDS/DCPS specialized interfaces (TypeSupport, DataReader and DataWriter) from application data definitions defined in IDL for all supported languages.

# 2.1 Introduction

The Vortex OpenSplice IDL Pre-processor supports two modes:

• Standalone mode where the application is only used with Vortex OpenSplice
• ORB-integrated mode where the application is used with an ORB as well as with Vortex OpenSplice

In a standalone context, Vortex OpenSplice provides, apart from the DDS/DCPS related artifacts, all of the artifacts implied by the lDL language-specific mapping. In this case the name space used is DDS instead of the name space implied by the IDL language-specific mapping.

In an ORB-integrated context, the ORB pre-processor will provide for the artifacts implied by the lDL languagespecific mapping, while Vortex OpenSplice only provides the DDS/DCPS-related artifacts. The application data type representation provided by the ORB is also used within the Vortex OpenSplice context. In this way application data types can be shared between the ORB and Vortex OpenSplice within one application program.

The Vortex OpenSplice IDL Pre-processor accepts IDL which complies with the OMG CORBA specification to specify application data types. Additionally it allows specifying keys on data types.

A number of DDS data types defined in the DCPS API (for example, Time\_t) are available for use with application IDL data types and can be seen as OpenSplice DDS IDL Pre-processor “built-in” definitions.

The diagram OpenSplice IDL Pre-processor High Level Processes shows the Vortex OpenSplice IDL Preprocessor high-level processing.

The Vortex OpenSplice IDL Pre-processor scans and parses the IDL input file containing the application data type definitions.

For the selected language, the Vortex OpenSplice IDL Pre-processor generates the specialized interfaces for Type-Support, the DataReader and the DataWriter from specialized class template files which are provided by Open-Splice. Note that the Vortex OpenSplice IDL Pre-processor will only generate specialized interfaces for application data types for which a key list is defined. If it is not, the OpenSplice DDS IDL Pre-processor assumes that the data type will only be used enclosed in other data types.

The Vortex OpenSplice IDL Pre-processor also generates language-specific support functions, which are needed to allow the Vortex OpenSplice system to handle the application data types.

For the standalone context the Vortex OpenSplice IDL Pre-processor generates the language-specific application data types according the OMG IDL language mapping that is applicable for the specific target language.

# OpenSplice IDL Pre-processor High Level Processes

![Based on the provided image, here is the description of the flowchart blocks and connections:\n\n**Labeled Blocks:**\n*   Application IDL data types\n*   IDL scanner and parser\n*   Language specific specialized class templates\n*   Language specific typed Foo classes generator\n*   Application Foo classes\n*   Language specific support functions generator\n*   Application language specific support functions\n*   Language specific data type generator\n*   Application language specific data types\n\n**Connections:**\n*   An arrow points from 'Application IDL data types' to 'IDL scanner and parser'.\n*   A vertical line connects 'IDL scanner and parser' down to 'Language specific typed Foo classes generator'.\n*   An arrow points from 'Language specific specialized class templates' to 'Language specific typed Foo classes generator'.\n*   An arrow points from 'Language specific typed Foo classes generator' to 'Application Foo classes'.\n*   A vertical line connects 'Language specific typed Foo classes generator' down to 'Language specific support functions generator'.\n*   An arrow points from 'Language specific support functions generator' to 'Application language specific support functions'.\n*   A vertical line connects 'Language specific support functions generator' down to 'Language specific data type generator'.\n*   An arrow points from 'Language specific data type generator' to 'Application language specific data types'.](.vortex-opensplice-idl-preprocessor-guide/940f916c12855bd09ed7f6029bc98fa27e5abd89394cf7f38626a0b44a98625a.jpg)

# 3

# Prerequisites

# Unix

The Vortex OpenSplice environment must be set correctly for UNIX-based platforms before the Vortex OpenSplice IDL Pre-processor can be used.

Run release.com from a shell command line to set the environment.

release.com is located in the root directory of the Vortex OpenSplice installation (&lt;OSPL\_HOME&gt;):

```batch
% . &lt;OSPL_HOME&gt;/release.com
```

The Vortex OpenSplice IDL Pre-processor, idlpp, can be invoked by running it from a command shell:

```txt
% idlpp
```

The idlpp command line options are fully described in IDL Pre-processor Command Line Options.

# 4

# Command Line Options

The Vortex OpenSplice IDL Pre-processor, idlpp, can be run with the following command line options:

```txt
[ -h ]
[ -b &lt;ORB-template-path&gt; ]
[ -n &lt;include-suffix&gt; ]
[ -I &lt;path&gt; ]
[ -D &lt;macro&gt;[=&lt;definition&gt;] ]
&lt; -S | -C &gt;
&lt; -l (c | c++ | cpp | java | cs | isocpp | isoc++ | c99 | simulink) &gt;
[ -F ]
[ -j [old]:&lt;new&gt; ]
[ -o &lt;dds-types&gt; | &lt;custom-psm&gt; | &lt;no-equality&gt; | &lt;deprecated-c++11-mapping&gt; ]
[ -d &lt;output-directory&gt; ]
[ -P &lt;dll_macro_name&gt;[,&lt;header_file&gt;] ]
[ -N ]
&lt;filename&gt;
```

• Options shown between angle brackets, &lt; and &gt;, are mandatory.
• Options shown between square brackets, [ and ], are optional.

All of these options are described in full detail below.

-h List the command line options and information.

-b &lt;ORB-template-path&gt; Specifies the ORB-specific path within the template path for the specialized class templates (in case the template files are ORB specific). The ORB-specific template path can also be set via the environment variable OSPL\_ORB\_PATH, the command line option is however leading. To complete the path to the templates, the value of the environment variable OSPL\_TMPL\_PATH is prepended to the ORB path.

-n &lt;include-suffix&gt; Overrides the suffix that is used to identify the ORB-dependent header file (specifying the data model) that needs to be included. Normally the name of this include file is derived from the IDL file name and followed by an ORB-dependent suffix (e.g. C.h for ACE-TAO based ORBs). This option is only supported in CORBA cohabitation mode for C++; in all other cases it is simply ignored. Example usage: -n .stub.hpp (For a file named foo.idl this will include foo.stub.hpp instead of fooC.h, which is the default expectation for ACE-TAO.)

-I &lt;path&gt; Passes the include path directives to the C pre-processor.

-D &lt;macro&gt; Passes the specified macro definition to the C pre-processor.

-S Specifies standalone mode, which allows application programs to be built and run without involvement of any ORB. The name space for standard types will be DDS instead of the name space implied by the IDL language mapping. types will be DDS instead of the name space implied by the IDL language mapping.

-C Specifies ORB integrated mode, which allows application programs to be built and run integrated with an ORB.

-l (c | c++ | cpp | java | cs | isocpp | isoc++ | isocpp2 | isoc++2 | c99 | simulink) Selects the target language. Note that the Vortex OpenSplice IDL Pre-processor does not support every combination of modes and languages. This option is mandatory; when no language is selected the OpenSplice IDL Pre-processor reports an error.

• For the c, c++, cpp, java and cs target languages the types will default to the standard types. For the isocpp and isoc++ target languages the types will default to the ISOC++ types that comply with the ISO/IEC C++ 2003 Language DDS PSM. When using isocpp, isoc++ isocpp2 or isoc++2 an equality operator will also be generated for types unless this feature is explicitly disabled.
• Please note that isocpp and isoc++ target languages are DEPRECATED since V6.6.0. Please use isocpp2 or isoc++2 instead.
• For the Standalone mode in C (when using the -S flag and the c language option), OSPL\_ORB\_PATH will by default be set to value SAC, which is the default location for the standalone C specialized class template files.
• For the CORBA cohabitation mode in C++ (when using the -C flag and the c++ or cpp language option) the OSPL\_ORB\_PATH will, by default, be set to:

# Unix

CCPP/DDS\_OpenFusion\_1\_6\_1 for Unix-based platforms.

# Windows

CCPP\DDS\_OpenFusion\_1\_6\_1 for Windows platforms.

These are the default locations for the IDL to C++ specialized class template files of the OpenSplice-Tao ORB. Class templates for other ORBS are also available in separate sub-directories of the CCPP directory, but for more information about using a different ORB, consult the README file in the custom\_lib/ccpp directory.

• For the Standalone mode in C++ (when using the -S flag and the c++ or cpp language option), OSPL\_ORB\_PATH will by default be set to value SACPP, which is the default location for the standalone C++ specialized class template files.

# Java

• For the Standalone mode in Java (when using the -S flag and the java language option), OSPL\_ORB\_PATH will by default be set to the value of SAJ, which is the default location for the standalone Java specialized class template files.
• For the CORBA cohabitation mode in Java (when using the -C flag and the java language option), OSPL\_ORB\_PATH will by default be set to the value of SAJ, which is the default location for the CORBA Java specialized class template files. This means that the CORBA cohabitated Java API and StandAlone Java API share the same template files.

# c#

• For the Standalone mode in C# (when using the -S flag and the cs language option), OSPL\_ORB\_PATH will by default be set to the value of SACS, which is the default location for the standalone CSharp specialized class template files.

# |c99|

• For the c99 target language the types will default to the standard types. Except that the primitive types are mapped to the corresponding c99 types and that bound strings are mapped to char arrays with a size one larger than specified in the idl definition to allow for the terminating 0 character.

# |simulink|

• For Simulink a MATLAB .m file is created representing the simulink bus for the input IDL file. Typically this option is used when invoking a script from MATLAB to import the IDL into Simulink.

See also OpenSplice Modes and Languages for a complete list of supported modes and languages.

-F Specifies FACE mode, generate FACE API type specific functions in addition to the target language specific ones. Only applicable for the java and isocpp2 target languages.

# Java

-j [old]:&lt;new&gt; Specifies that the (partial) package name which matches [old] will be replaced by the package name which matches &lt;new&gt; (the package &lt;new&gt; is substituted for the package [old]). If [old] is not included then the package name defined by &lt;new&gt; is prefixed to all Java packages. The package names may only be separated by . (period) characters. A trailing . character is not required, but may be used. Example: -j :org.opensplice (prefixes all Java packages). Example: -j com.opensplice.:org.opensplice. (substitutes). Only applicable for the Java language.

-o dds-types Enables the built-in DDS data types. In the default mode, the built-in DDS data types are not available to the application IDL definitions. When this option is activated, the built-in DDS data types will become available. Refer to Section 1.9, Built-in DDS data types, on page 28.
-o custom-psm Enables support for alternative IDL language mappings. Currently CSharp offers an alternative language mapping where IDL names are translated to their PascalCase representation and where @ instead of \_ is used to escape reserved C#-keywords.
-o no-equality Disables support for the automatically-generated equality operator on ISOC++ types.
-o deprecated-c++11-mapping Generates the ISOC++2 types using the deprecated C++11 mapping implementation as used in the past by the also deprecated isocpp/isoc++ PSM. This option only makes sense when migrating from isocpp/isoc++ to isocpp2/isoc++2.
-d &lt;output-directory&gt; Specifies the output directory for the generated code.
-P &lt;dll\_macro\_name&gt;[,&lt;header\_file&gt;] This option controls the signature for every external function/class interface. If you want to use the generated code for creating a DLL, then interfaces that need to be accessible from the outside need to be exported. When accessing these operations outside of the DLL, then these external interfaces need to be imported. If the generated code is statically linked, this option can be omitted. The first argument &lt;dll\_macro\_name&gt; specifies the text that is prepended to the signature of every external function and/or class. For example: defining DDS\_API as the macro, the user can define this macro as \_\_declspec(dllexport) when building the DLL containing the generated code, and define the macro as \_\_declspec(dllimport) when using the DLL containing the generated code.

Addtionally a header file can be specified, which contains controls to define the macro. For example the external interface of the generated code is exported when the macro BUILD\_MY\_DLL is defined, then this file could look like:

```c
#ifdef BUILD_MY_DLL
#define DDS_API __declspec(dllexport)
#else /* !BUILD_MY_DLL */
#define DDS_API __declspec(dllexport)
#endif /* BUILD_MY_DLL */
```

# C++

-N This option disables type caching in the copy-in routines. The copy-in routines cache the type to improve the performance of copying sequences. This option disables this feature to allow the use of sequences within multi-domain applications. Only applicable for the C and C++ languages.

&lt;filename&gt; Specifies the IDL input file to process.

# 5

# OpenSplice Modes and Languages

The Vortex OpenSplice IDL Pre-processor supports two modes:

• Standalone mode where the application is only used with Vortex OpenSplice
• ORB-integrated mode where the application is used with an ORB as well as with Vortex OpenSplice

In a standalone context, Vortex OpenSplice provides, apart from the DDS/DCPS related artifacts, all the artifacts implied by the lDL language specific mapping. In this case the used name space is DDS instead of the name space implied by the IDL language specific mapping.

In an ORB-integrated context, the ORB pre-processor will provide for the artifacts implied by the lDL language specific mapping, while Vortex OpenSplice only provides the DDS/DCPS related artifacts. The application data type representation provided by the ORB is also used within the Vortex OpenSplice context. In this way application data types can be shared between the ORB and Vortex OpenSplice within one application program.

The languages and modes that Vortex OpenSplice supports are listed in the table below.

Supported Modes and Languages

<table><tr><td>Language</td><td>Mode</td><td>OpenSplice Library</td><td>ORB Template Path</td></tr><tr><td>C</td><td>Standalone</td><td>dcpssac.sodcpsac.lib</td><td>SAC</td></tr><tr><td>C++</td><td>ORB Integrated</td><td>dcpsccpp.so</td><td>CCPP/DDS_OpenFusion_1_4_1for UNIX-like platforms, andCCPP\DDS_OpenFusion_1_5_1for the Windows platform</td></tr><tr><td>C++</td><td>Standalone</td><td>dcpssacpp.so</td><td>SACPP</td></tr><tr><td>ISOC++</td><td>ISOCPP Types</td><td>dcpsisocpp.so</td><td>ISOCPP</td></tr><tr><td>ISOC++</td><td>ORB Integrated</td><td>dcpsisocpp.so</td><td>CCPP/DDS_OpenFusion_1_4_1for UNIX-like platforms, andCCPP\DDS_OpenFusion_1_5_1for the Windows platform</td></tr><tr><td>ISOC++2</td><td>ISOCPP Types</td><td>dcpsisocpp2.so</td><td>ISOCPP2</td></tr><tr><td>Java</td><td>Standalone</td><td>dcpssaj.jar</td><td>SAJ</td></tr><tr><td>Java</td><td>ORB integrated</td><td>dcpscj.jar</td><td>SAJ</td></tr><tr><td>C#</td><td>Standalone</td><td>dcpssacsAssembly.dll</td><td>SACS</td></tr><tr><td>C99</td><td>Standalone</td><td>dcpsc99.sodcpsc99.lib</td><td>C99</td></tr></table>

The mappings for each language are in accordance with their respective OMG Language Mapping Specifications (see the Bibliography for a list of references).

# IDL Pre-processor Grammar

The Vortex OpenSplice IDL Pre-processor accepts the grammar which complies with the CORBA Specification. The Vortex OpenSplice IDL Pre-processor accepts the complete grammar, but it will ignore elements not relevant to the definition of data types.

In the following specification of the grammar (similar to EBNF), elements that are processed by the Vortex Open-Splice IDL Pre-processor are highlighted in bold. Note that Vortex OpenSplice does not support all base types that are specified by the OMG.

The idlpp also takes into account all C pre-processor directives that are common to ANSI-C, like #include, #define, #ifdef, etc..

The OMG’s IDL Grammar

<table><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td></td><td></td></tr></table>

Table 6.1 – continued from previous page

<table><tr><td></td><td>::=</td><td>“;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | &quot;;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” |“;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;” | “;”</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td>::=</td><td>“:” { ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ ”,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* * }*</td><td>{ “,” }* ] [ “supports” { ”,” }* ]</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td>::=</td><td colspan="101">(“value Forward Dcl&gt; | value Abs Dcl&gt; | value Box Dcl&gt; | value Forward Dcl&gt; )</td></tr><tr><td></td><td>::=</td><td colspan="100">[ “abstract” ] “valuetype”</td><td></td></tr><tr><td></td><td>::=</td><td colspan="97">“valuetype”</td><td></td><td></td><td></td><td></td></tr><tr><td></td><td></td><td>“abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “abstract” “valuetype” [ [ “inf param Decls&gt; ] ”)” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ””[ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [[ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [“inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “ inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “inf param decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparamdecls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam decls&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&gt; ] ”” [ [ “infparam declc&lt;sup&gt;+&lt;/sup&gt; 10000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000150000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000125000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000012250000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001225000001225000012250001225000122500122500122500122500122500122500122500122500122500122500122500122500122501225012250122501225012250122501225012250122501225012250122501225012250122501225012250122501225012225122501225012250122501225012250122501225012250122501225012250122501225012250122501225012250122501225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122251225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512253122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122491225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251226122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122712251225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512281225122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251229122512251225122512251225122512251225122512251225122512251225122512251225122512251225122512251229122912291229122912291229122912291229122912291229122912291229122912291229122912291229122912291229122812291229122912291229122912291229122912291229122912291229122912291229122912291229122912291229122912271229122912291229122912291229122912291229122912291229122912291229122912291229122912291229122912291226123123123123123123123123123123123123123123123123123123123123123123123123123123123123123123123123123123 13333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333 1333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14 14</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr><tr><td></td><td>::=</td><td>| “state member” | (“public” | “private” | (“custom”) | (“product” | (“custom”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“product”) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function） | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function) | (“function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) |“function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) |“(function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | (“function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function) | “function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function) | &quot;function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function) | &quot;function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function) |“function)( | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | “function) | &quot;function)( | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function） | “function）
|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| :---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---</td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td><td></td></tr></table>

Table 6.1 – continued from previous page

<table><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td></td><td></td></tr></table>

Table 6.1 – continued from previous page

<table><tr><td></td><td>::=</td><td>“oneway”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>“(”{,”* ”)”| “(” ”)”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>“in” | “out” | “inout”</td></tr><tr><td></td><td>::=</td><td>“raises” “(”{,”* ”)”</td></tr><tr><td></td><td>::=</td><td>“context” “(”{,”* ”)”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>| |</td></tr><tr><td></td><td>::=</td><td>“fixed” “&lt;””,”</td></tr><tr><td></td><td>::=</td><td>“fixed”</td></tr><tr><td></td><td>::=</td><td>“ValueBase”</td></tr><tr><td></td><td>::=</td><td>“struct” | “union”</td></tr><tr><td></td><td>::=</td><td>“import””,”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>|</td></tr><tr><td></td><td>::=</td><td>“typeid”</td></tr><tr><td></td><td>::=</td><td>“typeprefix”</td></tr><tr><td></td><td>::=</td><td>“readonly” “attribute”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>| { ”,”} *</td></tr><tr><td></td><td>::=</td><td>“attribute”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>[ ] |</td></tr><tr><td></td><td>::=</td><td>“getraises”</td></tr><tr><td></td><td>::=</td><td>“setraises”</td></tr><tr><td></td><td>::=</td><td>“(”{ ”,”} * ”)”</td></tr><tr><td></td><td>::=</td><td>|</td></tr><tr><td></td><td>::=</td><td>“{”</td></tr><tr><td></td><td>::=</td><td>[ ] [</td></tr><tr><td></td><td>::=</td><td>“supports”{ ”,”} *</td></tr><tr><td></td><td>::=</td><td>“:”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>“uses” [ “multiple” ] &lt;interface_type&gt;</td></tr><tr><td></td><td>::=</td><td>“emits”</td></tr><tr><td></td><td>::=</td><td>“publishes”</td></tr><tr><td></td><td>::=</td><td>“consumes”</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>[ ] “manages”[</td></tr><tr><td></td><td>::=</td><td></td></tr><tr><td></td><td>::=</td><td>“:”</td></tr><tr><td></td><td>::=</td><td>“primary_key_spec”</td></tr><tr><td></td><td>::=</td><td>“primarykey”</td></tr><tr><td></td><td>::=</td><td>“{”* ””</td></tr><tr><td></td><td>::=</td><td>| ;” | ;”</td></tr><tr><td></td><td>::=</td><td>“(” [ ] ”” [</td></tr><tr><td colspan="3">Continued on next page</td></tr></table>

Table 6.1 – continued from previous page

<table><tr><td></td><td>::=</td><td>“finder”&lt;identifier&gt;“(”[,,)”[]</td></tr><tr><td></td><td>::=</td><td>(||)</td></tr><tr><td></td><td>::=</td><td>[ “abstract” ] “eventType”</td></tr><tr><td></td><td>::=</td><td>“abstract” “eventType”[,”*“}”</td></tr><tr><td></td><td>::=</td><td>“{”*“}”</td></tr><tr><td></td><td>::=</td><td>[ “custom” ] “eventType”[]</td></tr><tr><td></td><td>::=</td><td>Arbitrarily long sequence of ASCII alphabetic, numeric and underscore characters. The first character must be ASCII alphabetic. All characters are significant. An identifier may be escaped with a prepended underscore character to prevent collisions with new IDL keywords. The underscore does not appear in the generated output.</td></tr></table>

# 7

# Keys

# 7.1 Defining Keys

The Vortex OpenSplice IDL Pre-processor also provides a mechanism to define a list of keys (space- or commaseparated) with a specific data type. The syntax for that definition is:

```txt
#pragma keylist &lt;data-type-name&gt; &lt;key&gt;*
```

The identifier &lt;data-type-name&gt; is the identification of a struct or a union definition.

The identifier &lt;key&gt; is the member of a struct. For a struct either no key list is defined, in which case no specialized interfaces (TypeSupport, DataReader and DataWriter) are generated for the struct, or a key list with or without keys is defined, in which case the specialized interfaces are generated for the struct. For a union either no key list is defined, in which case no specialized interfaces are generated for the union, or a key list without keys is defined, in which case the specialized interfaces are generated for the union. It is not possible to define keys for a union because a union case may only be addressed when the discriminant is set accordingly, nor is it possible to address the discriminant of a union. The keylist must be defined in the same name scope or module as the referred struct or union.

# 7.1.1 Supported types for keys

Vortex OpenSplice supports following types as keys:

• short
• long
• long long
• unsigned short
• unsigned long
• unsigned long long
• float
• double
• char
• boolean
• octet
• string
• bounded string
• enum
• char array (provided that #pragma cats is specified; see Character arrays as Keys below)

Vortex OpenSplice also supports typedef for these types.

# 7.1.2 Character arrays as Keys

By default Vortex OpenSplice does not support using a character array as a key. Using an (character) array as a key field is not desirable or supported, because:

1. Every index in the array must be considered a separate key in this situation. This is the only way that arrays can be compared to each other in a correct manner. An array of ten characters would have to be treated as a ten-dimensional storage structure, leading to poor performance compared with the processing of a (bounded) string of ten characters.
2. An array always has a fixed length and therefore the whole array is sent over the wire even if only a small part of it is needed. When using a (bounded) string, only the actual string is sent and not the maximum length.

However, in certain scenarios a character array is the logical key for a topic, either from an information modeling perspective or simply due to a legacy data model. To facilitate such scenarios Vortex OpenSplice introduces the following pragma which allows for character arrays to be used as a key.

```txt
#pragma cats &lt;data-type-name&gt; &lt;char-array-field-name&gt;*
```

The identifier &lt;data-type-name&gt; is the identification of a struct definition. The identifier &lt;char-array-field-name&gt; is the member of a struct with the type character array. The cats pragma must be defined in the same name scope or module as the referred struct.

This pragma ensures that each character array listed for the specified struct definition is treated as a string type internally within Vortex OpenSplice and operates exactly like a regular string. This allows the character array to be used as a key for the data type, because as far as Vortex OpenSplice is concerned the character array is in fact a string. On the API level (e.g., generated code) the character array is maintained so that applications will be able to use the field as a regular character array as normal. Be aware that listing a character array here does not promote the character array to a key of the data type; the regular keylist pragma must still be used for that. In effect this pragma can be used to let any character array be treated as a string internally, although that is not by definition desirable.

When a character array is mapped to a string internally by using the cats pragma, the product behaves as follows:

1. If the character array does not have a ‘0’ terminator, the middleware will add a \0 terminator internally and then remove it again in the character array that is presented to a subscribing application. In other words, a character array used in combination with the cats pragma does not need to define a \0 terminator as one of its elements.
2. If the character array does have a \0 terminator, the middleware will only process the characters up to the first element containing the \0 character; all other characters are ignored. The middleware will present the character array with the same \0 terminator to a subscribing application and any array elements following that \0 terminator will contain \0 terminators as well; i.e., any array elements following a \0 element are ignored.

The following table shows some examples using the cats pragma for a character array with a size of 4.

<table><tr><td>Character array written(by publishing application)</td><td>Internal string representation(Internal OpenSplice data)</td><td>Character array read(By subscribing application)</td></tr><tr><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;c&#x27;,&#x27;d&#x27;]</td><td>&quot;abcd&quot;</td><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;c&#x27;,&#x27;d&#x27;]</td></tr><tr><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;c&#x27;,&#x27;\0&#x27;]</td><td>&quot;abc&quot;</td><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;c&#x27;,&#x27;\0&#x27;]</td></tr><tr><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;\0&#x27;,&#x27;d&#x27;]</td><td>&quot;ab&quot;</td><td>[&#x27;a&#x27;,&#x27;b&#x27;,&#x27;\0&#x27;,&#x27;\0&#x27;]</td></tr></table>

# 7.2 Bounded strings as character arrays

In some use cases a large number of (relatively small) strings may be used in the data model, and because each string is a reference type, it means that it is not stored inline in the data model but instead as a pointer. This will result in separate allocations for each string (and thus a performance penalty when writing data) and a slight increase in memory usage due to pointers and (memory storage) headers for each string.

# 7.2. Bounded strings as character arrays

The Vortex OpenSplice IDL Pre-Processor features a special pragma called stac which can be utilized in such use cases. This pragma enables you to indicate that Vortex OpenSplice should store strings internally as character arrays (but on the API level they are still bounded strings). Because a character array has a fixed size, the pragma stac only affects bounded strings. By storing the strings internally as a character array the number of allocations is reduced and less memory is used. This is most effective in a scenario where a typical string has a relatively small size, i.e. fewer than 100 characters.

![A red triangular warning sign with a white interior displaying a black exclamation point in the center.](.vortex-opensplice-idl-preprocessor-guide/d403d75f8483ecd501b6fd6320c0a8730d256d15d6d5fabe852649dba4042e3e.jpg)

Using the pragma stac on bounded strings results in the limitation that those strings can no longer be utilized in queries. It also results in the maximum size of the bounded string to be used each time, therefore the pragma stac is less suitable when the string has a large bound and does not always use up the maximum space when filled with data. A bounded string that is also mentioned in the pragma keylist can not be listed for pragma stac, as transforming those strings to an array would violate the rule that an array can not be a keyfield.

```markdown
#pragma stac &lt;data-type-name&gt; [[!]bounded-string-fieldname]\*
```

The identifier &lt;data-type-name&gt; is the identification of a struct definition. The identifier [[!]bounded-stringfield-name] is the member of a struct with the type bounded string. The stac pragma must be defined in the same name scope or module as the referred struct. If no field names are listed, then all bounded strings will be treated as character arrays internally. If only a subset of the struct members is targeted for transformation then these members can be listed explicitly one by one. Preceeding a field name with a ! character indicates that the listed member should not be considered for transformation from bounded string to character array.

![This is an image of a standard triangular warning sign. It features a thick red border surrounding a white background. In the center is a large black exclamation point.](.vortex-opensplice-idl-preprocessor-guide/4dda80bdbd335bf53d8d29ec0e85ea86d4077f6b094aa93a53b224c6c0b6f1ec.jpg)

Member names with and without the ! character may not be mixed within a stac pragma for a specific struct as this has no relevant meaning. This pragma ensures that each bounded string listed for the specified struct definition is treated as a character array type internally within Vortex OpenSplice and operates exactly like a regular bounded string. On the API level ( i.e. , generated code) the bounded string is maintained so that applications will be able to use the field as a regular bounded string.

# 8

# Modes, Languages and Processing steps

# 8.1 Integrated C++ ORB

The generic diagram for the ORB integrated C++ context is shown in the diagram Integrated C++ ORB.

The Vortex OpenSplice IDL Pre-processor generates IDL code for the specialized TypeSupport, DataReader and DataWriter, as well as C++ implementations and support code. The ORB pre-processor generates from the generated IDL interfaces the C++ specialized interfaces for that specific ORB. These interfaces are included by the application C++ code as well as the Vortex OpenSplice generated specialized C++ implementation code. The application C++ code as well as the specialized C++ implementation code (with the support functions) is compiled into object code and linked together with the applicable Vortex OpenSplice libraries and the ORB libraries.

![This image displays a square icon with a teal background. Centered within it is a white lowercase letter 'i' in a serif font.](.vortex-opensplice-idl-preprocessor-guide/58f1e6aef7df70b9104ebba1f33d201a326f4641e6d967f855171bab00398fa6.jpg)

Vortex OpenSplice libraries are provided for linking with OpenFusion TAO. However the source code of the C++ API is also available to build against your own ORB and/or compiler version.

Integrated C++ ORB

![Here is an accurate description of the flowchart, listing the labeled blocks and their connections:\n\n**IDL Pre-processing Phase**\n*   **Application IDL data types** connects to **OpenSplice IDL pre-processor**.\n*   **OpenSplice IDL pre-processor** connects to **OpenSplice generated Foo interfaces (IDL)** and **ORB pre-processor**.\n*   **OpenSplice interface (IDL)** connects to **OpenSplice generated Foo interfaces (IDL)** via an arrow labeled 'include'.\n*   **OpenSplice generated Foo interfaces (IDL)** connects to **ORB pre-processor**.\n\n**Code Generation Phase**\n*   **ORB pre-processor** connects to **ORB generated Application datatypes and Foo C++ interfaces**.\n*   **ORB generated Application datatypes and Foo C++ interfaces** connects to **OpenSplice Foo C++ implementation code and support functions** via an arrow labeled 'include'.\n*   **OpenSplice generated Foo interfaces (IDL)** connects to **OpenSplice Foo C++ implementation code and support functions**.\n*   **OpenSplice Foo C++ implementation code and support functions** connects to **Application C++ code** via an arrow labeled 'include'.\n\n**Compilation Phase**\n*   **Application C++ code** connects to **C++ compiler** (left block).\n*   **OpenSplice Foo C++ implementation code and support functions** connects to **C++ compiler** (right block).\n*   The left **C++ compiler** connects to **Application object code**.\n*   The right **C++ compiler** connects to **OpenSplice Foo implementation and support functions object code**.\n\n**Linking Phase**\n*   **Application object code** connects to **linker**.\n*   **OpenSplice Foo implementation and support functions object code** connects to **linker**.\n*   **OpenSplice libraries** connects to **linker**.\n*   **ORB libraries** connects to **linker**.\n*   **linker** connects to **Application executable**.](.vortex-opensplice-idl-preprocessor-guide/d3d0762062e85efd65f9503d4bed2243e789dcb434276103515ccc7017e8a741.jpg)

The role of the Vortex OpenSplice IDL Pre-processor functionality is expanded in Integrated C++ ORB Vortex OpenSplice IDL Pre-processor Details. It shows in more detail which files are generated, given an input file (in this example foo.idl).

Integrated C++ ORB Vortex OpenSplice IDL Pre-processor Details
![The flowchart depicts a processing workflow involving the following labeled blocks and connections:\n\n**Blocks:**\n*   Application IDL data types (foo.idl)\n*   OpenSplice IDL pre-processor\n*   foo.h\n*   fooDcps.idl\n*   fooDcps_impl.h\n*   fooDcps_impl.cpp\n*   fooSplDcps.h\n*   fooSplDcps.cpp\n\n**Connections:**\n*   An arrow connects 'Application IDL data types (foo.idl)' to 'OpenSplice IDL pre-processor'.\n*   Four arrows originate from 'OpenSplice IDL pre-processor' pointing to:\n    *   'foo.h'\n    *   'fooDcps.idl'\n    *   'fooDcps_impl.h'\n    *   'fooSplDcps.h'\n*   The block 'fooDcps_impl.cpp' is positioned directly below 'fooDcps_impl.h'.\n*   The block 'fooSplDcps.cpp' is positioned directly below 'fooSplDcps.h'.](.vortex-opensplice-idl-preprocessor-guide/ed5106c39b6e45e2c4fd589822f2aca7f8381492445ec2b258c9c6bb579d23c6.jpg)

The file foo.h is the only file that needs to be included by the application. It includes all files needed by the application to interact with the DCPS interface.

The file fooDcps.idl is an IDL definition of the specialized TypeSupport, DataReader and DataWriter interfaces, which will be used to generate ORB-specific C++ interface files.

The fooDcps\_impl.\* files contain the specialized TypeSupport, DataReader and DataWriter implementation classes needed to communicate the type via Vortex OpenSplice.

The fooSplDcps.\* files contain support functions required by Vortex OpenSplice in order to be able to handle the specific data types.

# 8.2 C++ Standalone

The C++ standalone mode provides a Vortex OpenSplice context which does not need an ORB. Vortex Open-Splice resolves all implied IDL-to-C++ language mapping functions and requirements.

The only difference when using the standalone mode is that DDS is used as the naming scope for definitions and functions instead of the CORBA naming scope (the CORBA namespace is still supported, however, for compatibility purposes).

The diagram C Standalone is an overview of the artifacts and processing stages related to the C standalone context. For C++ the different stages are equal to the C standalone context. Because there is no ORB involved, all preprocessing is performed by the Vortex OpenSplice IDL Pre-processor. The generated specialized implementations and the application’s C++ code must be compiled into object code, plus all objects must be linked with the appropriate Vortex OpenSplice libraries.

# 8.3 ISOC++

The ISOC++ mode provides a Vortex OpenSplice context which does not need an ORB. Vortex OpenSplice resolves all implied IDL-to-C++ language mapping functions and requirements. Much like C++ standalone mode, the CORBA naming scope is not used but C99 types are used in place of DDS:: types, as specified in the ISO/IEC C++ language mapping specification.

# 8.4 ISOC++2

The ISOC++2 mode provides a Vortex OpenSplice context which does not need an ORB. Vortex OpenSplice resolves all implied IDL-to-C++ language mapping functions and requirements. Much like C++ standalone mode, the CORBA naming scope is not used but C99 types are used in place of DDS:: types, as specified in the ISO/IEC C++ language mapping specification.

# 8.5 C Standalone

The C standalone mode provides an Vortex OpenSplice context which does not need an ORB. Vortex OpenSplice resolves all implied IDL to C language mapping functions and requirements. The only difference when using the standalone mode is that DDS is used as the naming scope for definitions and functions.

The diagram C Standalone shows an overview of the artifacts and processing stages related to the C standalone context. Because there is no ORB involved, all the pre-processing is done by the Vortex OpenSplice IDL Preprocessor. The generated specialized class implementations and the application’s C code must be compiled into object code, plus all objects must be linked with the appropriate Vortex OpenSplice libraries.

C Standalone

![**Labeled Blocks:**\n*   A pplication IDL data types\n*   OpenSplice IDL pre-processor\n*   C application data types\n*   Foo classes and support functions\n*   A pplication C code\n*   C compiler\n*   C compiler\n*   A pplication object code\n*   Foo classes and support functions object code\n*   OpenSplice libraries\n*   linker\n*   A pplication executable\n\n**Connections:**\n*   A pplication IDL data types connects to OpenSplice IDL pre-processor\n*   OpenSplice IDL pre-processor connects to C application data types\n*   OpenSplice IDL pre-processor connects to Foo classes and support functions\n*   C application data types connects to A pplication C code (labeled 'include')\n*   C application data types connects to Foo classes and support functions (labeled 'include')\n*   A pplication C code connects to C compiler\n*   C compiler connects to A pplication object code\n*   Foo classes and support functions connects to C compiler\n*   C compiler connects to Foo classes and support functions object code\n*   A pplication object code connects to linker\n*   Foo classes and support functions object code connects to linker\n*   OpenSplice libraries connects to linker\n*   linker connects to A pplication executable](.vortex-opensplice-idl-preprocessor-guide/e785dcebf8ed2c102b274d8e3065fc2583aa3a254b2659756707420e3bb14862.jpg)

The role of the Vortex OpenSplice IDL Pre-processor functionality is expanded in the diagram C Standalone Vortex OpenSplice IDL Pre-processor Details, providing more detail about the files generated when provided with an input file (foo.idl this example).

C Standalone Vortex OpenSplice IDL Pre-processor Details
![This flowchart depicts a processing pipeline with one input block, one central processing block, and three output groups.\n\n**Blocks:**\n*   **Top Left:** A green rectangular box labeled 'Application IDL data types (foo.idl)'.\n*   **Top Right:** A green rectangular box with a double border labeled 'OpenSplice IDL pre-processor'.\n*   **Bottom Left Group:** Two stacked green boxes. The top box is labeled 'foo.h' and the bottom box is labeled 'fooDcps.h'.\n*   **Bottom Middle Group:** Two stacked green boxes. The top box is labeled 'fooSacDcps.h' and the bottom box is labeled 'fooSacDcps.c'.\n*   **Bottom Right Group:** Two stacked green boxes. The top box is labeled 'fooSplDcps.h' and the bottom box is labeled 'fooSplDcps.c'.\n\n**Connections:**\n*   An arrow points from 'Application IDL data types (foo.idl)' to 'OpenSplice IDL pre-processor'.\n*   A single line originates from the bottom of 'OpenSplice IDL pre-processor' and splits into three arrows pointing downwards:\n    *   One arrow points to the top box of the left group ('foo.h').\n    *   One arrow points to the top box of the middle group ('fooSacDcps.h').\n    *   One arrow points to the top box of the right group ('fooSplDcps.h').](.vortex-opensplice-idl-preprocessor-guide/99d41bca9aeaca25b7c71c4985702063bea761fc76634aa03cc63e2743f8da8b.jpg)

The file foo.h is the only file that needs to be included by the application. It itself includes all necessary files needed by the application in order to interact with the DCPS interface.

The file fooDcps.h contains all definitions related to the IDL input file in accordance with the OMG’s IDL-to-C language mapping specification.

The fooSacDcps.\* files contain the specialized TypeSupport, DataReader and DataWriter classes needed to communicate the type via Vortex OpenSplice.

The fooSplDcps.\* files contain support functions required by Vortex OpenSplice in order to be able to handle the specific data types.

# 8.6 C99 Standalone

The C99 standalone mode is simular to the C standalone mode. The difference is that the C99 standalone mode is used to support the C99 version of the C programming language. Except for some small changes in the generated artifacts this mode operates the equal to the C standalone mode. See for a description of the processing stages the description in section C Standalone.

The difference with the C standalone mode is that the primitive types are mapped to the corresponding C99 types. Further bounded strings are mapped to char array’s with a upperboundone larger than specified in the idl to allow for the terminating 0 character.

Further an additional file fooDcps.c is generated which contains the information to register the type information with Vortex OpenSplice.

# 8.7 Java Standalone

The Java standalone mode provides a Vortex OpenSplice context without the need of an ORB, which still enables portability of application code because all IDL Java language mapping implied functions and requirements are resolved by Vortex OpenSplice.

The diagram Java Standalone shows an overview of the artifacts and processing stages related to the Java standalone context. The Vortex OpenSplice IDL Pre-processor generates the application data classes from IDL according the language mapping. The Vortex OpenSplice IDL Pre-processor additionally generates classes for the specialized TypeSupport, DataReader and DataWriter interfaces. All generated code must be compiled with the Java compiler as well as the application Java code.

![**Labeled Blocks:**\n*   Java Standalone (Title)\n*   Application IDL data types\n*   OpenSplice IDL pre-processor\n*   Application Java code\n*   Java application data classes\n*   Foo classes\n*   Java compiler\n*   Application intermediate code\n*   Java application data intermediate code\n*   Foo classes intermediate code\n*   OpenSplice libraries\n*   Java Virtual Machine\n*   Application process\n\n**Connections:**\n*   **Application IDL data types** points to **OpenSplice IDL pre-processor**.\n*   **OpenSplice IDL pre-processor** points to **Java application data classes** and **Foo classes**.\n*   **Java application data classes** points to **Application Java code** (labeled 'import') and **Foo classes** (labeled 'import').\n*   **Application Java code**, **Java application data classes**, and **Foo classes** each point to a **Java compiler**.\n*   Each **Java compiler** points to its respective intermediate code block: **Application intermediate code**, **Java application data intermediate code**, and **Foo classes intermediate code**.\n*   **Application intermediate code**, **Java application data intermediate code**, **Foo classes intermediate code**, and **OpenSplice libraries** all point to **Java Virtual Machine**.\n*   **Java Virtual Machine** points to **Application process**.](.vortex-opensplice-idl-preprocessor-guide/e044a06f26785b4ba37b74e04c6111f2fa6c0a0b25cc09a145f5b43c660f1da7.jpg)

The role of the Vortex OpenSplice IDL Pre-processor functionality is more magnified in the diagram Java Standalone OpenSplice IDL Pre-Processor Details. It shows in more detail which files are generated based upon input file (in this example foo.idl).

Java Standalone OpenSplice IDL Pre-Processor Details
![The flowchart illustrates a data processing pipeline with the following blocks and connections:\n\n**Labeled Blocks:**\n*   Application IDL data types (foo.idl)\n*   OpenSplice IDL pre-processor\n*   data type classes\n*   data type holder classes\n*   TypeSupport, DataReader, DataWriter interface\n*   TypeSupport, DataReader, DataWriter implementation\n\n**Connections:**\n*   An arrow points from the 'Application IDL data types (foo.idl)' block to the 'OpenSplice IDL pre-processor' block.\n*   From the 'OpenSplice IDL pre-processor', a branching arrow points downward to the 'data type classes' block. The 'data type holder classes' block is stacked directly below it.\n*   A second branching arrow from the 'OpenSplice IDL pre-processor' points downward to the 'TypeSupport, DataReader, DataWriter interface' block. The 'TypeSupport, DataReader, DataWriter implementation' block is stacked directly below it.](.vortex-opensplice-idl-preprocessor-guide/4c88fdca54cd5771009b472d744715b00879b336400778ea7d9ae104d63ed8f6.jpg)

# 8.8 Integrated Java ORB

The Java CORBA mode provides a Vortex OpenSplice context for the JacORB ORB. The Vortex OpenSplice IDL Pre-processor generates IDL code for the specialized TypeSupport, DataReader and DataWriter, as well as Java implementations and support code. The ORB pre-processor generates the Java ‘Foo’ classes, which must be done manually. These classes are included with the application Java code as well as the Vortex OpenSplice generated specialized Java implementation code. The application Java code as well as the specialized Java implementation code (with the support functions) is compiled into class files and can be used together with the applicable Vortex OpenSplice libraries and the ORB libraries.

The artifacts and processing stages related to the Java CORBA cohabitation context are similar to those of the standalone mode, with one exception: the ‘Foo’ classes will not be generated by the Vortex OpenSplice IDL Pre-processor. Instead these classes should be generated by the JacORB IDL Pre-processor.

# Extensible and Dynamic Topic Types for DDS annotation support

The specification defines an annotation language as extension to IDL. Even though this specification has not been implemented in Vortex OpenSplice, its IDL pre-processor is already able to parse these extensions even though it does not generate anything special for them yet. This allows users to write future-proof IDL definitions with annotations already in them.

The specification describes two notations for defining annotations in IDL, a prefix and a suffix notation. An annotation type is defined by prefixing a local interface definition with the new token @Annotation. The members of these types shall be represented using IDL attributes, as shown in the following example using the prefix notation:

```txt
@Annotation
local interface MyAnnotation {
    attribute long my_annotation_member_1;
    attribute double my_annotation_member_2;
};
```

Alternately and equivalently, an annotation can be defined by suffixing the interface with the new annotation token using slash-slash-at (//@Annotation) instead, like this:

```txt
local interface MyAnnotation {
    attribute long my_annotation_member_1;
    attribute double my_annotation_member_2;
}; //@Annotation
```

An annotation can be applied to a type or type member by prefixing it with an at sign (@) and the name of the annotation type to apply. To specify the values of any members of the annotation type, include them in name=value syntax between parentheses; for example:

```txt
1 @MyTypeAnnotation
2 struct Gadget {
3    @MyAnnotation(my_annotation_member_1=5, my_annotation_member_2=3.4) long my_integer;
4 };
```

Alternately and equivalently, an annotation can also be applied to a type or type member by suffixing it with an annotation type name using slash-slash-at (//@) instead of the at sign by itself; for example:

```txt
1 struct Gadget {
2 long my_integer; // @MyAnnotation(my_annotation_member_1 = 5, my_annotation_member_2 = 3.4)
3 }; // @MyTypeAnnotation
```

# C++ Lava

Please note that the IDL Pre-Processor only supports the suffix notation when selecting C++ (-l cpp, -l c++, -l isocpp, -l isoc++, -l isocpp2 or -l isoc++2) or CORBA-cohabitated java (-l java -C) as language.

For other languages both prefix and suffix notations are supported. The Extensible and Dynamic Topic Types for DDS specification also defines a number of annotations for use by applications. These types do not appear as annotations at runtime; they exist at runtime only in order to extend the capabilities of IDL. The following annotations have been defined and are accepted by the Vortex OpenSplice IDL pre-processor as well:

• ID
• Optional
• Key
• Shared
• BitBound
• Value
• BitSet
• Nested
• Extensibility
• MustUnderstand
• Verbatim

For more details on built-in annotations and annotations in general please refer to section 7.3.1 of the OMG Extensible and Dynamic Topic Types for DDS specification.

# 10

# Built-in DDS data types

The Vortex OpenSplice IDL Pre-processor and the Vortex OpenSplice runtime system support the following DDS data types to be used in application IDL definitions:

• Duration\_t
• Time\_t

When building C or Java application programs, no special actions have to be taken other than enabling the Vortex OpenSplice IDL Pre-processor built-in DDS data types using the -o dds-types option.

For C++, however, attention must be paid to the ORB IDL compiler, which is also involved in the application building process. The ORB IDL compiler is not aware of any DDS data types, so the supported DDS types must be provided by means of inclusion of an IDL file (dds\_dcps.idl) that defines these types. This file must not be included for the Vortex OpenSplice IDL Pre-processor, which has the type definitions built-in. Therefore dds\_dcps.idl must be included conditionally. The condition can be controlled via the macro definition OSPL\_IDL\_COMPILER, which is defined when the Vortex OpenSplice IDL Pre-processor is invoked, but not when the ORB IDL compiler is invoked:

```cpp
#ifndef OSPL_IDL_COMPILER
#include &lt;dds_dcps.idl&gt;
#endif

module example {
    struct example_struct {
    DDS::Time_ttime;
    };
};
```

![A red triangular warning sign with a white interior featuring a black exclamation point in the center.](.vortex-opensplice-idl-preprocessor-guide/141b438bbcb2d5ad8f1f63c30cdbbcda9f1138976d0528416e4646b7e11892a3.jpg)

The ORB IDL compiler must be called with the -I\$OSPL\_HOME/etc/idlpp option in order to define the include path for the dds\_dcps.idl file. The Vortex OpenSplice IDL Pre-processor must be called without this option.

# 11

# References

The following documents are referred to in the text:

# OMG DDS 2004

Object Management Group, ‘Data Distribution Service for Real-Time Systems’, Final Adopted Specification, ptc/04-04-12 2004

# OMG CORBA v3 2002

Object Management Group, ‘The Common Object Request Broker: Architecture and Specification’, Version 3.0, formal/02-06-01 2002

# OMG C Language 1999

Object Management Group, ‘C Language Mapping Specification’, Version 1.0, formal/99-07-35 1999

# OMG C++ Language 2003

Object Management Group, ‘C++ Language Mapping Specification’, Version 1.1, formal/03-06-03 2003

# OMG Java Language 2002

Object Management Group, ‘Java Language Mapping Specification’, Version 1.2, formal/02-08-05 2002

# OMG ISO/IEC C++ Language 2013

Object Management Group, ‘ISO/IEC C++ 2003 Language DDS PSM’, Version 1.0, formal/2013-11-01 2013

# OMG DDS XTYPES 2012

Object Management Group, ‘Extensible and Dynamic Topic Types for DDS’, Version 1.0, formal/2012-11-10 2012

# 12

# Contacts & Notices

# 12.1 Contacts

# ADLINK Technology Corporation

400 TradeCenter

Suite 5900

Woburn, MA

01801

USA

Tel: +1 781 569 5819

# ADLINK Technology Limited

The Edge

5th Avenue

Team Valley

Gateshead

NE11 0XA

UK

Tel: +44 (0)191 497 9900

# ADLINK Technology SARL

28 rue Jean Rostand

91400 Orsay

France

Tel: +33 (1) 69 015354

Web: http://ist.adlinktech.com/

Contact: http://ist.adlinktech.com

E-mail: ist\_info@adlinktech.com

LinkedIn: https://www.linkedin.com/company/79111/

Twitter: https://twitter.com/ADLINKTech\_usa

Facebook: https://www.facebook.com/ADLINKTECH

# 12.2 Notices

Copyright © 2018 ADLINK Technology Limited. All rights reserved.

This document may be reproduced in whole but not in part. The information contained in this document is subject to change without notice and is made available in good faith without liability on the part of ADLINK Technology Limited. All trademarks acknowledged.
[🔗 Link to the original document](.vortex-opensplice-idl-preprocessor-guide/vortex-opensplice-idl-preprocessor-guide.pdf)