rtiddsgen
[Programming Tools]

Generates source code from data types declared in IDL, XML, XSD, or WSDL files. More... Generates code necessary to allocate, send, receive, and print user-defined data types.

Usage

  rtiddsgen [-d <outdir>] 
	       [-language <C|C++|Java|C++/CLI|C#|Ada>]
               [-namespace]
               [-package <packagePrefix>]
               [-example <arch>]
               [-replace]
	       [-debug]
               [-corba [client header file] [-orb <CORBA ORB>]]
               [-optimization <level of optimization>]
               [-stringSize <Unbounded strings size>]
               [-sequenceSize <Unbounded sequences size>]
               [-notypecode]
               [-ppDisable]
               [-ppPath <preprocessor executable>]
               [-ppOption <option>]
               [-D <name>[=<value>]]
               [-U <name>]
               [-I <directory>]
               [-noCopyable]
               [-use42eAlignment]
               [-enableEscapeChar]
               [-typeSequenceSuffix <Suffix>]
               [-dataReaderSuffix <Suffix>]
               [-dataWriterSuffix <Suffix>]
               [-convertToXml |
                -convertToXsd |
                -convertToWsdl |
                -convertToIdl]
               [-convertToCcl]
               [-convertToCcs]
               [-expandOctetSeq]
               [-expandCharSeq]
               [-metp]
               [-version]
               [-help]
               [-verbosity [1-3]]
               [[-inputIdl] <IDLInputFile.idl> | 
	        [-inputXml] <XMLInputFile.xml> | 
		[-inputXsd] <XSDInputFile.xsd> |
		[-inputWsdl] <WSDLInputFile.wsdl>]

-d Specifies where to put the generated files. If omitted, the input file's directory is used.

-language Generates output for only the language specified. The default is C++.

Use of generated Ada 2005 code requires installation of RTI Ada 2005 Language Support. Please contact support@rti.com for more information.

-namespace Specifies the use of C++ namespaces (for C++ only).

-package Specifies a packagePrefix to use as the root package (for Java only).

-example Generates example programs and makefiles (for UNIX-based systems) or workspace and project files (for Windows systems) based on the input types description file.

The <arch> parameter specifies the architecture for the example makefiles.

For -language C/C++, valid options for <arch> are:

sparcSol2.9gcc3.2, sparcSol2.9gcc3.3, sparcSol2.9cc5.4, sparc64Sol2.10cc5.8, sparcSol2.10gcc3.4.2, sparc64Sol2.10gcc3.4.2, i86Sol2.9gcc3.3.2, i86Sol2.10gcc3.4.4, x64Sol2.10gcc3.4.3,

x64Darwin10gcc4.2.1,

i86Linux2.4gcc3.2, i86Linux2.4gcc3.2.2, x64Linux2.4gcc3.2.3, i86Linux2.6gcc3.4.3, x64Linux2.6gcc3.4.5, i86Linux2.6gcc4.1.1, x64Linux2.6gcc4.1.1, i86Linux2.6gcc4.1.2, x64Linux2.6gcc4.1.2, x64Linux2.6gcc4.3.2, i86Linux2.6gcc4.4.3, x64Linux2.6gcc4.4.3, i86Linux2.6gcc3.4.6, i86RedHawk5.1gcc4.1.2, i86Suse10.1gcc4.1.0, x64Suse10.1gcc4.1.0, armv7leLinux2.6gcc4.4.1,

cell64Linux2.6ppu4.1.1,

ppc4xxFPLinux2.6gcc4.3.3, ppc7400Linux2.6gcc3.3.3, ppc85xxWRLinux2.6gcc4.3.2,

i86Win32VC60, i86Win32VC70, i86Win32VS2003, i86Win32VS2005, x64Win64VS2005, i86Win32VS2008, x64Win64VS2008, i86Win32VS2010, x64Win64VS2010,

armv4WinCE6.0VS2005, i86WinCE6.0VS2005,

ppc7400Lynx4.0.0gcc3.2.2, ppc7400Lynx4.2.0gcc3.2.2, ppc750Lynx4.0.0gcc3.2.2, ppc7400Lynx4.2.0gcc3.4.3, ppc7400Lynx5.0.0gcc3.4.3, i86Lynx4.0.0gcc3.2.2, i86Lynx4.2.0gcc3.2.2, i86LynxOS_SE3.0.0gcc3.4.3,

ppc604Vx5.4gcc, pentiumVx5.5gcc, ppc405Vx5.5gcc, ppc604Vx5.5gcc, ppc603Vx5.5gcc, pentiumVx6.0gcc3.3.2, ppc604Vx6.0gcc3.3.2, pentiumVx6.0gcc3.3.2_rtp, ppc604Vx6.0gcc3.3.2_rtp, pentiumVx6.3gcc3.4.4, ppc604Vx6.3gcc3.4.4, pentiumVx6.3gcc3.4.4_rtp, ppc604Vx6.3gcc3.4.4_rtp, pentiumVx6.5gcc3.4.4, ppc604Vx6.5gcc3.4.4, pentiumVx6.5gcc3.4.4_rtp, ppc604Vx6.5gcc3.4.4_rtp, pentiumVx6.6gcc4.1.2, pentiumVx6.6gcc4.1.2_rtp, ppc405Vx6.6gcc4.1.2, ppc405Vx6.6gcc4.1.2_rtp, ppc604Vx6.6gcc4.1.2, ppc604Vx6.6gcc4.1.2_rtp, ppc604Vx6.7gcc4.1.2, ppc604Vx6.7gcc4.1.2_smp, ppc604Vx6.7gcc4.1.2_rtp, ppc604Vx6.8gcc4.1.2, ppc604Vx6.8gcc4.1.2_rtp, pentiumVx6.8gcc4.1.2, pentiumVx6.8gcc4.1.2_rtp, ppc604Vx6.9gcc4.3.3, ppc604Vx6.9gcc4.3.3_rtp, pentiumVx6.9gcc4.3.3, pentiumVx6.9gcc4.3.3_rtp, pentium64Vx6.9gcc4.3.3, pentium64Vx6.9gcc4.3.3_rtp,

ppc7400Inty5.0.7.mvme5100-7400, ppc7400Inty5.0.7.mvme5100-7400-ipk, ppc7400Inty5.0.9.mvme5100-7400-ghnet2,

p5AIX5.3xlc9.0, 64p5AIX5.3xlc9.0,

i86QNX6.4.1qcc_gpp i86QNX6.5qcc_gpp4.4.2

For -language C++/CLI and C#, valid options for <arch> are:

i86Win32dotnet2.0, x64Win64dotnet2.0, i86Win32dotnet4.0, x64Win64dotnet4.0

For -language java, valid options for <arch> are:

i86Sol2.9jdk, i86Sol2.10jdk, x64Sol2.10jdk, sparcSol2.9jdk, sparcSol2.10jdk, sparc64Sol2.10jdk, x64Darwin10gcc4.2.1jdk, i86Linux2.4gcc3.2jdk, i86Linux2.4gcc3.2.2jdk, x64Linux2.4gcc3.2.3jdk, i86Linux2.6gcc3.4.3jdk, x64Linux2.6gcc3.4.5jdk, i86Linux2.6gcc4.1.1jdk, x64Linux2.6gcc4.1.1jdk, i86Linux2.6gcc4.4.3jdk, x64Linux2.6gcc4.4.3jdk, i86Linux2.6gcc4.1.2jdk, x64Linux2.6gcc4.1.2jdk, x64Linux2.6gcc4.3.2jdk, i86Linux2.6gcc3.4.6jdk, i86RedHawk5.1gcc4.1.2jdk i86Suse10.1gcc4.1.0jdk, x64Suse10.1gcc4.1.0jdk, cell64Linux2.6ppu4.1.1jdk, i86Win32jdk, x64Win64jdk, ppc7400Lynx4.0.0gcc3.2.2jdk, ppc750Lynx4.0.0gcc3.2.2jdk, ppc7400Lynx5.0.0gcc3.4.3jdk, i86Lynx4.0.0gcc3.2.2jdk, p5AIX5.3xlc9.0jdk, 64p5AIX5.3xlc9.0jdk

For -language Ada, valid option for <arch> is i86Linux2.6gcc4.1.2

-replace Overwrites any existing output files. Warning: This removes any changes you may have made to the original files.

-debug Generates intermediate files for debugging purposes.

-corba [client header file] [-orb <CORBA ORB>] Specifies that you want to produce CORBA-compliant code.

Use [client header file] and [-orb <CORBA ORB>] for C++ only. The majority of code generated is independent of the ORB. However, for some IDL features, the code generated depends on the ORB. This version of rtiddsgen generates code compatible with ACE-TAO or JacORB. To pick the ACE_TAO version, use the -orb parameter; the default is ACE_TAO1.6.

client header file: the name of the header file for the IDL types generated by the CORBA IDL compiler. This file will be included in the rtiddsgen type header file instead of generating type definitions.

CORBA support requires the RTI CORBA Compatibility Kit, an add-on product that provides a different version of rtiddsgen. Please contact support@rti.com for more information.

-optimization Sets the optimization level. (Only applies to C/C++)

• 0 (default): No optimization.
• 1: Compiler generates extra code for typedefs but optimizes its use. If the type that is used is a typedef that can be resolved either to a primitive type or to another type defined in the same file, the generated code will invoke the code of the most basic type to which the typedef can be resolved, unless the most basic type is an array or a sequence. This level can be used if the generated code is not expected to be modified.
• 2: Maximum optimization. Functionally the same as level 1, but extra code for typedef is not generated. This level can be used if the typedefs are only referred by types within the same file.

-typeSequenceSuffix Assigns a suffix to the name of the implicit sequence defined for IDL types. (Only applies to CORBA)

By default, the suffix is 'Seq'. For example, given the type 'Foo' the name of the implicit sequence will be 'FooSeq'.

-dataReaderSuffix Assigns a suffix to the name of the DataReader interface. (Only applies to CORBA)

By default, the suffix is 'DataReader'. For example, given the type 'Foo' the name of the DataReader interface will be 'FooDataReader'.

-dataWriterSuffix Assigns a suffix to the name of the DataWriter interface. (Only applies to CORBA)

By default, the suffix is 'DataWriter'. For example, given the type 'Foo' the name of the DataWriter interface will be 'FooDataWriter'.

-stringSize Sets the size for unbounded strings. Default: 255 bytes.

-sequenceSize Sets the size for unbounded sequences. Default: 100 elements.

-notypecode: Disables the generation of type code information.

-ppDisable: Disables the preprocessor.

-ppPath <preprocessor executable>: Specifies the preprocessor path. If you only specify the name of an executable (not a complete path to that executable), the executable must be found in your Path.

The default value is "cpp" for non-Windows architectures, "cl.exe" for Windows architectures.

If the default preprocessor is not found in your Path and you use -ppPath to provide its full path and filename, you must also use -ppOption (described below) to set the following preprocessor options:

• If you use a non-default path for cl.exe, you also need to set:
  -ppOption /nologo -ppOption /C -ppOption /E -ppOption /X

• If you use a non-default path for cpp, you also need to set:
  -ppOption -C

-ppOption <option>: Specifies a preprocessor option. This parameter can be used multiple times to provide the command-line options for the specified preprocessor. See -ppPath (above).

-D <name>[=<value>]: Defines preprocessor macros.

-U <name>: Cancels any previous definition of name.

-I <directory>: Adds to the list of directories to be searched for type-definition files (IDL, XML, XSD or WSDL files). Note: A type-definition file in one format cannot include a file in another format.

-noCopyable: Forces rtiddsgen to put copy logic into the corresponding TypeSupport class rather than the type itself (for Java code generation only).

This option is not compatible with the use of ndds_standalone_type.jar.

-use42eAlignment: Generates code compliant with RTI Data Distribution Service 4.2e.

If your RTI Data Distribution Service application's data type uses a 'double','long long','unsigned long long', or 'long double' it will not be backwards compatible with RTI Data Distribution Service 4.2e applications unless you use the -use42eAlignment flag when generating code with rtiddsgen.

-enableEscapeChar: Enables use of the escape character '_' in IDL identifiers. With CORBA this option is always enabled.

-convertToXml: Converts the input type-description file to XML format.

-convertToIdl: Converts the input type-description file to IDL format.

-convertToXsd: Converts the input type-description file to XSD format.

-convertToWsdl: Converts the input type-description file to WSDL format.

-convertToCcl: Converts the input type-description file to CCL format.

-convertToCcs: Converts the input type-description file to CCS format.

-expandOctetSeq: When converting to CCS or CCL files, expand octet sequences. The default is to use a blob type.

-expandCharSeq: When converting to CCS or CCL files, expand char sequences. The default is to use a string type.

-metp: Generates code for the Multi-Encapsulation Type Support (METP) library.

-version: Prints the version, such as 4.5x. (Does not show 'patch' revision number.)

-help: Prints this rtiddsgen usage help.

-verbosity: rtiddsgen verbosity.

• 1: exceptions
• 2: exceptions and warnings
• 3 (default): exceptions, warnings and information

-inputIdl: Indicates that the input file is an IDL file, regardless of the file extension.

-inputXml: Indicates that the input file is a XML file, regardless of the file extension.

-inputXsd: Indicates that the input file is a XSD file, regardless of the file extension.

-inputWsdl: Indicates that the input file is a WSDL file, regardless of the file extension.

IDLInputFile.idl: File containing IDL descriptions of your data types. If -inputIdl is not used, the file must have an .idl extension.

XMLInputFile.xml: File containing XML descriptions of your data types. If -inputXml is not used, the file must have an .xml extension.

XSDInputFile.xsd: File containing XSD descriptions of your data types. If -inputXsd is not used, the file must have an .xsd extension.

XSDInputFile.wsdl: WSDL file containing XSD descriptions of your data types. If -inputWsdl is not used, the file must have an .wsdl extension.

Description

rtiddsgen takes a language-independent specification of the data (in IDL, XML, XSD or WSDL notation) and generates supporting classes and code to distribute instances of the data over RTI Data Distribution Service.

To use rtiddsgen, you first write a description of your data types in IDL, XML, XSD or WSDL format.

C++ Example

The following is an example generating the RTI Data Distribution Service type myDataType:

IDL notation

struct myDataType {
    long value;
};

XML notation

<?xml version="1.0" encoding="UTF-8"?>
<types xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="rti_dds_topic_types.xsd">
    <struct name="myDataType">
        <member name="value" type="long"/>
    </struct>
</types>

XSD notation

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
             xmlns:dds="http://www.omg.org/dds" 
	     xmlns:tns="http://www.omg.org/IDL-Mapped/" 
	     targetNamespace="http://www.omg.org/IDL-Mapped/">
  <xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti_dds_topic_types_common.xsd"/>
  <xsd:complexType name="myDataType">
    <xsd:sequence>
      <xsd:element name="value" minOccurs="1" maxOccurs="1" type="xsd:int"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:schema>

WSDL notation

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:dds="http://www.omg.org/dds" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.omg.org/IDL-Mapped/" targetNamespace="http://www.omg.org/IDL-Mapped/">
  <types>
    <xsd:schema targetNamespace="http://www.omg.org/IDL-Mapped/">
      <xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti_dds_topic_types_common.xsd"/>
      <xsd:complexType name="myDataType">
        <xsd:sequence>
          <xsd:element name="value" minOccurs="1" maxOccurs="1" type="xsd:int"/>
        </xsd:sequence>
      </xsd:complexType>
    </xsd:schema>
  </types>
</definitions>

Assuming the name of the idl file is myFileName.(idl|xml|xsd|wsdl) then all you need to do is type:

rtiddsgen myFileName.(idl|xml|xsd|wsdl)

This generates myFileName.cxx, myFileName.h, myFileNamePlugin.cxx, myFileNamePlugin.h, myFileNameSupport.cxx and myFileNameSupport.h. By default, rtiddsgen will not overwrite these files. You must use the -replace argument to do that.

IDL Language

In the IDL language, data types are described in a fashion almost identical to structures in "C." The complete description of the language can be found at the OMG website.

rtiddsgen does not support the full IDL language.

For detailed information about the IDL support in RTI Data Distribution Service see Chapter 3 of the user manual.

Below are the IDL types that are currently supported:

• char
• wchar
• octet
• short
• unsigned short
• long
• unsigned long
• long long
• unsigned long long
• float
• double
• long double
• boolean
• bounded string
• unbounded string
• bounded wstring
• unbounded wstring
• enum
• typedef
• struct
• valuetypes (limited support)
• union
• sequences
• unbounded sequences
• arrays
• array of sequences
• constant

The following non-IDL types are also supported by rtiddsgen:

• bitfield
• valued enum

Use of Unsupported Types in an IDL File

You may include unsupported data types in the IDL file. rtiddsgen does not consider this an error. This allows you to use types that are defined in non-IDL languages with either hand-written or non-rtiddsgen written plug-ins. For example, the following is allowable:

//@copy #include "Bar.h"
//@copy #include "BarHandGeneratedPlugin.h"
struct Foo {
short height;
Bar barMember;
};

In the above case, Bar is defined externally by the user.

Multiple Types in a Single File

You can specify multiple types in a single idl file. This can simplify management of files in your distributed program.

Use of Directives in an IDL File

The following directives can be used in your IDL file: Note: Do not put a space between the slashes and the @ sign. Note: Directives are case-sensitive (for example: use key, not Key).

• //@key The field declared just before this directive in the enclosing structure is part of the key. Any number of a structure's fields may be declared part of the key.

• //@copy This copies a line of text into the generated code verbatim (for all languages). The text is copied into all of the type-specific files generated by rtiddsgen (except the examples).
• //@copy-c Same as //@copy, but for C++/C-only code.
• //@copy-java Same as //@copy, but for Java-only code.
• //@copy-java-begin This copies a line of text at the beginning of all the Java files generated for a type. The directive only applies to the first type that is immediately below in the IDL file.

• //@copy-declaration This is like //@copy, but only copies the text into the file where the type is declared (<type>.h for C++/C, or <type>.java for Java).
• //@copy-c-declaration Same as //@copy-declaration, but for C++/C-only code.
• //@copy-java-declaration Same as //@copy-declaration, but for Java-only code.
• //@copy-java-declaration-begin This is like //@copy-java-begin but only copies the text into the file where the type is declared.

• //@resolve-name [true|false] This specifies whether or not rtiddsgen should resolve the scope of a type. If this directive is not present or set to true, rtiddsgen resolves the scope. Otherwise rtiddsgen delegates the resolution of a type to the user.

• //@top-level [true|false] This specifies whether or not rtiddsgen should generate type-support code for a particular struct or union. The default is true.

XML Language

The data types can be described using XML.

RTI Data Distribution Service provides DTD and XSD files that describe the XML format.

The DTD definition of the XML elements can be found in rti_dds_topic_types.dtd under <NDDSHOME>/resource/dtd.

The XSD definition of the XML elements can be found in rti_dds_topic_types.dtd under <NDDSHOME>/resource/xsd.

The XML validation performed by rtiddsgen always uses the DTD definition. If the <!DOCTYPE> tag is not present in the XML file, rtiddsgen will look for the DTD document under <NDDSHOME>/resource/dtd. Otherwise, it will use the location specified in <!DOCTYPE>.

For detailed information about the mapping between IDL and XML see Chapter 3 of the RTI Data Distribution Service User Manual.

XSD Language

The data types can be described using XML schemas (XSD files). The XSD specification is based on the standard IDL to WSDL mapping described in the OMG document CORBA to WSDL/SOAP Interworking Specification

For detailed information about the mapping between IDL and XML see Chapter 3 of the RTI Data Distribution Service User Manual.

WSDL Language

The data types can be described using XML schemas contained in WSDL files. The XSD specification is based on the standard IDL to WSDL mapping described in the OMG document CORBA to WSDL/SOAP Interworking Specification

For detailed information about the mapping between IDL and XML see Chapter 3 of the RTI Data Distribution Service User Manual.

Using Generated Types Without RTI Data Distribution Service (Standalone)

You can use the generated type-specific source and header files without linking the RTI Data Distribution Service libraries or even including the RTI Data Distribution Service header files. That is, the generated files for your data types can be used standalone.

The directory <NDDSHOME>/resource/standalone contains the helper files required to work in standalone mode:

• include: header and templates files for C/C++.
• src: source files for C/C++.
• class: Java jar file.

Using Standalone Types in C

The generated files that can be used standalone are:

• <idl file name>.c : Types source file
• <idl file name>.h : Types header file

You cannot use the type plug-in (<idl file>Plugin.c <idl file>Plugin.h) or the type support (<idl file>Support.c <idl file>Support.h) code standalone.

To use the rtiddsgen-generated types in a standalone manner:

• Include the directory <NDDSHOME>/resource/standalone/include in the list of directories to be searched for header files.
• Add the source files ndds_standalone_type.c and <idl file name>.c to your project.
• Include the file <idl file name>.h in the source files that will use the generated types in a standalone way.
• Compile the project using the two following preprocessor definitions:
  • NDDS_STANDALONE_TYPE
  • The definition for your platform: RTI_VXWORKS, RTI_QNX, RTI_WIN32, RTI_INTY, RTI_LYNX or RTI_UNIX

Using Standalone Types in C++

The generated files that can be used standalone are:

• <idl file name>.cxx : Types source file
• <idl file name>.h : Types header file

You cannot use the type plugin (<idl file>Plugin.cxx <idl file>Plugin.h) or the type support (<idl file>Support.cxx <idl file>Support.h) code standalone.

To use the generated types in a standalone manner:

• Include the directory <NDDSHOME>/resource/standalone/include in the list of directories to be searched for header files.
• Add the source files ndds_standalone_type.cxx and <idl file name>.cxx to your project.
• Include the file <idl file name>.h in the source files that will use the generated types in a standalone way.
• Compile the project using the two following preprocessor definitions:
  • NDDS_STANDALONE_TYPE
  • The definition for your platform: RTI_VXWORKS, RTI_QNX, RTI_WIN32, RTI_INTY, RTI_LYNX or RTI_UNIX

Standalone Types in Java

The generated files that can be used standalone are:

• <idl type>.java
• <idl type>Seq.java

You cannot use the type code (<idl file>TypeCode.java), the type support (<idl type>TypeSupport.java), the data reader (<idl file>DataReader.java) or the data writer code (<idl file>DataWriter.java) standalone.

To use the generated types in a standalone manner:

• Include the file ndds_standalone_type.jar in the classpath of your project.
• Compile the project using the standalone types files (<idl type>.java <idl type>Seq.java).