Chapter 1 Introduction

omniORB is an Object Request Broker (ORB) that implements the 2.3 specification of the Common Object Request Broker Architecture (CORBA) [OMG99]¹. It has passed the Open Group CORBA compliant testsuite and is one of the three ORBs to have been granted the CORBA brand in June 1999².

This user guide tells you how to use omniORB to develop CORBA applications. It assumes a basic understanding of CORBA.

In this chapter, we give an overview of the main features of omniORB and what you need to do to setup your environment to run omniORB.

1.1 Features

1.1.1 CORBA 2.3 compliant

omniORB implements the Internet Inter-ORB Protocol (IIOP). This protocol provides omniORB the means of achieving interoperability with the ORBs implemented by other vendors. In fact, this is the native protocol used by omniORB for the communication amongst its objects residing in different address spaces. Moreover, the IDL to C++ language mapping provided by omniORB conforms to the latest revision of the CORBA specification. Type Any and TypeCode are now supported (introduced in version 2.5.0). DynAny is supported since 2.6.0. The Dynamic Invocation Interface and Dynamic Skeleton Interface are supported since 2.7.0. The C++ mapping has been updated to the CORBA 2.3 specification since 2.8.0. The POA was introduced with 3.0.

1.1.2 Multithreading

omniORB is fully multithreaded. To achieve low IIOP call overhead, unnecessary call-multiplexing is eliminated. At any time, there is at most one call in-flight in each communication channel between two address spaces. To do so without limiting the level of concurrency, new channels connecting the two address spaces are created on demand and cached when there are more concurrent calls in progress. Each channel is served by a dedicated thread. This arrangement provides maximal concurrency and eliminates any thread switching in either of the address spaces to process a call. Furthermore, to maximise the throughput in processing large call arguments, large data elements are sent as soon as they are processed while the other arguments are being marshalled.

1.1.3 Portability

At AT&T Laboratories, the ability to target a single source tree to multiple platforms is very important. This is difficult to achieve if the IDL to C++ mapping for these platforms are different. We avoid this problem by making sure that only one IDL to C++ mapping is used. We run several flavours of Unix, Windows NT, Windows 95 and our in-house developed systems for our own hardware. omniORB has been ported to all these platforms. The IDL to C++ mapping for all these targets is the same.

omniORB uses real C++ exceptions and nested classes. We keep to the CORBA specification's standard mapping as much as possible and do not use the alternative mappings for C++ dialects. The only exception is the mapping of modules.

Starting with 2.6.0, the code generated by the IDL compiler of omniORB can be compiled using C++ classes or namespaces to represent IDL modules depending on the availability of namespace support in the compiler.

omniORB relies on the native thread libraries to provide the multithreading capability. A small class library (omnithread [Ric96b]) is used to encapsulate the (possibly different) APIs of the native thread libraries. In application code, it is recommended but not mandatory to use this class library for thread management. It should be easy to port omnithread to any platform that either supports the POSIX thread standard or has a thread package that supports similar capabilities.

1.1.4 Missing features

omniORB is not (yet) a complete implementation of the CORBA 2.3 core. The following is a list of the missing features.

omniORB does not have its own Interface Repository. However, it can act as a client to an IR.
The IDL types wchar, wstring, fixed, and valuetype are not supported in this release.
The PortableServer::Current interface is not yet supported.
The DSI interface has changed significantly. Old code will have to be re-written to the new interface. There is no support for using the DSI with the BOA. This part of the ORB is incomplete, since it depends in part on PortableServer::Current. See chapter 12 for a way to workaround this problem for now.

These features may be implemented in the short to medium term. It is best to check out the latest status on the omniORB home page (http://www.uk.research.att.com/omniORB/).

1.2 Setting Up Your Environment

At AT&T Laboratories Cambridge, you should use the OMNI Development Environment (ODE) [Ric96a] and the OMNI tree version 5.0 or above to compile your programs. If this is the case, there is no extra setup you have to do other than those described in the ODE documentation.

If you are running omniORB at other sites, you (or your system administrator) should install omniORB by following the instructions in the installation notes.

On Unix platforms, the omniORB runtime looks for the environment variable OMNIORB_CONFIG. If this variable is defined, it contains the pathname of the omniORB configuration file. If the variable is not set, omniORB will use the compiled-in pathname to locate the file.
On ARM/ATMos, the omniORB runtime looks for configuration information in the file omniORB.cfg.
On Win32 platforms (Windows NT, 2000, 95, 98), omniORB first checks the environment variable OMNIORB_CONFIG to obtain the pathname of the configuration file. If this is not set, it then attempts to obtain configuration data in the system registry. It searches for the data under the key HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0.

The configuration file is used to obtain an object reference for the Naming Service, via either a stringified IOR or an Interoperable Naming Service URI. The entry in the configuration file should be specified in the form:

   ORBInitRef NameService=<URI for the Naming Service>

The easiest way of specifying the Naming Service is with a corbaname: URI, as described in section 4.1.2.

Comments in the configuration file should be prefixed with a `#' character.

On Win32 platforms, the naming service reference can be placed in the system registry, in the (string) value ORBInitRef, under the key HKEY_LOCAL_MACHINE\SOFTWARE\ORL\omniORB\2.0.

1.2.1 Deprecated configuration file entries

ORBInitRef is new with omniORB 3.0. The omniORB 2 formats are still supported, so you can specify the Naming Service IOR using a line of the form:

   NAMESERVICE <IOR for the Naming Service>

Since 2.6.0, two other entries have been supported, but are now made obsolete by the Interoperable Naming Service URIs:

   ORBInitialHost <hostname string>
   ORBInitialPort <port number (1-65535)>

The corresponding entries under the Win32 system registry are the keys named ORBInitialHost and ORBInitialPort.

The two entries provide information to the ORB to locate a (proprietary) bootstrap service at runtime. The bootstrap service is able to return the initial object reference for the Naming Service and others.

1.3 Platform specific variables

To compile omniORB programs correctly, several C++ preprocessor defines must be specified to identify the target platform.

Platform	CPP defines
Sun Solaris 2.5	`__sparc__ __sunos__ __OSVERSION__=5`
Digital Unix 3.2	`__alpha__ __osf1__ __OSVERSION__=3`
HPUX 10.x	`__hppa__ __hpux__ __OSVERSION__=10`
HPUX 11.x	`__hppa__ __hpux__ __OSVERSION__=11`
IBM AIX 4.x	`__aix__ __powerpc__ __OSVERSION__=4`
Linux 2.0 (x86)	`__x86__ __linux__ __OSVERSION__=2`
Linux 2.0 (alpha)	`__alpha__ __linux__ __OSVERSION__=2`
Linux 2.0 (powerpc)	`__powerpc__ __linux__ __OSVERSION__=2`
Windows/NT 3.5	`__x86__ __NT__ __OSVERSION__=3 __WIN32__`
Windows/NT 4.0	`__x86__ __NT__ __OSVERSION__=4 __WIN32__`
Windows/95	`__x86__ __WIN32__`
OpenVMS 6.x (alpha)	`__alpha__ __vms __OSVERSION__=6`
OpenVMS 6.x (vax)	`__vax__ __vms __OSVERSION__=6`
SGI Irix 6.x	`__mips__ __irix__ __OSVERSION__=6`
Reliant Unix 5.43	`__mips__ __SINIX__ __OSVERSION__=5`
ATMos 4.0	`__arm__ __atmos__ __OSVERSION__=4`
NextStep 3.x	`__m68k__ __nextstep__ __OSVERSION__=3`
Unixware 7	`__x86__ __uw7__ __OSVERSION__=5`

The preprocessor defines for new platform ports not listed above can be found in the corresponding platform configuration files. For instance, the platform configuration file for Sun Solaris 2.6 is in mk/platforms/sun4_sosV_5.6.mk. The preprocessor defines to identify a platform are in the make variable IMPORT_CPPFLAGS.

In a single source multi-target environment, you can put the preprocessor defines as the command-line arguments for the compiler. Alternately, you could create a sitedef.h file in the same directory as omniORB3/CORBA.h. Write into the file the appropriate set of preprocessor defines and add

#include <omniORB3/sitedef.h>

at the beginning of omniORB3/CORBA_sysdep.h.

1: Most of the 2.3 features have been implemented. The features still missing in this release are listed in section 1.1.4. Where possible, backward compatibility has been maintained up to specification 2.0.
2: More information can be found at http://www.opengroup.org/press/7jun99_b.htm