| Option | Description |
| -chs= | Generated client header suffix (default .h) |
| -cis= | Generated client implementation suffix (default .cpp) |
| -client_only | Generates only the client files. |
| -collocated_direct | Generate code for direct servant invocation. |
| -D[=value] | Defines name and an optional value for use with preprocessor conditional directives in the IDL specification file. White space between the -D and the name is optional. This option can be repeated to specify multiple preprocessor directives. |
| -E | Only runs the pre-processor, printing the output. |
| -enum32 | Can be used when enumerated types map naturally to 32-bit values. Prevents generation of additional enumeration to force size. |
| -[no]exceptions | Generate code to support native or non-native exceptions (as opposed to portable macros). |
| -gen_any | Generates code to support insertion and extraction of IDL types using anys. This flag must be used for IDL files which contain anys. |
| -gen_names | Generates code to support operations that return id, name, and member_name for TypeCodes and dynamic anys.
Setting this flag automatically sets the gen_any flag. |
| -gen_tie | Generates a tie template class for each interface. By default, idlcpp does not generate tie templates. |
| -I<directory> | Adds directory to the list of directories to be searched for included IDL files. |
| -ignore_interfaces | Do not generate interface code. |
| -import_export=<macro> | Generates all of the code necessary to import or export the generated classes from a user-built Dynamic Link Library for Windows. See Creating a DLL on page 26 for more details. |
| -M | Generate code for included files |
| -no_map_wide | Do not map wchar/wstring types to char/string. Generate compiler error instead. |
| -max_char=<num> | Sets the maximum number of characters per line for generated files. If a line in the IDL file exceeds num characters, the line is split by a backslash character (\) and continued on a new line. The default maximum number of characters per line is 1024. |
| -no_warn | Disable warning messages. |
| -o or -output <dir> | Generates output into specified directory. |
| -shs=<suffix> | Generated server header suffix (default _s . h) |
| -sis=<suffix> | Generated server implementation suffix (default _s . cpp) |
| -strip_includes | Strips path information from #include directives in the generated code. For example: #include "common/types.idl" in an IDL file will be translated into #include "types.h" in the generated code. |
| -u | Displays usage message and exits. Note that this is a lower-case u. |
| -U | Removes any initial definition of the preprocessor directive name. This option can be repeated to undefined multiple names. This is the opposite of the -D option. White space between the -U and the name is optional. Note that this is an upper-case U. |
| -v | Traces compilation stages. Note that this is a lower-case v. |
| -V | Prints compiler version information and exits. Note that this is an upper-case V. -version can also be used to display version information. |
| -w | Suppresses compiler warning messages. |
# 3.2 IDL Compiler Output
The IDL to C++ compiler will generate the four files shown in Figure 1 for an IDL specification file called hello.idl.
Figure 1 Example Generated C++ Files
Note that this is the default output from the IDL compiler. The number, type, and names of the output files can be changed with command-line options (given in Table 5, IDL to C++ Compiler Options, on page 22).
# 3.2.1 C++ Files Produced
• hello.h is the client header file containing stub declarations. It defines the C++ types associated with the IDL types defined in the IDL specification. The C++ types in this header file are used by client programs and object implementations. This header file provides a C++ abstract base class for every interface construct in the IDL specification. For clients, this header file provides remote access to object references through stubs that correspond to the IDL-defined interface operations. An ORB client program includes this header file and makes a request by calling one of the stub routines on an object reference.
• hello.cpp is the client implementation file containing stub definitions. It contains implementations of the types declared in hello.h. The interface implementation file is compiled and linked with an ORB client program and with object implementations.
• hello\_s.h is the server implementation base header file containing the skeleton and tie declarations. It provides C++ types that you use in your object implementation. An ORB object implementation file includes this header file, which in turn includes the interface header file, hello.h. If the -gen\_tie compiler switch is used, hello\_s.h will also contain the tie template class definition.
• hello\_s.cpp is the server implementation base file containing the skeleton and tie class definitions. It contains the implementations of operation dispatch functions required by object implementations. The object implementation dispatch file is compiled and linked with an ORB object implementation.
# 3.2.2 Using the IDL Compiler Output
The header files produced by the IDL compiler are used as follows:
• the client’s modules must include the client header file (using a #include directive)
• the server’s modules must include the server header file (using a #include directive)
The client and server implementation files produced by the IDL compiler should be compiled and linked with the application.
# 3.2.3 Creating a DLL
A Win32 DLL (Dynamic Link Library) can be created by the IDL compiler by using the -import\_export=<macro> command-line option.
. The following example illustrates this with the MY\_DLL macro:
```batch
% idlcpp -import_export=MY_DLL hello.idl
```
This inserts an import/export block into hello.h as follows:
```cmake
#if defined(_WIN32)
if defined(EORB_BUILD_MY_DLL)
define MY_DLL __declspec(dllexport)
elif defined(EORB_NO_MY_DLL)
define MY_DLL
else
define MY_DLL __declspec(dllexport)
endif
#else
#define MY_DLL
#endif
```
When compiling the generated source into a DLL, -DEORB\_BUILD\_MY\_DLL must be used. This ensures that the appropriate symbols are declared as exported from the resulting DLL (by declaring \_\_declspec(dllexport)).
When compiling the generated source into a static library, and when compiling other code that is to be linked with the resulting static library, -DEORB\_NO\_MY\_DLL must b e u s e d t o e n s ur e t h a t t h e r e i s n o \_\_ d e c l s pe c ( d l l i mp o r t ) or \_\_declspec(dllexport) declaration.
If neither -DEORB\_BUILD\_MY\_DLL nor -DEORB\_NO\_MY\_DLL are used then the appropriate symbols will be declared as \_\_declspec(dllimport), which is effectively “standard” behaviour for a C++ file.
# CHAPTER
# IDL to C++ Mapping
This section describes the IDL to the C++ language mapping for Spectra ORB C++ Edition. Applications, clients or servers which conform to the constructs described here will be portable across conforming ORB implementations.
i The ORB’s IDL to C++ compiler conforms to the OMG’s C++ Language Mapping Specification Version 1.0.
# 4.1 Namespaces
Names in IDL can be scoped within a module or an interface in order to avoid identifier conflicts. This mapping ensures that you can use each of the types defined in the IDL specification without ambiguity.
# 4.1.1 Scoped Names and Namespaces
Names which are scoped in IDL are mapped to C++ scoped names as follows:
• modules can be mapped to C++ namespaces
• interfaces are mapped to C++ classes
• All IDL constructs which are scoped to an interface or module are accessed via C++ scoped names. For example, if a type Mode were defined in interface Printer, the type would be referred to as Printer::Mode.
These mappings allow corresponding mechanisms to be used in both IDL and C++ to build scoped names. For example, the IDL is logically mapped into C++ as:
```txt
// IDL
module M
{
struct S
{
// definitions
};
union U
{
// definitions
};
};
```
```txt
// C++
namespace M
```
```txt
{
struct S
{
// definitions
};
union U
{
// definitions
};
};
```
The following are legal scoped names in C++:
```txt
// C++
M::S s;
M::U u;
```
Alternatively, employing the C++ using statement allows you to specify the name without explicitly using scoping.
```txt
// C++
using namespace M;
S s;
U u;
```
# 4.2 Modules
A module defines a scope and maps to a C++ namespace with the same name:
```txt
// IDL
module M
{
// definitions
};
```
```txt
// C++
namespace M
{
// definitions
}
```
# Example Mapping to namespace
The IDL module M mapping to namespace is shown below.
```txt
// IDL
module M
{
// definitions
};
```
# 4.3 Interfaces
IDL interfaces are mapped to abstract C++ classes using the same name and scope as the interface. The interface class includes methods for each of the operations and attributes that the interface supports. The interface class contains public C++ definitions for each of the IDL types defined in the scope of the interface in IDL.
Each interface class is derived from CORBA::Object, which defines behaviours common to all interface classes.
Note that the ORB typedefs CORBA::Object to CORBA::Stub.
# Example Interface mapping to Class
The example IDL interface A maps to the C++ class A as shown below:
```txt
interface A
{
const float pi = 3.14159;
struct S
{
short field;
};
void op();
};
```
```cpp
class A
:
virtual public CORBA::Object //e*ORB uses CORBA::Stub
{
public:
// Nested definitions
static const CORBA::Float pi;
struct S {
CORBA::Short field;
};
// operations
virtual void op() = 0;
// Object reference operations, explained later
protected:
// restricted behaviours
A();
virtual ~A();
private:
A(const A&);
void operator = (const A&);
};
```
A CORBA-compliant C++ program cannot
• create or hold an instance of an interface class
• use a pointer (A\*) or reference (A&) to an interface class
• reference ORB-specific interface classes (classes other than A, A\_ptr, and A\_var) that an ORB implementation might generate to implement interface behaviours in C++
# Example Non-conformant uses
The following uses of class A are not conformant:
```typescript
// C++: Non-conformant uses
A a; // cannot declare an instance of an
// interface class...
A * p; // nor declare a pointer to an interface
// class...
void f(A & r); // nor declare a reference to an
// interface class
```
A CORBA-compliant program may refer to nested types and constants using their fully-qualified scoped names as follows:
```txt
// C++
A::S s; // declare a struct variable
s.field = 3; // field access
```
# 4.3.1 The \_var Type
The \_var type for an interface both manages and behaves like an object reference. For the interface A, A\_var behaves like the A\_ptr object reference except that the A\_var releases the real object reference when it goes out of scope or is assigned a new object reference.
# Example \_var type for an interface
The following code demonstrates using the interface \_var type to invoke an operation on a managed object reference:
```txt
A_ptr ap = ... // obtain a reference to an A
A_var av = ap // av assumes ownership of ap.
av->op(); // Invoke op on av's object reference.
```
The A\_var and A\_ptr types may be assigned to each other without any explicit operations or casts. However, keep in mind that the var deallocates its pointer when it goes out of scope. Be careful to avoid using an object reference after it has been deallocated by a var. For example, the assignment statement in the code below results in the object reference held by p being released at the end of the block containing the declaration of v. Attempting to use the object reference after the end of the block causes errors because the var releases the object reference.
```txt
// C++
A_ptr p = // ...somehow obtain an A
{
```
```javascript
A_var v;
v = p;
} // v will release the object reference when it goes out
// of scope
p->op(); // this call will fail since the object reference
// has been released by v.
```
# 4.3.2 Object References
An IDL object reference maps to two C++ types. For an interface A, these types are named A\_ptr and A\_var where
• the name for the object reference is formed by appending \_ptr or \_var to the name of the interface
• the \_ptr type behaves like a raw C++ pointer type
• the \_var type behaves like the \_ptr object reference except that the \_var type releases the real object reference when it goes out of scope or is assigned a new object reference
i The ORB defines A\_ptr for an interface A as a C++ pointer:
```txt
class A;
typedef A * A_ptr;
```
Operations on an object can be performed with an object reference by using the arrow operator ( -> ) on the object reference (\_ptr).
To invoke op on ap, which is a reference to an A:
```txt
A_ptr ap = ... // obtain a reference to an A
ap->op(); // invoke op on ap
```
An object reference is used the same way when it refers to a local object instance as when it refers to a remote object instance. Using the object reference type enables the caller of an object’s services to make requests on an object without regard to the object’s implementation or location, whether the object is local to the caller’s process address space or an object instance on a remote host.
# 4.3.3 Object Reference Operations
The C++ mapping provides a number of standard functions for manipulating and comparing object references. These functions are either static functions in the CORBA namespace or are member functions of CORBA::Object.
# 4.3.3.1 Common Operations
CORBA defines three operations on any object reference: duplicate, release, and is\_nil. Note that these are operations on the object reference, not the object implementation. Because the mapping does not require that object references to themselves be C++ objects, the -> syntax cannot be employed to express the usage of these operations. Also, for convenience these operations are allowed to be performed on a nil object reference.
# 4.3.3.1.1 \_duplicate and \_nil
\_duplicate and \_nil are static member functions generated for each interface and are especially useful for initializing object references.
These functions are generated as follows:
```cpp
// IDL
interface A {};
// C++
class A
{
...
static A_ptr _duplicate(A_ptr obj);
static A_ptr _nil();
...
};
```
The \_duplicate function returns a new object reference with the same static type as the given reference and does not consume the given object reference. The caller is responsible for releasing the returned object reference.
A nil object reference is a special value that refers to no object. This value might be used to initialize a return value or as a return from an unsuccessful search request. The \_nil function returns the nil object reference value for a given type. Whether to release the returned nil pointer is a stylistic decision that has no impact on code integrity. Conforming applications may not attempt to invoke methods on a nil object reference.
Example duplicate and nil usage
```cpp
// IDL
interface A {}; // C++
A_ptr ap1 = ... // get an object reference
A_ptr ap2 = A::_duplicate(ap1); // assign a copy of ap1 to ap2
A_ptr ap3 = A::_nil(); // assign a nil object
// reference to np3
```
# 4.3.3.1.2 is\_nil and release
is\_nil and release are both static functions defined in the CORBA namespace as follows:
```txt
// C++
namespace CORBA
{
```
```txt
void release(Object_ptr obj);
Boolean is_nil(Object_ptr obj);
};
```
The release operation indicates that the caller will no longer access the reference, so associated resources may be deallocated. If the given object reference is nil, then release does nothing.
The is\_nil operation returns TRUE if the object reference contains the special value for a nil object reference as defined by the ORB. Neither the release operation nor the is\_nil operation may throw CORBA exceptions.
A compliant application need not call release on the object reference returned from the \_nil function. References may not be compared using operator==; therefore, is\_nil is the only compliant way an object reference can be checked to see if it is nil.
The \_nil function may not throw any CORBA exceptions. A compliant program cannot attempt to invoke an operation through a nil object reference, since a valid C++ implementation of a nil object reference is a null pointer.
For each interface A the following is always guaranteed to return TRUE:
```c
// IDL
interface A {};
// C++
Boolean true_result = CORBA::is_nil(A::_nil());
```
# 4.3.3.2 Widening Object References
An object reference for a derived interface can be widened to an object reference of a statically known parent type without any explicit operations or casts. For example, if interface B is derived from interface A, then the following implicit widening operations for B are supported:
• B\_ptr to A\_ptr
• B\_ptr to CORBA::Object\_ptr
• B\_var to A\_ptr
• B\_var to CORBA::Object\_ptr
When mixing \_var and \_ptr types, be careful to avoid the direct use of an object reference that has been assigned to a \_var. Once the \_var leaves scope, the object reference is no longer valid.
An attempt to implicitly widen from one \_var type to another will cause a compile-time error. Assignment between two \_var objects of the same type is supported, but widening assignments are not and will cause a compile-time error.
Widening assignments may be done using \_duplicate. The same rules apply for object reference types that are nested in a complex type, such as a structure or sequence. The following code demonstrates these rules:
```cpp
// C++
B_ptr bp = ... // acquire a reference to B
A_ptr ap = bp; // implicit widening
CORBA::Object_ptr objp = bp; // implicit widening
objp = ap; // implicit widening
B_var bv = bp; // bv assumes ownership of bp
ap = bv; // implicit widening, bv retains ownership
obp = bv; // implicit widening,
// bv retains ownership
A_var av = bv; // illegal, no implicit conversions
A_var av = B::_duplicate(bv); // av and bv both refer to bp
B_var bv2 = bv; // implicit _duplicate
A_var av2;
av2 = av; // implicit _duplicate
```
# 4.3.3.3 Narrowing Object References
The mapping for an interface defines the \_narrow static member function which returns a new object reference when passed an existing reference. Like \_duplicate, the \_narrow function returns a nil object reference if the given reference is nil. Unlike \_duplicate, the parameter to \_narrow is a reference of an object of any interface type. If the actual runtime type is of the requested interface's type, then \_narrow returns a valid object reference. Otherwise, \_narrow returns a nil object reference. For example, given the IDL shown below if the actual run-time type of the object referenced by a CORBA::Object\_ptr obj is C, then:
```txt
// IDL
interface A {};
interface B : A {};
interface C : B {};
interface D : C {};
```
• A::\_narrow(obj) returns a valid object reference
• B::\_narrow(obj) returns a valid object reference
• C::\_narrow(obj) returns a valid object reference
• D::\_narrow(obj) returns a nil object reference
Narrowing to A, B, and C all succeed because the object referenced by obj supports all those interfaces. D::\_narrow(obj) fails because the C object does not support the D interface.
The client may need to make a distributed call in order to determine the actual runtime type of the object.
If successful, the \_narrow function creates a new object reference and does not consume the given object reference, so the caller is responsible for releasing both the original and new references.
The \_narrow operation can throw CORBA system exceptions.
# 4.4 Data Type Mappings
# 4.4.1 Constants
IDL constants map directly to a C++ constant definition that may or may not define storage, depending on the scope of the declaration. In the example below, a top-level IDL constant maps to a file-scope C++ constant, but a nested constant maps to a class-scope C++ constant. This inconsistency occurs because C++ file-scope constants may or may not require storage, or the storage may be replicated in each compilation unit, while class-scope constants always take storage. As a side effect, this difference means that the generated C++ header file might not contain values for constants defined in the IDL file.
Example
```cpp
// IDL
const string some_string = "some string";
interface A
{
const float pi = 3.14159;
};
// C++
static const CORBA::String some_string = "some string";
class A
{
public:
static const CORBA::Float pi;
};
```
The generated code must use the constant’s value instead of the constant’s name in certain situations. For example:
```cpp
// IDL
interface A
{
const long n = 10;
typedef long V[n];
};
// C++
class A
{
public:
static const CORBA::Long n;
typedef CORBA::Long V[10];
};
```
When generating constant values for long long types, compilers that do not support native long long types are limited to 32-bit constant values.
# 4.4.2 Typedefs
A typedef creates an alias for a type. If the original type maps to several types in C++, the code generator creates the corresponding alias for each type. The following example illustrates the mapping:
```c
// IDL
typedef long long_t;
interface i;
typedef i i_t;
typedef sequence<long> long_sequence;
typedef long_sequence long_sequence_t;
// C++
typedef CORBA::Long long_t;
// Definitions for interface i, i_ptr, i_var
typedef i i_t;
typedef i_ptr i_t_ptr;
typedef i_var i_t_var;
// Definition for long_sequence, long_sequence_var
typedef long_sequence long_sequence_t;
typedef long_sequence_var long_sequence_t_var;
```
# 4.4.3 Basic Data Types
The following table shows mappings and sizes for the basic data types as defined in the eOrb/CORBA.h header file.
Table 6 Basic Data Types Mapping and Sizes