File: omniORB.html

package info (click to toggle)
omniorb-dfsg 4.1.6-2
links: PTS, VCS
area: main
in suites: jessie, jessie-kfreebsd, wheezy
size: 14,072 kB
ctags: 21,067
sloc: cpp: 109,772; ansic: 15,771; python: 14,158; sh: 2,754; yacc: 2,230; lex: 671; xml: 438; perl: 383; makefile: 88
file content (4178 lines) | stat: -rw-r--r-- 273,961 bytes
parent folder | download | duplicates (2)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>omniORB</TITLE>

<META http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<META name="GENERATOR" content="hevea 1.10">
<STYLE type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
DIV TABLE{margin-left:inherit;margin-right:inherit;}
PRE{text-align:left;margin-left:0ex;margin-right:auto;}
BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
TD P{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px;width:auto; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px;width:auto; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
.lstlisting{font-family:monospace;white-space:pre;margin-right:auto;margin-left:0pt;text-align:left}
</STYLE>
</HEAD>
<BODY >
<!--HEVEA command line is: hevea omniORB -->
<!--CUT DEF chapter 1 --><DIV CLASS="center"><P> <FONT SIZE=7>The omniORB version 4.1<BR>
User&#X2019;s Guide
</FONT></P><P> <FONT SIZE=5>Duncan Grisby<BR>
</FONT><FONT SIZE=3>(</FONT><FONT SIZE=3><I>email: </I></FONT><A HREF="mailto:dgrisby@apasphere.com"><FONT SIZE=3><I><FONT COLOR=purple>dgrisby@apasphere.com</FONT></I></FONT></A><FONT SIZE=3>)</FONT><FONT SIZE=5><BR>
Apasphere Ltd.<BR>
Sai-Lai Lo<BR>
David Riddoch<BR>
AT&amp;T Laboratories Cambridge<BR>
</FONT></P><P>July 2009
</P></DIV><P><FONT SIZE=5><B>Changes and Additions, July 2007</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Updates for omniORB 4.1.1.
</LI></UL><P><FONT SIZE=5><B>Changes and Additions, June 2005</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
New omniORB 4.1 features.
</LI></UL><P><FONT SIZE=5><B>Changes and Additions, October 2004</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Packaging stubs into DLLs.
</LI></UL><P><FONT SIZE=5><B>Changes and Additions, July 2004</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Minor updates.
</LI></UL><P><FONT SIZE=5><B>Changes and Additions, November 2002</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Per thread timeouts.
</LI><LI CLASS="li-itemize">Implement missing interceptors.
</LI><LI CLASS="li-itemize">Minor fixes.
</LI></UL><P><FONT SIZE=5><B>Changes and Additions, June 2002</B></FONT>
</P><UL CLASS="itemize"><LI CLASS="li-itemize">
Updated to omniORB 4.0.
</LI></UL><P><FONT SIZE=5><B>Contents</B></FONT></P><!--TOC chapter Introduction-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc1">Chapter&#XA0;1</A>&#XA0;&#XA0;Introduction</H1><!--SEC END --><P>omniORB is an Object Request Broker (ORB) that implements the 2.6
specification of the Common Object Request Broker Architecture
(CORBA)&#XA0;[<A HREF="#corba26-spec">OMG01</A>]<SUP><A NAME="text1" HREF="#note1">1</A></SUP>. It has
passed the Open Group CORBA compliant testsuite (for CORBA 2.1) and
was one of the three ORBs to be granted the CORBA brand in June
1999<SUP><A NAME="text2" HREF="#note2">2</A></SUP>.</P><P>This user guide tells you how to use omniORB to develop CORBA
applications. It assumes a basic understanding of CORBA.</P><P>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.</P><!--TOC section Features-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc2">1.1</A>&#XA0;&#XA0;Features</H2><!--SEC END --><!--TOC subsection Multithreading-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc3">1.1.1</A>&#XA0;&#XA0;Multithreading</H3><!--SEC END --><P>omniORB is fully multithreaded. To achieve low call overhead,
unnecessary call-multiplexing is eliminated. With the default
policies, there is at most one call in-flight in each communication
channel between two address spaces at any one time. To do this without
limiting the level of concurrency, new channels connecting the two
address spaces are created on demand and cached when there are
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. With GIOP 1.2, large
messages are fragmented, so the marshaller can start transmission
before it knows how large the entire message will be.</P><P>From version 4.0 onwards, omniORB also supports a flexible thread
pooling policy, and supports sending multiple interleaved calls on a
single connection. This policy leads to a small amount of additional
call overhead, compared to the default thread per connection model,
but allows omniORB to scale to extremely large numbers of concurrent
clients.</P><!--TOC subsection Portability-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc4">1.1.2</A>&#XA0;&#XA0;Portability</H3><!--SEC END --><P>omniORB has always been designed to be portable. It runs on many
flavours of Unix, Windows, several embedded operating systems, and
relatively obscure systems such as OpenVMS and Fujitsu-Siemens BS2000.
It is designed to be easy to port to new platforms. The IDL to C++
mapping for all target platforms is the same.</P><P>omniORB uses real C++ exceptions and nested classes. It keeps to the
CORBA specification&#X2019;s standard mapping as much as possible and does
not use the alternative mappings for C++ dialects. The only exception
is the mapping of IDL modules, which can use either namespaces or
nested classes.</P><P>omniORB relies on native thread libraries to provide multithreading
capability. A small class library (omnithread&#XA0;[<A HREF="#tjr96a">Ric96</A>]) is used
to encapsulate the 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.</P><!--TOC subsection Missing features-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc5">1.1.3</A>&#XA0;&#XA0;Missing features</H3><!--SEC END --><P>
<A NAME="sec:missing"></A></P><P>omniORB is not (yet) a complete implementation of the CORBA 2.6 core.
The following is a list of the most significant missing features.</P><UL CLASS="itemize"><LI CLASS="li-itemize">omniORB does not have its own Interface Repository. However, it
can act as a client to an IfR. The omniifr project
(<A HREF="http://omniifr.sourceforge.net/"><TT>http://omniifr.sourceforge.net/</TT></A>) aims to create an IfR for
omniORB.</LI><LI CLASS="li-itemize">omniORB supports interceptors, but not the standard Portable
Interceptor API.</LI></UL><P>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
(<A HREF="http://omniorb.sourceforge.net/"><TT>http://omniorb.sourceforge.net/</TT></A>).</P><!--TOC section Setting up your environment-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc6">1.2</A>&#XA0;&#XA0;Setting up your environment</H2><!--SEC END --><P>
<A NAME="sec:setup"></A></P><P>To get omniORB running, you first need to install omniORB according to
the instructions in the installation notes for your platform. Most
Unix platforms can use the Autoconf <TT>configure</TT> script to
automate the configuration process.</P><P>Once omniORB is installed in a suitable location, you must configure
it according to your required set-up. The configuration can be set
with a configuration file, environment variables, command-line
arguments or, on Windows, the Windows registry.</P><UL CLASS="itemize"><LI CLASS="li-itemize">On Unix platforms, the omniORB runtime looks for the environment
variable <TT>OMNIORB_CONFIG</TT>. 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 (by default <TT>/etc/omniORB.cfg</TT>).</LI><LI CLASS="li-itemize">On Win32 platforms (Windows NT, 2000, 95, 98), omniORB first
checks the environment variable <TT>OMNIORB_CONFIG</TT>&#XA0;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
<TT>HKEY_LOCAL_MACHINE\SOFTWARE\omniORB</TT>.</LI></UL><P>omniORB has a large number of parameters than can be configured. See
chapter&#XA0;<A HREF="#chap:config">4</A> for full details. The files
<TT>sample.cfg</TT> and <TT>sample.reg</TT> contain an example
configuration file and set of registry entries respectively.</P><P>To get all the omniORB examples running, the main thing you need to
configure is the Naming service, omniNames. To do that, the
configuration file or registry should contain an entry of the form</P><PRE CLASS="verbatim">  InitRef = NameService=corbaname::my.host.name
</PRE><P>See section&#XA0;<A HREF="#sec:corbaname">6.1.2</A> for full details of corbaname URIs.</P><!--TOC section Platform specific variables-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc7">1.3</A>&#XA0;&#XA0;Platform specific variables</H2><!--SEC END --><P>To compile omniORB programs correctly, several C++ preprocessor defines
<B>must</B> be specified to identify the target platform. On Unix
platforms where omniORB was configured with Autoconf, the
<TT>omniconfig.h</TT> file sets these for you. On other platforms, and
Unix platforms when Autoconf is not used, you must specify the
following defines:</P><DIV CLASS="flushleft">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1><TR><TD ALIGN=left NOWRAP>Platform</TD><TD ALIGN=left NOWRAP>CPP defines</TD></TR>
<TR><TD ALIGN=left NOWRAP>Windows NT 4.0,2000,XP</TD><TD ALIGN=left NOWRAP><CODE>__x86__     __NT__       __OSVERSION__=4  __WIN32__</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Windows NT 3.5</TD><TD ALIGN=left NOWRAP><CODE>__x86__     __NT__       __OSVERSION__=3  __WIN32__</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Windows 95</TD><TD ALIGN=left NOWRAP><CODE>__x86__     __WIN32__</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Sun Solaris 2.5</TD><TD ALIGN=left NOWRAP><CODE>__sparc__   __sunos__    __OSVERSION__=5</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
HPUX 10.x</TD><TD ALIGN=left NOWRAP><CODE>__hppa__    __hpux__     __OSVERSION__=10</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
HPUX 11.x</TD><TD ALIGN=left NOWRAP><CODE>__hppa__    __hpux__     __OSVERSION__=11</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
IBM AIX 4.x</TD><TD ALIGN=left NOWRAP><CODE>__aix__     __powerpc__  __OSVERSION__=4</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Digital Unix 3.2</TD><TD ALIGN=left NOWRAP><CODE>__alpha__   __osf1__     __OSVERSION__=3</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Linux 2.x (x86)</TD><TD ALIGN=left NOWRAP><CODE>__x86__     __linux__    __OSVERSION__=2</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Linux 2.x (powerpc)</TD><TD ALIGN=left NOWRAP><CODE>__powerpc__ __linux__    __OSVERSION__=2</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
OpenVMS 6.x (alpha)</TD><TD ALIGN=left NOWRAP><CODE>__alpha__   __vms        __OSVERSION__=6 </CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
OpenVMS 6.x (vax)</TD><TD ALIGN=left NOWRAP><CODE>__vax__     __vms        __OSVERSION__=6 </CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
SGI Irix 6.x</TD><TD ALIGN=left NOWRAP><CODE>__mips__    __irix__     __OSVERSION__=6 </CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Reliant Unix 5.43</TD><TD ALIGN=left NOWRAP><CODE>__mips__    __SINIX__    __OSVERSION__=5 </CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
ATMos 4.0</TD><TD ALIGN=left NOWRAP><CODE>__arm__     __atmos__    __OSVERSION__=4</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
NextStep 3.x</TD><TD ALIGN=left NOWRAP><CODE>__m68k__    __nextstep__ __OSVERSION__=3</CODE></TD></TR>
<TR><TD ALIGN=left NOWRAP>
Unixware 7</TD><TD ALIGN=left NOWRAP><CODE>__x86__     __uw7__      __OSVERSION__=5</CODE></TD></TR>
</TABLE>
</DIV><P>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
<TT>mk/platforms/sun4_sosV_5.6.mk</TT>. The preprocessor defines to
identify a platform are in the make variable
<TT>IMPORT_CPPFLAGS</TT>.</P><P>In a single source multi-target environment, you can put the
preprocessor defines as the command-line arguments for the compiler.
If you are building for a single platform, you can edit
include/omniconfig.h to add the definitions.</P><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note1" HREF="#text1">1</A></DT><DD CLASS="dd-thefootnotes">Most of the 2.6 features have
been implemented. The features still missing in this release are
listed in section&#XA0;<A HREF="#sec:missing">1.1.3</A>. Where possible, backward
compatibility has been maintained up to specification 2.0.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note2" HREF="#text2">2</A></DT><DD CLASS="dd-thefootnotes">More information can be found at
<A HREF="http://www.opengroup.org/press/7jun99_b.htm"><TT>http://www.opengroup.org/press/7jun99_b.htm</TT></A>
</DD></DL>
<!--END NOTES-->
<!--TOC chapter The Basics-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc8">Chapter&#XA0;2</A>&#XA0;&#XA0;The Basics</H1><!--SEC END --><P>
<A NAME="chap:basic"></A></P><P>In this chapter, we go through three examples to illustrate the
practical steps to use omniORB. By going through the source code of
each example, the essential concepts and APIs are introduced. If you
have no previous experience with using CORBA, you should study this
chapter in detail. There are pointers to other essential documents you
should be familiar with.</P><P>If you have experience with using other ORBs, you should still go
through this chapter because it provides important information about
the features and APIs that are necessarily omniORB specific. With the
Portable Object Adapter, there are very few omniORB specific details.</P><!--TOC section The Echo Object Example-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc9">2.1</A>&#XA0;&#XA0;The Echo Object Example</H2><!--SEC END --><P>Our example is an object which has only one method. The method simply
echos the argument string. We have to:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">define the object interface in IDL;
</LI><LI CLASS="li-enumerate">use the IDL compiler to generate the stub code<SUP><A NAME="text3" HREF="#note3">1</A></SUP>;
</LI><LI CLASS="li-enumerate">provide the <I>servant</I> object implementation;
</LI><LI CLASS="li-enumerate">write the client code.</LI></OL><P>These examples are in the <TT>src/examples/echo</TT> directory of the
omniORB distribution; there are several other examples one directory
above that in <TT>src/examples</TT>.</P><!--TOC section Specifying the Echo interface in IDL-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc10">2.2</A>&#XA0;&#XA0;Specifying the Echo interface in IDL</H2><!--SEC END --><P>We define an object interface, called <TT>Echo</TT>, as follows:</P><DIV CLASS="lstlisting"><B>interface</B> Echo {
    <B>string</B> echoString(<B>in</B> <B>string</B> mesg);
};</DIV><P>If you are new to IDL, you can learn about its syntax in Chapter 3 of
the CORBA 2.6 specification&#XA0;[<A HREF="#corba26-spec">OMG01</A>]. For the moment, you
only need to know that the interface consists of a single operation,
<TT>echoString()</TT>, which takes a string as an input argument and returns
a copy of the same string.</P><P>The interface is written in a file, called <TT>echo.idl</TT>. It is part
of the CORBA standard that all IDL files should have the extension
&#X2018;<TT>.idl</TT>&#X2019;, although omniORB does not enforce this.</P><P>For simplicity, the interface is defined in the global IDL namespace.
You should avoid this practice for the sake of object reusability. If
every CORBA developer defines their interfaces in the global IDL
namespace, there is a danger of name clashes between two independently
defined interfaces. Therefore, it is better to qualify your interfaces
by defining them inside <TT>module</TT> names. Of course, this does not
eliminate the chance of a name clash unless some form of naming
convention is agreed globally. Nevertheless, a well-chosen module name
can help a lot.</P><!--TOC section Generating the C++ stubs-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc11">2.3</A>&#XA0;&#XA0;Generating the C++ stubs</H2><!--SEC END --><P>From the IDL file, we use the IDL compiler to produce the C++ mapping
of the interface. The IDL compiler for omniORB is called omniidl.
Given the IDL file, omniidl produces two stub files: a C++ header file
and a C++ source file. For example, from the file <TT>echo.idl</TT>, the
following files are produced:</P><UL CLASS="itemize"><LI CLASS="li-itemize">
<TT>echo.hh</TT>
</LI><LI CLASS="li-itemize"><TT>echoSK.cc</TT>
</LI></UL><P>omniidl must be invoked with the <TT>-bcxx</TT> argument to
tell it to generate C++ stubs. The following command line generates
the stubs for <TT>echo.idl</TT>:</P><DIV CLASS="lstlisting">omniidl -bcxx echo.idl</DIV><P>If you are using our make environment (ODE), you don&#X2019;t need
to invoke omniidl explicitly. In the example file <TT>dir.mk</TT>, we
have the following line:</P><DIV CLASS="lstlisting">CORBA_INTERFACES = echo</DIV><P>That is all we need to instruct ODE to generate the stubs.
Remember, you won&#X2019;t find the stubs in your working directory because
all stubs are written into the <TT>stub</TT> directory at the top level
of your build tree.</P><P>The full arguments to omniidl are detailed in
chapter&#XA0;<A HREF="#chap:omniidl">5</A>.</P><!--TOC section Object References and Servants-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc12">2.4</A>&#XA0;&#XA0;Object References and Servants</H2><!--SEC END --><P>We contact a CORBA object through an <I>object reference</I>. The
actual implementation of a CORBA object is termed a <I>servant</I>.</P><P>Object references and servants are quite separate entities, and it is
important not to confuse the two. Client code deals purely with object
references, so there can be no confusion; object implementation code
must deal with both object references and servants. omniORB 4 uses
distinct C++ types for object references and servants, so the C++
compiler will complain if you use a servant when an object reference
is expected, or vice-versa.</P><DIV CLASS="minipage"><HR SIZE=2><DL CLASS="list"><DT CLASS="dt-list">

</DT><DD CLASS="dd-list">
<DIV CLASS="center"><B>Warning</B></DIV><P>omniORB 2.x <EM>did not</EM> use distinct types for object references
and servants, and often accepted a pointer to a servant when the CORBA
specification says it should only accept an object reference. If you
have code which relies on this, it will not compile with omniORB 3.x
or 4.x, even under the BOA compatibility mode.
</P></DD></DL><HR SIZE=2></DIV><!--TOC section A Quick Tour of the C++ stubs-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc13">2.5</A>&#XA0;&#XA0;A Quick Tour of the C++ stubs</H2><!--SEC END --><P>The C++ stubs conform to the standard mapping defined in the CORBA
specification&#XA0;[<A HREF="#cxxmapping">OMG03</A>]. It is important to understand the
mapping before you start writing any serious CORBA applications.
Before going any further, it is worth knowing what the mapping looks
like.</P><P>For the example interface <TT>Echo</TT>, the C++ mapping for its object
reference is <TT>Echo_ptr</TT>. The type is defined in <TT>echo.hh</TT>.
The relevant section of the code is reproduced below. The stub code
produced by other ORBs will be functionally equivalent to omniORB&#X2019;s,
but will almost certainly look very different.</P><DIV CLASS="lstlisting"><B>class</B> Echo;
<B>class</B> _objref_Echo;
<B>class</B> _impl_Echo;
<B>typedef</B> _objref_Echo* Echo_ptr;

<B>class</B> Echo {
<B>public</B>:
  <I>// Declarations for this interface type.</I>
  <B>typedef</B> Echo_ptr _ptr_type;
  <B>typedef</B> Echo_var _var_type;

  <B>static</B> _ptr_type _duplicate(_ptr_type);
  <B>static</B> _ptr_type _narrow(CORBA::Object_ptr);
  <B>static</B> _ptr_type _nil();

  <I>// ... methods generated for internal use</I>
};

<B>class</B> _objref_Echo :
  <B>public</B> <B>virtual</B> CORBA::Object, <B>public</B> <B>virtual</B> omniObjRef {
<B>public</B>:
  <B>char</B> * echoString(<B>const</B> <B>char</B>* mesg);

  <I>// ... methods generated for internal use</I>
};</DIV><P>In a compliant application, the operations defined in an object
interface should <B>only</B> be invoked via an object reference.
This is done by using arrow (&#X2018;<TT>-&gt;</TT>&#X2019;) on an object reference.
For example, the call to the operation <TT>echoString()</TT> would be
written as <TT>obj-&gt;echoString(mesg)</TT>.</P><P>It should be noted that the concrete type of an object reference is
opaque, i.e. you must not make any assumption about how an object
reference is implemented. In our example, even though <TT>Echo_ptr</TT>
is implemented as a pointer to the class <TT>_objref_Echo</TT>, it
should not be used as a C++ pointer, i.e. conversion to <TT>void*</TT>,
arithmetic operations, and relational operations including testing for
equality using <TT>operator==</TT>, must not be performed on the type.</P><P>In addition to class <TT>_objref_Echo</TT>, the mapping defines three
static member functions in the class <TT>Echo</TT>: <TT>_nil()</TT>,
<TT>_duplicate()</TT>, and <TT>_narrow()</TT>.</P><P>The <TT>_nil()</TT> function returns a nil object reference of the Echo
interface. The following call is guaranteed to return TRUE:</P><DIV CLASS="lstlisting">CORBA::Boolean true_result = CORBA::is_nil(Echo::_nil());</DIV><P>Remember, <TT>CORBA::is_nil()</TT> is the only compliant way to check if an
object reference is nil. You should not use the equality
<TT>operator==</TT>. Many C++ ORBs use the null pointer to represent a
nil object reference; <EM>omniORB does not</EM>.</P><P>The <TT>_duplicate()</TT> function returns a new object reference of the
<TT>Echo</TT> interface. The new object reference can be used
interchangeably with the old object reference to perform an operation
on the same object. Duplications are required to satisfy the C++
mapping&#X2019;s reference counting memory management.</P><P>All CORBA objects inherit from the generic object
<TT>CORBA::Object</TT>. <TT>CORBA::Object_ptr</TT> is the object
reference type for <TT>CORBA::Object</TT>. Any <TT>_ptr</TT> object
reference is therefore conceptually inherited from
<TT>CORBA::Object_ptr</TT>. In other words, an object reference such as
<TT>Echo_ptr</TT> can be used in places where a
<TT>CORBA::Object_ptr</TT> is expected.</P><P>The <TT>_narrow()</TT> function takes an argument of type
<TT>CORBA::Object_ptr</TT> and returns a new object reference of the
<TT>Echo</TT> interface. If the actual (runtime) type of the argument
object reference can be narrowed to <TT>Echo_ptr</TT>, <TT>_narrow()</TT>
will return a valid object reference. Otherwise it will return a nil
object reference. Note that <TT>_narrow()</TT> performs an implicit
duplication of the object reference, so the result must be released.
Note also that <TT>_narrow()</TT> may involve a remote call to check the
type of the object, so it may throw CORBA system exceptions such as
<TT>COMM_FAILURE</TT> or <TT>OBJECT_NOT_EXIST</TT>.</P><P>To indicate that an object reference will no longer be accessed, you
must call the <TT>CORBA::release()</TT> operation. Its signature is as
follows:</P><DIV CLASS="lstlisting"><B>namespace</B> CORBA {
  <B>void</B> release(CORBA::Object_ptr obj);
  ... <I>// other methods</I>
};</DIV><P>Once you have called <TT>CORBA::release()</TT> on an object reference, you
must no longer use that reference. This is because the associated
resources may have been deallocated. Notice that we are referring to
the resources associated with the object reference and <B>not the
servant object</B>. Servant objects are not affected by the lifetimes of
object references. In particular, servants are not deleted when all
references to them have been released&#X2014;CORBA does not perform
distributed garbage collection.</P><P>As described above, the equality <TT>operator==</TT> should not be used
on object references. To test if two object references are equivalent,
the member function <TT>_is_equivalent()</TT> of the generic object
<TT>CORBA::Object</TT> can be used. Here is an example of its usage:</P><DIV CLASS="lstlisting">Echo_ptr A;
...            <I>// initialise A to a valid object reference </I>
Echo_ptr B = A;
CORBA::Boolean true_result = A-&gt;_is_equivalent(B);
<I>// Note: the above call is guaranteed to be TRUE</I></DIV><P>You have now been introduced to most of the operations that can be
invoked via <TT>Echo_ptr</TT>. The generic object <TT>CORBA::Object</TT>
provides a few more operations and all of them can be invoked via
<TT>Echo_ptr</TT>. These operations deal mainly with CORBA&#X2019;s dynamic
interfaces. You do not have to understand them in order to use the C++
mapping provided via the stubs.</P><P>Since object references must be released explicitly, their usage is
prone to error and can lead to memory leakage. The mapping defines the
<I>object reference variable</I> type to make life easier. In our
example, the variable type <TT>Echo_var</TT> is defined<SUP><A NAME="text4" HREF="#note4">2</A></SUP>.</P><P>The <TT>Echo_var</TT> is more convenient to use because it will
automatically release its object reference when it is deallocated or
when assigned a new object reference. For many operations, mixing data
of type <TT>Echo_var</TT> and <TT>Echo_ptr</TT> is possible without any
explicit operations or castings<SUP><A NAME="text5" HREF="#note5">3</A></SUP>. For instance, the operation
<TT>echoString()</TT> can be called using the arrow (&#X2018;<TT>-&gt;</TT>&#X2019;) on a
<TT>Echo_var</TT>, as one can do with a <TT>Echo_ptr</TT>.</P><P>The usage of <TT>Echo_var</TT> is illustrated below:</P><DIV CLASS="lstlisting">Echo_var a;
Echo_ptr p = ... <I>// somehow obtain an object reference</I>

a = p;           <I>// a assumes ownership of p, must not use p any more</I>

Echo_var b = a;  <I>// implicit _duplicate</I>

p = ...          <I>// somehow obtain another object reference</I>

a = Echo::_duplicate(p);     <I>// release old object reference</I>
                             <I>// a now holds a copy of p.</I></DIV><!--TOC subsection Servant Object Implementation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc14">2.5.1</A>&#XA0;&#XA0;Servant Object Implementation</H3><!--SEC END --><P>
<A NAME="stubobjimpl"></A></P><P>Before the Portable Object Adapter (POA) specification, many of the
details of how servant objects should be implemented and registered
with the system were unspecified, so server-side code was not portable
between ORBs. The POA specification rectifies that. omniORB 4 still
supports the old omniORB 2.x BOA mapping, but you should always use
the POA mapping for new code. BOA code and POA code can coexist within
a single program. See section&#XA0;<A HREF="#sec:BOAcompat">3.1</A> for details of the
BOA compatibility, and problems you may encounter.</P><P>For each object interface, a <I>skeleton</I> class is generated. In
our example, the POA specification says that the skeleton class for
interface <TT>Echo</TT> is named <TT>POA_Echo</TT>. A servant
implementation can be written by creating an implementation class that
derives from the skeleton class.</P><P>The skeleton class <TT>POA_Echo</TT> is defined in <TT>echo.hh</TT>. The
relevant section of the code is reproduced below.</P><DIV CLASS="lstlisting"><B>class</B> POA_Echo :
  <B>public</B> <B>virtual</B> PortableServer::ServantBase
{
<B>public</B>:
  Echo_ptr _this();

  <B>virtual</B> <B>char</B> * echoString(<B>const</B> <B>char</B>*  mesg) = 0;
  <I>// ...</I>
};</DIV><P>The code fragment shows the only member functions that can be used in
the object implementation code. Other member functions are generated
for internal use only. As with the code generated for object
references, other POA-based ORBs will generate code which looks
different, but is functionally equivalent to this.</P><DL CLASS="description"><DT CLASS="dt-description"><B><TT>echoString()</TT></B></DT><DD CLASS="dd-description"><BR>
It is through this abstract function that an implementation class
provides the implementation of the <TT>echoString()</TT> operation. Notice
that its signature is the same as the <TT>echoString()</TT> function that
can be invoked via the <TT>Echo_ptr</TT> object reference.</DD><DT CLASS="dt-description"><B><TT>_this()</TT></B></DT><DD CLASS="dd-description"><BR>
This function returns an object reference for the target object,
provided the POA policies permit it. The returned value must be
deallocated via <TT>CORBA::release()</TT>. See section&#XA0;<A HREF="#objeg1">2.8</A>
for an example of how this function is used.</DD></DL><!--TOC section Writing the servant implementation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc15">2.6</A>&#XA0;&#XA0;Writing the servant implementation</H2><!--SEC END --><P>
<A NAME="objimpl"></A></P><P>You define an implementation class to provide the servant
implementation. There is little constraint on how you design your
implementation class except that it has to inherit from the stubs&#X2019;
skeleton class and to implement all the abstract functions defined in
the skeleton class. Each of these abstract functions corresponds to an
operation of the interface. They are the hooks for the ORB to perform
upcalls to your implementation.</P><P>Here is a simple implementation of the Echo object.</P><DIV CLASS="lstlisting"><B>class</B> Echo_i : <B>public</B> POA_Echo
{
<B>public</B>:
  <B>inline</B> Echo_i() {}
  <B>virtual</B> ~Echo_i() {}
  <B>virtual</B> <B>char</B>* echoString(<B>const</B> <B>char</B>* mesg);
};

<B>char</B>* Echo_i::echoString(<B>const</B> <B>char</B>* mesg)
{
  <B>return</B> CORBA::string_dup(mesg);
}</DIV><P>There are four points to note here:</P><DL CLASS="description"><DT CLASS="dt-description"><B>Storage Responsibilities</B></DT><DD CLASS="dd-description"><BR>
A string, which is used both as an in argument and the return value of
<TT>echoString()</TT>, is a variable size data type. Other examples of
variable size data types include sequences, type &#X2018;any&#X2019;, etc. For these
data types, you must be clear about whose responsibility it is to
allocate and release the associated storage. As a rule of thumb, the
client (or the caller to the implementation functions) owns the
storage of all IN arguments, the object implementation (or the callee)
must copy the data if it wants to retain a copy. For OUT arguments and
return values, the object implementation allocates the storage and
passes the ownership to the client. The client must release the
storage when the variables will no longer be used. For details,
please refer to the C++ mapping specification.</DD><DT CLASS="dt-description"><B>Multi-threading</B></DT><DD CLASS="dd-description"><BR>
As omniORB is fully multithreaded, multiple threads may perform the
same upcall to your implementation concurrently. It is up to your
implementation to synchronise the threads&#X2019; accesses to shared data.
In our simple example, we have no shared data to protect so no thread
synchronisation is necessary.<P>Alternatively, you can create a POA which has the
<TT>SINGLE_THREAD_MODEL</TT> Thread Policy. This guarantees that all
calls to that POA are processed sequentially.</P></DD><DT CLASS="dt-description"><B>Reference Counting</B></DT><DD CLASS="dd-description"><BR>
All servant objects are reference counted. The base
<TT>PortableServer::ServantBase</TT> class from which all servant
skeleton classes derive defines member functions named <TT>_add_ref()</TT>
and <TT>_remove_ref()</TT><SUP><A NAME="text6" HREF="#note6">4</A></SUP>. The reference
counting means that an <TT>Echo_i</TT> instance will be deleted when no
more references to it are held by application code or the POA
itself. Note that this is totally separate from the reference counting
which is associated with object references&#X2014;a servant object is
<EM>never</EM> deleted due to a CORBA object reference being released.</DD><DT CLASS="dt-description"><B>Instantiation</B></DT><DD CLASS="dd-description"><BR>
Servants are usually instantiated on the heap, i.e. using the
<TT>new</TT> operator. However, they can also be created on the stack as
automatic variables. If you do that, it is vital to make sure that the
servant has been deactivated, and thus released by the POA, before the
variable goes out of scope and is destroyed.</DD></DL><!--TOC section Writing the client-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc16">2.7</A>&#XA0;&#XA0;Writing the client</H2><!--SEC END --><P>Here is an example of how an <TT>Echo_ptr</TT> object reference is
used.</P><DIV CLASS="lstlisting"><FONT SIZE=1>   1</FONT> <B>void</B>
<FONT SIZE=1>   2</FONT> hello(CORBA::Object_ptr obj)
<FONT SIZE=1>   3</FONT> {
<FONT SIZE=1>   4</FONT>   Echo_var e = Echo::_narrow(obj);
<FONT SIZE=1>   5</FONT> 
<FONT SIZE=1>   6</FONT>   <B>if</B> (CORBA::is_nil(e)) {
<FONT SIZE=1>   7</FONT>     cerr &lt;&lt; "cannot invoke on a nil object reference."
<FONT SIZE=1>   8</FONT>          &lt;&lt; endl;
<FONT SIZE=1>   9</FONT>     <B>return</B>;
<FONT SIZE=1>  10</FONT>   }
<FONT SIZE=1>  11</FONT> 
<FONT SIZE=1>  12</FONT>   CORBA::String_var src = (<B>const</B> <B>char</B>*) "Hello!";
<FONT SIZE=1>  13</FONT>   CORBA::String_var dest;
<FONT SIZE=1>  14</FONT> 
<FONT SIZE=1>  15</FONT>   dest = e-&gt;echoString(src);
<FONT SIZE=1>  16</FONT> 
<FONT SIZE=1>  17</FONT>   cerr &lt;&lt; "I said,\"" &lt;&lt; src &lt;&lt; "\"."
<FONT SIZE=1>  18</FONT>        &lt;&lt; " The Object said,\"" &lt;&lt; dest &lt;&lt;"\"" &lt;&lt; endl;
<FONT SIZE=1>  19</FONT> }</DIV><P>Briefly, the <TT>hello()</TT> function accepts a generic object reference.
The object reference (<TT>obj</TT>) is narrowed to <TT>Echo_ptr</TT>. If
the object reference returned by <TT>Echo::_narrow()</TT> is not nil, the
operation <TT>echoString()</TT> is invoked. Finally, both the argument to
and the return value of <TT>echoString()</TT> are printed to <TT>cerr</TT>.</P><P>The example also illustrates how <TT>T_var</TT> types are used. As was
explained in the previous section, <TT>T_var</TT> types take care of
storage allocation and release automatically when variables are
reassigned or when the variables go out of scope.</P><P>In line 4, the variable <TT>e</TT> takes over the storage responsibility
of the object reference returned by <TT>Echo::_narrow()</TT>. The object
reference is released by the destructor of <TT>e</TT>. It is called
automatically when the function returns. Lines 6 and 15 show how a
<TT>Echo_var</TT> variable is used. As explained earlier, the
<TT>Echo_var</TT> type can be used interchangeably with the
<TT>Echo_ptr</TT> type.</P><P>The argument and the return value of <TT>echoString()</TT> are stored in
<TT>CORBA::String_var</TT> variables <TT>src</TT> and <TT>dest</TT>
respectively. The strings managed by the variables are deallocated by
the destructor of <TT>CORBA::String_var</TT>. It is called
automatically when the variable goes out of scope (as the function
returns). Line 15 shows how <TT>CORBA::String_var</TT> variables are
used. They can be used in place of a string (for which the mapping is
<TT>char*</TT>)<SUP><A NAME="text7" HREF="#note7">5</A></SUP>. As used in line 12, assigning a constant string
(<TT>const char*</TT>) to a <TT>CORBA::String_var</TT> causes the string
to be copied. On the other hand, assigning a <TT>char*</TT> to a
<TT>CORBA::String_var</TT>, as used in line 15, causes the latter to
assume the ownership of the string<SUP><A NAME="text8" HREF="#note8">6</A></SUP>.</P><P>Under the C++ mapping, <TT>T_var</TT> types are provided for all the
non-basic data types. It is obvious that one should use automatic
variables whenever possible both to avoid memory leaks and to maximise
performance. However, when one has to allocate data items on the heap,
it is a good practice to use the <TT>T_var</TT> types to manage the
heap storage.</P><!--TOC section Example 1 &#X2014; Colocated Client and Implementation-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc17">2.8</A>&#XA0;&#XA0;Example 1 &#X2014; Colocated Client and Implementation</H2><!--SEC END --><P>
<A NAME="objeg1"></A></P><P>Having introduced the client and the object implementation, we can now
describe how to link up the two via the ORB and POA. In this section,
we describe an example in which both the client and the object
implementation are in the same address space. In the next two
sections, we shall describe the case where the two are in different
address spaces.</P><P>The code for this example is reproduced below:</P><DIV CLASS="lstlisting"><FONT SIZE=1>   1</FONT> <B>int</B>
<FONT SIZE=1>   2</FONT> main(<B>int</B> argc, <B>char</B> **argv)
<FONT SIZE=1>   3</FONT> {
<FONT SIZE=1>   4</FONT>   CORBA::ORB_ptr orb = CORBA::ORB_init(argc,argv,"omniORB4");
<FONT SIZE=1>   5</FONT> 
<FONT SIZE=1>   6</FONT>   CORBA::Object_var       obj = orb-&gt;resolve_initial_references("RootPOA");
<FONT SIZE=1>   7</FONT>   PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);
<FONT SIZE=1>   8</FONT> 
<FONT SIZE=1>   9</FONT>   Echo_i *myecho = <B>new</B> Echo_i();
<FONT SIZE=1>  10</FONT>   PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(myecho);
<FONT SIZE=1>  11</FONT> 
<FONT SIZE=1>  12</FONT>   Echo_var myechoref = myecho-&gt;_this();
<FONT SIZE=1>  13</FONT>   myecho-&gt;_remove_ref();
<FONT SIZE=1>  14</FONT> 
<FONT SIZE=1>  15</FONT>   PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
<FONT SIZE=1>  16</FONT>   pman-&gt;activate();
<FONT SIZE=1>  17</FONT> 
<FONT SIZE=1>  18</FONT>   hello(myechoref);
<FONT SIZE=1>  19</FONT> 
<FONT SIZE=1>  20</FONT>   orb-&gt;destroy();
<FONT SIZE=1>  21</FONT>   <B>return</B> 0;
<FONT SIZE=1>  22</FONT> }</DIV><P>The example illustrates several important interactions among the ORB,
the POA, the servant, and the client. Here are the details:</P><!--TOC subsection ORB initialisation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc18">2.8.1</A>&#XA0;&#XA0;ORB initialisation</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Line 4</B></DT><DD CLASS="dd-description"><BR>
The ORB is initialised by calling the <TT>CORBA::ORB_init()</TT>
function. The function uses the optional 3rd argument to determine
which ORB should be returned. Unless you are using omniORB specific
features, it is usually best to leave it out, and get the default
ORB. To explicitly ask for omniORB 4.x, this argument must be
&#X2018;omniORB4&#X2019;<SUP><A NAME="text9" HREF="#note9">7</A></SUP>.<P><TT>CORBA::ORB_init()</TT> takes the list of command line arguments and
processes any that start &#X2018;<TT>-ORB</TT>&#X2019;. It removes these arguments
from the list, so application code does not have to deal with them.</P><P>If any error occurs during ORB initialisation, such as invalid ORB
arguments, or an invalid configuration file, the
<TT>CORBA::INITIALIZE</TT> system exception is raised.</P></DD></DL><!--TOC subsection Obtaining the Root POA-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc19">2.8.2</A>&#XA0;&#XA0;Obtaining the Root POA</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Lines 6&#X2013;7</B></DT><DD CLASS="dd-description"><BR>
To activate our servant object and make it available to clients, we
must register it with a POA. In this example, we use the <I>Root
POA</I>, rather than creating any child POAs. The Root POA is found with
<TT>orb-&gt;resolve_initial_references()</TT>, which returns a plain
<TT>CORBA::Object</TT>. In line 7, we narrow the reference to the right
type for a POA.<P>A POA&#X2019;s behaviour is governed by its <I>policies</I>. The Root POA has
suitable policies for many simple servers, and closely matches the
&#X2018;policies&#X2019; used by omniORB 2&#X2019;s BOA. See Chapter 11 of the CORBA 2.6
specification[<A HREF="#corba26-spec">OMG01</A>] for details of all the POA policies
which are available.</P></DD></DL><!--TOC subsection Object initialisation-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc20">2.8.3</A>&#XA0;&#XA0;Object initialisation</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Line 9</B></DT><DD CLASS="dd-description"><BR>
An instance of the Echo servant is initialised using the <TT>new</TT>
operator.</DD><DT CLASS="dt-description"><B>Line 10</B></DT><DD CLASS="dd-description"><BR>
The servant object is activated in the Root POA using
<TT>poa-&gt;activate_object()</TT>, which returns an object identifier
(of type <TT>PortableServer::ObjectId*</TT>). The object id must
be passed back to various POA operations. The caller is responsible
for freeing the object id, so it is assigned to a <TT>_var</TT> type.</DD><DT CLASS="dt-description"><B>Line 12</B></DT><DD CLASS="dd-description"><BR>
The object reference is obtained from the servant object by calling
<TT>_this()</TT>. Like all object references, the return value of
<TT>_this()</TT> must be released by <TT>CORBA::release()</TT> when it is no
longer needed. In this case, we assign it to a <TT>_var</TT> type, so
the release is implicit at the end of the function.<P>One of the important characteristics of an object reference is that it
is completely location transparent. A client can invoke on the object
using its object reference without any need to know whether the
servant object is colocated in the same address space or is in a
different address space.</P><P>In the case of colocated client and servant, omniORB is able to
short-circuit the client calls so they do not involve IIOP. The calls
still go through the POA, however, so the various POA policies affect
local calls in the same way as remote ones. This optimisation is
applicable not only to object references returned by <TT>_this()</TT>, but
to any object references that are passed around within the same
address space or received from other address spaces via remote calls.</P></DD><DT CLASS="dt-description"><B>Line 13</B></DT><DD CLASS="dd-description"><BR>
The server code releases the reference it holds to the servant
object. The only reference to that object is now held by the POA (it
gained the reference on the call to <TT>activate_object()</TT>), so when
the object is deactivated (or the POA is destroyed), the servant
object will be deleted automatically. After this point, the code must
no longer use the <TT>myecho</TT> pointer.</DD></DL><!--TOC subsection Activating the POA-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc21">2.8.4</A>&#XA0;&#XA0;Activating the POA</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Lines 15&#X2013;16</B></DT><DD CLASS="dd-description"><BR>
POAs are initially in the <I>holding</I> state, meaning that incoming
requests are blocked. Lines 15 and 16 acquire a reference to the POA&#X2019;s
POA manager, and use it to put the POA into the <I>active</I> state.
Incoming requests are now served. <B>Failing to activate the POA
is one of the most common programming mistakes. If your program
appears deadlocked, make sure you activated the POA!</B></DD></DL><!--TOC subsection Performing a call-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc22">2.8.5</A>&#XA0;&#XA0;Performing a call</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Line 18</B></DT><DD CLASS="dd-description"><BR>
At long last, we can call <TT>hello()</TT> with this object reference. The
argument is widened implicitly to the generic object reference
<TT>CORBA::Object_ptr</TT>.</DD></DL><!--TOC subsection ORB destruction-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc23">2.8.6</A>&#XA0;&#XA0;ORB destruction</H3><!--SEC END --><DL CLASS="description"><DT CLASS="dt-description"><B>Line 20</B></DT><DD CLASS="dd-description"><BR>
Shutdown the ORB permanently. This call causes the ORB to release all
its resources, e.g. internal threads, and also to deactivate any
servant objects which are currently active. When it deactivates the
<TT>Echo_i</TT> instance, the servant&#X2019;s reference count drops to zero,
so the servant is deleted.<P>This call is particularly important when writing a CORBA DLL on
Windows NT that is to be used from ActiveX. If this call is absent,
the application will hang when the CORBA DLL is unloaded.</P></DD></DL><!--TOC section Example 2 &#X2014; Different Address Spaces-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc24">2.9</A>&#XA0;&#XA0;Example 2 &#X2014; Different Address Spaces</H2><!--SEC END --><P>In this example, the client and the object implementation reside in
two different address spaces. The code of this example is almost the
same as the previous example. The only difference is the extra work
which needs to be done to pass the object reference from the object
implementation to the client.</P><P>The simplest (and quite primitive) way to pass an object reference
between two address spaces is to produce a <I>stringified</I> version
of the object reference and to pass this string to the client as a
command-line argument. The string is then converted by the client
into a proper object reference. This method is used in this
example. In the next example, we shall introduce a better way of
passing the object reference using the CORBA Naming Service.</P><!--TOC subsection Object Implementation: Making a Stringified Object Reference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc25">2.9.1</A>&#XA0;&#XA0;Object Implementation: Making a Stringified Object Reference</H3><!--SEC END --><P>The <TT>main()</TT> function of the server side is reproduced below. The
full listing (<TT>eg2_impl.cc</TT>) can be found at the end of this
chapter.</P><DIV CLASS="lstlisting"><FONT SIZE=1>   1</FONT> <B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
<FONT SIZE=1>   2</FONT> {
<FONT SIZE=1>   3</FONT>   CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);
<FONT SIZE=1>   4</FONT> 
<FONT SIZE=1>   5</FONT>   CORBA::Object_var       obj = orb-&gt;resolve_initial_references("RootPOA");
<FONT SIZE=1>   6</FONT>   PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);
<FONT SIZE=1>   7</FONT> 
<FONT SIZE=1>   8</FONT>   Echo_i* myecho = <B>new</B> Echo_i();
<FONT SIZE=1>   9</FONT> 
<FONT SIZE=1>  10</FONT>   PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(myecho);
<FONT SIZE=1>  11</FONT> 
<FONT SIZE=1>  12</FONT>   obj = myecho-&gt;_this();
<FONT SIZE=1>  13</FONT>   CORBA::String_var sior(orb-&gt;object_to_string(obj));
<FONT SIZE=1>  14</FONT>   cerr &lt;&lt; (<B>char</B>*)sior &lt;&lt; endl;
<FONT SIZE=1>  15</FONT> 
<FONT SIZE=1>  16</FONT>   myecho-&gt;_remove_ref();
<FONT SIZE=1>  17</FONT> 
<FONT SIZE=1>  18</FONT>   PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
<FONT SIZE=1>  19</FONT>   pman-&gt;activate();
<FONT SIZE=1>  20</FONT> 
<FONT SIZE=1>  21</FONT>   orb-&gt;run();
<FONT SIZE=1>  22</FONT>   orb-&gt;destroy();
<FONT SIZE=1>  23</FONT>   <B>return</B> 0;
<FONT SIZE=1>  24</FONT> }</DIV><P>The stringified object reference is obtained by calling the ORB&#X2019;s
<TT>object_to_string()</TT> function (line 13). This results in a
string starting with the signature &#X2018;IOR:&#X2019; and followed by some
hexadecimal digits. All CORBA 2 compliant ORBs are able to convert the
string into its internal representation of a so-called Interoperable
Object Reference (IOR). The IOR contains the location information and
a key to uniquely identify the object implementation in its own
address space. From the IOR, an object reference can be constructed.</P><!--TOC subsection Client: Using a Stringified Object Reference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc26">2.9.2</A>&#XA0;&#XA0;Client: Using a Stringified Object Reference</H3><!--SEC END --><P>
<A NAME="clnt2"></A></P><P>The stringified object reference is passed to the client as a
command-line argument. The client uses the ORB&#X2019;s
<TT>string_to_object()</TT> function to convert the string into a generic
object reference (<TT>CORBA::Object_ptr</TT>). The relevant section of
the code is reproduced below. The full listing (<TT>eg2_clt.cc</TT>) can
be found at the end of this chapter.</P><DIV CLASS="lstlisting"><B>try</B> {
  CORBA::Object_var obj = orb-&gt;string_to_object(argv[1]);
  hello(obj);
}
<B>catch</B>(CORBA::TRANSIENT&amp;) {
  ... <I>// code to handle transient exception...</I>
}</DIV><!--TOC subsection Catching System Exceptions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc27">2.9.3</A>&#XA0;&#XA0;Catching System Exceptions</H3><!--SEC END --><P>When omniORB detects an error condition, it may raise a system
exception. The CORBA specification defines a series of exceptions
covering most of the error conditions that an ORB may encounter. The
client may choose to catch these exceptions and recover from the error
condition<SUP><A NAME="text10" HREF="#note10">8</A></SUP>. For instance, the code fragment, shown in
section&#XA0;<A HREF="#clnt2">2.9.2</A>, catches the <TT>TRANSIENT</TT> system exception
which indicates that the object could not be contacted at the time of
the call, usually meaning the server is not running.</P><P>All system exceptions inherit from <TT>CORBA::SystemException</TT>. With
compilers that properly support RTTI<SUP><A NAME="text11" HREF="#note11">9</A></SUP>, a single catch of <TT>CORBA::SystemException</TT> will
catch all the different system exceptions thrown by omniORB.</P><P>When omniORB detects an internal error such as corrupt data or invalid
conditions, it raises the exception <TT>omniORB::fatalException</TT>.
When this exception is raised, it is not sensible to proceed with any
operation that involves the ORB&#X2019;s runtime. It is best to exit the
program immediately. The exception structure carried by
<TT>omniORB::fatalException</TT> contains the exact location (the file
name and the line number) where the exception is raised. In most
cases, <TT>fatalException</TT>s occur due to incorrect behaviour by the
application code, but they may be caused by bugs in omniORB.</P><!--TOC subsection Lifetime of a CORBA object-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc28">2.9.4</A>&#XA0;&#XA0;Lifetime of a CORBA object</H3><!--SEC END --><P>CORBA objects are either <I>transient</I> or <I>persistent</I>. The
majority are transient, meaning that the lifetime of the CORBA object
(as contacted through an object reference) is the same as the lifetime
of its servant object. Persistent objects can live beyond the
destruction of their servant object, the POA they were created in, and
even their process. Persistent objects are, of course, only
contactable when their associated servants are active, or can be
activated by their POA with a servant manager<SUP><A NAME="text12" HREF="#note12">10</A></SUP>. A reference to
a persistent object can be published, and will remain valid even if
the server process is restarted.</P><P>A POA&#X2019;s Lifespan Policy determines whether objects created within it
are transient or persistent. The Root POA has the <TT>TRANSIENT</TT>
policy.</P><P>An alternative to creating persistent objects is to register object
references in a <I>naming service</I> and bind them to fixed path
names. Clients can bind to the object implementations at run time by
asking the naming service to resolve the path names to the object
references. CORBA defines a standard naming service, which is a
component of the Common Object Services (COS)&#XA0;[<A HREF="#corbaservices">OMG98</A>],
that can be used for this purpose. The next section describes an
example of how to use the COS Naming Service.</P><!--TOC section Example 3 &#X2014; Using the Naming Service-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc29">2.10</A>&#XA0;&#XA0;Example 3 &#X2014; Using the Naming Service</H2><!--SEC END --><P>In this example, the object implementation uses the Naming
Service&#XA0;[<A HREF="#corbaservices">OMG98</A>] to pass on the object reference to the
client. This method is far more practical than using stringified
object references. The full listing of the object implementation
(<TT>eg3_impl.cc</TT>) and the client (<TT>eg3_clt.cc</TT>) can be found
at the end of this chapter.</P><P>The names used by the Naming service consist of a sequence of
<I>name components</I>. Each name component has an <I>id</I> and a
<I>kind</I> field, both of which are strings. All name components
except the last one are bound to a naming context. A naming context is
analogous to a directory in a filing system: it can contain names of
object references or other naming contexts. The last name component is
bound to an object reference.</P><P>Sequences of name components can be represented as a flat string,
using &#X2018;.&#X2019; to separate the id and kind fields, and &#X2018;/&#X2019; to separate name
components from each other<SUP><A NAME="text13" HREF="#note13">11</A></SUP>. In our example, the Echo object
reference is bound to the stringified name
&#X2018;<TT>test.my_context/Echo.Object</TT>&#X2019;.</P><P>The kind field is intended to describe the name in a
syntax-independent way. The naming service does not interpret, assign,
or manage these values. However, both the name and the kind attribute
must match for a name lookup to succeed. In this example, the kind
values for <TT>test</TT> and <TT>Echo</TT> are chosen to be
&#X2018;<TT>my_context</TT>&#X2019; and &#X2018;<TT>Object</TT>&#X2019; respectively. This is an
arbitrary choice as there is no standardised set of kind values.</P><!--TOC subsection Obtaining the Root Context Object Reference-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc30">2.10.1</A>&#XA0;&#XA0;Obtaining the Root Context Object Reference</H3><!--SEC END --><P>
<A NAME="resolveinit"></A></P><P>The initial contact with the Naming Service can be established via the
<I>root</I> context. The object reference to the root context is
provided by the ORB and can be obtained by calling
<TT>resolve_initial_references()</TT>. The following code fragment shows
how it is used:</P><DIV CLASS="lstlisting">CORBA::ORB_ptr orb = CORBA::ORB_init(argc,argv);

CORBA::Object_var initServ;
initServ = orb-&gt;resolve_initial_references("NameService");

CosNaming::NamingContext_var rootContext;
rootContext = CosNaming::NamingContext::_narrow(initServ);</DIV><P>Remember, omniORB constructs its internal list of initial references
at initialisation time using the information provided in the
configuration file <TT>omniORB.cfg</TT>, or given on the command
line. If this file is not present, the internal list will be empty and
<TT>resolve_initial_references()</TT> will raise a
<TT>CORBA::ORB::InvalidName</TT> exception.</P><!--TOC subsection The Naming Service Interface-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc31">2.10.2</A>&#XA0;&#XA0;The Naming Service Interface</H3><!--SEC END --><P>It is beyond the scope of this chapter to describe in detail the
Naming Service interface. You should consult the CORBA services
specification&#XA0;[<A HREF="#corbaservices">OMG98</A>] (chapter 3). The code listed in
<TT>eg3_impl.cc</TT> and <TT>eg3_clt.cc</TT> are good examples of how the
service can be used. Please spend time to study the examples
carefully.</P><!--TOC section Example 4 &#X2014; Using tie implementation templates-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc32">2.11</A>&#XA0;&#XA0;Example 4 &#X2014; Using tie implementation templates</H2><!--SEC END --><P>omniORB supports <I>tie</I> implementation templates as an alternative
way of providing servant classes. If you use the <TT>-Wbtp</TT> option
to omniidl, it generates an extra template class for each interface.
This template class can be used to tie a C++ class to the skeleton
class of the interface.</P><P>The source code in <TT>eg3_tieimpl.cc</TT> at the end of this chapter
illustrates how the template class can be used. The code is almost
identical to <TT>eg3_impl.cc</TT> with only a few changes.</P><P>Firstly, the servant class <TT>Echo_i</TT> does not inherit from any
stub classes. This is the main benefit of using the template class
because there are applications in which it is difficult to require
every servant class to derive from CORBA classes.</P><P>Secondly, the instantiation of a CORBA object now involves creating an
instance of the implementation class <EM>and</EM> an instance of the
template. Here is the relevant code fragment:</P><DIV CLASS="lstlisting"><B>class</B> Echo_i { ... };

Echo_i *myimpl = <B>new</B> Echo_i();
POA_Echo_tie&lt;Echo_i&gt; myecho(myimpl);

PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(&amp;myecho);</DIV><P>For interface <TT>Echo</TT>, the name of its tie implementation template
is <TT>POA_Echo_tie</TT>. The template parameter is the servant
class that contains an implementation of each of the operations
defined in the interface. As used above, the tie template takes
ownership of the <TT>Echo_i</TT> instance, and deletes it when the tie
object goes out of scope. The tie constructor has an optional boolean
argument (defaulted to true) which indicates whether or not it should
delete the servant object. For full details of using tie templates,
see the CORBA C++ mapping specification.</P><!--TOC section Source Listings-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc33">2.12</A>&#XA0;&#XA0;Source Listings</H2><!--SEC END --><!--TOC subsection eg1.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc34">2.12.1</A>&#XA0;&#XA0;eg1.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg1.cc - This is the source code of example 1 used in Chapter 2</I>
<I>//          "The Basics" of the omniORB user guide.</I>
<I>//</I>
<I>//          In this example, both the object implementation and the</I>
<I>//          client are in the same process.</I>
<I>//</I>
<I>// Usage: eg1</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<I>// This is the object implementation.</I>

<B>class</B> Echo_i : <B>public</B> POA_Echo
{
<B>public</B>:
  <B>inline</B> Echo_i() {}
  <B>virtual</B> ~Echo_i() {}
  <B>virtual</B> <B>char</B>* echoString(<B>const</B> <B>char</B>* mesg);
};


<B>char</B>* Echo_i::echoString(<B>const</B> <B>char</B>* mesg)
{
  <B>return</B> CORBA::string_dup(mesg);
}


<I>//////////////////////////////////////////////////////////////////////</I>

<I>// This function acts as a client to the object.</I>

<B>static</B> <B>void</B> hello(Echo_ptr e)
{
  <B>if</B>( CORBA::is_nil(e) ) {
    cerr &lt;&lt; "hello: The object reference is nil!\n" &lt;&lt; endl;
    <B>return</B>;
  }

  CORBA::String_var src = (<B>const</B> <B>char</B>*) "Hello!";
  <I>// String literals are (char*) rather than (const char*) on some</I>
  <I>// old compilers.  Thus it is essential to cast to (const char*)</I>
  <I>// here to ensure that the string is copied, so that the</I>
  <I>// CORBA::String_var does not attempt to 'delete' the string</I>
  <I>// literal.</I>

  CORBA::String_var dest = e-&gt;echoString(src);

  cout &lt;&lt; "I said, \"" &lt;&lt; (<B>char</B>*)src &lt;&lt; "\"." &lt;&lt; endl
       &lt;&lt; "The Echo object replied, \"" &lt;&lt; (<B>char</B>*)dest &lt;&lt;"\"." &lt;&lt; endl;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{


  <B>try</B> {
    <I>// Initialise the ORB.</I>
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    <I>// Obtain a reference to the root POA.</I>
    CORBA::Object_var obj = orb-&gt;resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

      <I>// We allocate the object on the heap.  Since this is a reference</I>
      <I>// counted object, it will be deleted by the POA when it is no</I>
      <I>// longer needed.</I>
    Echo_i* myecho = <B>new</B> Echo_i();

    <I>// Activate the object.  This tells the POA that this object is</I>
    <I>// ready to accept requests.</I>
    PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(myecho);

      <I>// Obtain a reference to the object.</I>
    Echo_var myechoref = myecho-&gt;_this();

    <I>// Decrement the reference count of the object implementation, so</I>
    <I>// that it will be properly cleaned up when the POA has determined</I>
    <I>// that it is no longer needed.</I>
    myecho-&gt;_remove_ref();

    <I>// Obtain a POAManager, and tell the POA to start accepting</I>
    <I>// requests on its objects.</I>
    PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
    pman-&gt;activate();

    <I>// Do the client-side call.</I>
    hello(myechoref);

    <I>// Clean up all the resources.</I>
    orb-&gt;destroy();
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}</DIV><!--TOC subsection eg2_impl.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc35">2.12.2</A>&#XA0;&#XA0;eg2_impl.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg2_impl.cc - This is the source code of example 2 used in Chapter 2</I>
<I>//               "The Basics" of the omniORB user guide.</I>
<I>//</I>
<I>//               This is the object implementation.</I>
<I>//</I>
<I>// Usage: eg2_impl</I>
<I>//</I>
<I>//        On startup, the object reference is printed to cerr as a</I>
<I>//        stringified IOR. This string should be used as the argument to </I>
<I>//        eg2_clt.</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<B>class</B> Echo_i : <B>public</B> POA_Echo
{
<B>public</B>:
  <B>inline</B> Echo_i() {}
  <B>virtual</B> ~Echo_i() {}
  <B>virtual</B> <B>char</B>* echoString(<B>const</B> <B>char</B>* mesg);
};


<B>char</B>* Echo_i::echoString(<B>const</B> <B>char</B>* mesg)
{
  cout &lt;&lt; "Upcall " &lt;&lt; mesg &lt;&lt; endl;
  <B>return</B> CORBA::string_dup(mesg);
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    CORBA::Object_var obj = orb-&gt;resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    Echo_i* myecho = <B>new</B> Echo_i();

    PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(myecho);

    <I>// Obtain a reference to the object, and print it out as a</I>
    <I>// stringified IOR.</I>
    obj = myecho-&gt;_this();
    CORBA::String_var sior(orb-&gt;object_to_string(obj));
    cout &lt;&lt; (<B>char</B>*)sior &lt;&lt; endl;

    myecho-&gt;_remove_ref();

    PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
    pman-&gt;activate();

    orb-&gt;run();
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}</DIV><!--TOC subsection eg2_clt.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc36">2.12.3</A>&#XA0;&#XA0;eg2_clt.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg2_clt.cc - This is the source code of example 2 used in Chapter 2</I>
<I>//              "The Basics" of the omniORB user guide.</I>
<I>//</I>
<I>//              This is the client. The object reference is given as a</I>
<I>//              stringified IOR on the command line.</I>
<I>//</I>
<I>// Usage: eg2_clt &lt;object reference&gt;</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
<B>#  include</B> &lt;fstream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>


<B>static</B> <B>void</B> hello(Echo_ptr e)
{
  CORBA::String_var src = (<B>const</B> <B>char</B>*) "Hello!";

  CORBA::String_var dest = e-&gt;echoString(src);

  cout &lt;&lt; "I said, \"" &lt;&lt; (<B>char</B>*)src &lt;&lt; "\"." &lt;&lt; endl
       &lt;&lt; "The Echo object replied, \"" &lt;&lt; (<B>char</B>*)dest &lt;&lt;"\"." &lt;&lt; endl;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{


  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    <B>if</B>( argc != 2 ) {
      cerr &lt;&lt; "usage:  eg2_clt &lt;object reference&gt;" &lt;&lt; endl;
      <B>return</B> 1;
    }

    CORBA::Object_var obj = orb-&gt;string_to_object(argv[1]);
    Echo_var echoref = Echo::_narrow(obj);
    <B>if</B>( CORBA::is_nil(echoref) ) {
      cerr &lt;&lt; "Can't narrow reference to type Echo (or it was nil)." &lt;&lt; endl;
      <B>return</B> 1;
    }
    <B>for</B> (CORBA::ULong count=0; count&lt;10; count++)
      hello(echoref);

    orb-&gt;destroy();
  }
  <B>catch</B>(CORBA::TRANSIENT&amp;) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "server." &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}</DIV><!--TOC subsection eg3_impl.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc37">2.12.4</A>&#XA0;&#XA0;eg3_impl.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg3_impl.cc - This is the source code of example 3 used in Chapter 2</I>
<I>//               "The Basics" of the omniORB user guide.</I>
<I>//</I>
<I>//               This is the object implementation.</I>
<I>//</I>
<I>// Usage: eg3_impl</I>
<I>//</I>
<I>//        On startup, the object reference is registered with the</I>
<I>//        COS naming service. The client uses the naming service to</I>
<I>//        locate this object.</I>
<I>//</I>
<I>//        The name which the object is bound to is as follows:</I>
<I>//              root  [context]</I>
<I>//               |</I>
<I>//              test  [context] kind [my_context]</I>
<I>//               |</I>
<I>//              Echo  [object]  kind [Object]</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<B>static</B> CORBA::Boolean bindObjectToName(CORBA::ORB_ptr, CORBA::Object_ptr);


<B>class</B> Echo_i : <B>public</B> POA_Echo
{
<B>public</B>:
  <B>inline</B> Echo_i() {}
  <B>virtual</B> ~Echo_i() {}
  <B>virtual</B> <B>char</B>* echoString(<B>const</B> <B>char</B>* mesg);
};


<B>char</B>* Echo_i::echoString(<B>const</B> <B>char</B>* mesg)
{
  <B>return</B> CORBA::string_dup(mesg);
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B>
main(<B>int</B> argc, <B>char</B> **argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    CORBA::Object_var obj = orb-&gt;resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    Echo_i* myecho = <B>new</B> Echo_i();

    PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(myecho);

    <I>// Obtain a reference to the object, and register it in</I>
    <I>// the naming service.</I>
    obj = myecho-&gt;_this();

    CORBA::String_var x;
    x = orb-&gt;object_to_string(obj);
    cout &lt;&lt; x &lt;&lt; endl;

    <B>if</B>( !bindObjectToName(orb, obj) )
      <B>return</B> 1;

    myecho-&gt;_remove_ref();

    PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
    pman-&gt;activate();

    orb-&gt;run();
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>static</B> CORBA::Boolean
bindObjectToName(CORBA::ORB_ptr orb, CORBA::Object_ptr objref)
{
  CosNaming::NamingContext_var rootContext;

  <B>try</B> {
    <I>// Obtain a reference to the root context of the Name service:</I>
    CORBA::Object_var obj;
    obj = orb-&gt;resolve_initial_references("NameService");

    <I>// Narrow the reference returned.</I>
    rootContext = CosNaming::NamingContext::_narrow(obj);
    <B>if</B>( CORBA::is_nil(rootContext) ) {
      cerr &lt;&lt; "Failed to narrow the root naming context." &lt;&lt; endl;
      <B>return</B> 0;
    }
  }
  <B>catch</B> (CORBA::NO_RESOURCES&amp;) {
    cerr &lt;&lt; "Caught NO_RESOURCES exception. You must configure omniORB "
         &lt;&lt; "with the location" &lt;&lt; endl
         &lt;&lt; "of the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }
  <B>catch</B> (CORBA::ORB::InvalidName&amp;) {
    <I>// This should not happen!</I>
    cerr &lt;&lt; "Service required is invalid [does not exist]." &lt;&lt; endl;
    <B>return</B> 0;
  }

  <B>try</B> {
    <I>// Bind a context called "test" to the root context:</I>

    CosNaming::Name contextName;
    contextName.length(1);
    contextName[0].id   = (<B>const</B> <B>char</B>*) "test";       <I>// string copied</I>
    contextName[0].kind = (<B>const</B> <B>char</B>*) "my_context"; <I>// string copied</I>
    <I>// Note on kind: The kind field is used to indicate the type</I>
    <I>// of the object. This is to avoid conventions such as that used</I>
    <I>// by files (name.type -- e.g. test.ps = postscript etc.)</I>

    CosNaming::NamingContext_var testContext;
    <B>try</B> {
      <I>// Bind the context to root.</I>
      testContext = rootContext-&gt;bind_new_context(contextName);
    }
    <B>catch</B>(CosNaming::NamingContext::AlreadyBound&amp; ex) {
      <I>// If the context already exists, this exception will be raised.</I>
      <I>// In this case, just resolve the name and assign testContext</I>
      <I>// to the object returned:</I>
      CORBA::Object_var obj;
      obj = rootContext-&gt;resolve(contextName);
      testContext = CosNaming::NamingContext::_narrow(obj);
      <B>if</B>( CORBA::is_nil(testContext) ) {
        cerr &lt;&lt; "Failed to narrow naming context." &lt;&lt; endl;
        <B>return</B> 0;
      }
    }

    <I>// Bind objref with name Echo to the testContext:</I>
    CosNaming::Name objectName;
    objectName.length(1);
    objectName[0].id   = (<B>const</B> <B>char</B>*) "Echo";   <I>// string copied</I>
    objectName[0].kind = (<B>const</B> <B>char</B>*) "Object"; <I>// string copied</I>

    <B>try</B> {
      testContext-&gt;bind(objectName, objref);
    }
    <B>catch</B>(CosNaming::NamingContext::AlreadyBound&amp; ex) {
      testContext-&gt;rebind(objectName, objref);
    }
    <I>// Note: Using rebind() will overwrite any Object previously bound</I>
    <I>//       to /test/Echo with obj.</I>
    <I>//       Alternatively, bind() can be used, which will raise a</I>
    <I>//       CosNaming::NamingContext::AlreadyBound exception if the name</I>
    <I>//       supplied is already bound to an object.</I>

    <I>// Amendment: When using OrbixNames, it is necessary to first try bind</I>
    <I>// and then rebind, as rebind on it's own will throw a NotFoundexception if</I>
    <I>// the Name has not already been bound. [This is incorrect behaviour -</I>
    <I>// it should just bind].</I>
  }
  <B>catch</B>(CORBA::TRANSIENT&amp; ex) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "naming service." &lt;&lt; endl
         &lt;&lt; "Make sure the naming server is running and that omniORB is "
         &lt;&lt; "configured correctly." &lt;&lt; endl;

    <B>return</B> 0;
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name()
         &lt;&lt; " while using the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }
  <B>return</B> 1;
}</DIV><!--TOC subsection eg3_clt.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc38">2.12.5</A>&#XA0;&#XA0;eg3_clt.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg3_clt.cc - This is the source code of example 3 used in Chapter 2</I>
<I>//              "The Basics" of the omniORB user guide.</I>
<I>//</I>
<I>//              This is the client. It uses the COSS naming service</I>
<I>//              to obtain the object reference.</I>
<I>//</I>
<I>// Usage: eg3_clt</I>
<I>//</I>
<I>//</I>
<I>//        On startup, the client lookup the object reference from the</I>
<I>//        COS naming service.</I>
<I>//</I>
<I>//        The name which the object is bound to is as follows:</I>
<I>//              root  [context]</I>
<I>//               |</I>
<I>//              text  [context] kind [my_context]</I>
<I>//               |</I>
<I>//              Echo  [object]  kind [Object]</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<B>static</B> CORBA::Object_ptr getObjectReference(CORBA::ORB_ptr orb);

<B>static</B> <B>void</B> hello(Echo_ptr e)
{
  <B>if</B>( CORBA::is_nil(e) ) {
    cerr &lt;&lt; "hello: The object reference is nil!\n" &lt;&lt; endl;
    <B>return</B>;
  }

  CORBA::String_var src = (<B>const</B> <B>char</B>*) "Hello!";

  CORBA::String_var dest = e-&gt;echoString(src);

  cerr &lt;&lt; "I said, \"" &lt;&lt; (<B>char</B>*)src &lt;&lt; "\"." &lt;&lt; endl
       &lt;&lt; "The Echo object replied, \"" &lt;&lt; (<B>char</B>*)dest &lt;&lt;"\"." &lt;&lt; endl;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B>
main (<B>int</B> argc, <B>char</B> **argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    CORBA::Object_var obj = getObjectReference(orb);

    Echo_var echoref = Echo::_narrow(obj);

    <B>for</B> (CORBA::ULong count=0; count &lt; 10; count++)
      hello(echoref);

    orb-&gt;destroy();
  }
  <B>catch</B>(CORBA::TRANSIENT&amp;) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "server." &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>static</B> CORBA::Object_ptr
getObjectReference(CORBA::ORB_ptr orb)
{
  CosNaming::NamingContext_var rootContext;

  <B>try</B> {
    <I>// Obtain a reference to the root context of the Name service:</I>
    CORBA::Object_var obj;
    obj = orb-&gt;resolve_initial_references("NameService");

    <I>// Narrow the reference returned.</I>
    rootContext = CosNaming::NamingContext::_narrow(obj);
    <B>if</B>( CORBA::is_nil(rootContext) ) {
      cerr &lt;&lt; "Failed to narrow the root naming context." &lt;&lt; endl;
      <B>return</B> CORBA::Object::_nil();
    }
  }
  <B>catch</B> (CORBA::NO_RESOURCES&amp;) {
    cerr &lt;&lt; "Caught NO_RESOURCES exception. You must configure omniORB "
         &lt;&lt; "with the location" &lt;&lt; endl
         &lt;&lt; "of the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }
  <B>catch</B>(CORBA::ORB::InvalidName&amp; ex) {
    <I>// This should not happen!</I>
    cerr &lt;&lt; "Service required is invalid [does not exist]." &lt;&lt; endl;
    <B>return</B> CORBA::Object::_nil();
  }

  <I>// Create a name object, containing the name test/context:</I>
  CosNaming::Name name;
  name.length(2);

  name[0].id   = (<B>const</B> <B>char</B>*) "test";       <I>// string copied</I>
  name[0].kind = (<B>const</B> <B>char</B>*) "my_context"; <I>// string copied</I>
  name[1].id   = (<B>const</B> <B>char</B>*) "Echo";
  name[1].kind = (<B>const</B> <B>char</B>*) "Object";
  <I>// Note on kind: The kind field is used to indicate the type</I>
  <I>// of the object. This is to avoid conventions such as that used</I>
  <I>// by files (name.type -- e.g. test.ps = postscript etc.)</I>

  <B>try</B> {
    <I>// Resolve the name to an object reference.</I>
    <B>return</B> rootContext-&gt;resolve(name);
  }
  <B>catch</B>(CosNaming::NamingContext::NotFound&amp; ex) {
    <I>// This exception is thrown if any of the components of the</I>
    <I>// path [contexts or the object] aren't found:</I>
    cerr &lt;&lt; "Context not found." &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::TRANSIENT&amp; ex) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "naming service." &lt;&lt; endl
         &lt;&lt; "Make sure the naming server is running and that omniORB is "
         &lt;&lt; "configured correctly." &lt;&lt; endl;

  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name()
         &lt;&lt; " while using the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }

  <B>return</B> CORBA::Object::_nil();
}</DIV><!--TOC subsection eg3_tieimpl.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc39">2.12.6</A>&#XA0;&#XA0;eg3_tieimpl.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// eg3_tieimpl.cc - This example is similar to eg3_impl.cc except that</I>
<I>//                  the tie implementation skeleton is used.</I>
<I>//</I>
<I>//               This is the object implementation.</I>
<I>//</I>
<I>// Usage: eg3_tieimpl</I>
<I>//</I>
<I>//        On startup, the object reference is registered with the </I>
<I>//        COS naming service. The client uses the naming service to</I>
<I>//        locate this object.</I>
<I>//</I>
<I>//        The name which the object is bound to is as follows:</I>
<I>//              root  [context]</I>
<I>//               |</I>
<I>//              test  [context] kind [my_context]</I>
<I>//               |</I>
<I>//              Echo  [object]  kind [Object]</I>
<I>//</I>

<B>#include</B> &lt;echo.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<B>static</B> CORBA::Boolean bindObjectToName(CORBA::ORB_ptr,CORBA::Object_ptr);


<I>// This is the object implementation.  Notice that it does not inherit</I>
<I>// from any stub class, and notice that the echoString() member</I>
<I>// function does not have to be virtual.</I>

<B>class</B> Echo_i {
<B>public</B>:
  <B>inline</B> Echo_i() {}
  <B>inline</B> ~Echo_i() {}
  <B>char</B>* echoString(<B>const</B> <B>char</B>* mesg);
};


<B>char</B>* Echo_i::echoString(<B>const</B> <B>char</B>* mesg)
{
  <B>return</B> CORBA::string_dup(mesg);
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    CORBA::Object_var obj = orb-&gt;resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    <I>// Note that the &lt;myecho&gt; tie object is constructed on the stack</I>
    <I>// here. It will delete its implementation (myimpl) when it it</I>
    <I>// itself destroyed (when it goes out of scope).  It is essential</I>
    <I>// however to ensure that such servants are not deleted whilst</I>
    <I>// still activated.</I>
    <I>//</I>
    <I>// Tie objects can of course be allocated on the heap using new,</I>
    <I>// in which case they are deleted when their reference count</I>
    <I>// becomes zero, as with any other servant object.</I>
    Echo_i* myimpl = <B>new</B> Echo_i();
    POA_Echo_tie&lt;Echo_i&gt; myecho(myimpl);

    PortableServer::ObjectId_var myechoid = poa-&gt;activate_object(&amp;myecho);

    <I>// Obtain a reference to the object, and register it in</I>
    <I>// the naming service.</I>
    obj = myecho._this();
    <B>if</B>( !bindObjectToName(orb, obj) )
      <B>return</B> 1;

    PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
    pman-&gt;activate();

    orb-&gt;run();
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>static</B> CORBA::Boolean
bindObjectToName(CORBA::ORB_ptr orb, CORBA::Object_ptr objref)
{
  CosNaming::NamingContext_var rootContext;

  <B>try</B> {
    <I>// Obtain a reference to the root context of the Name service:</I>
    CORBA::Object_var obj;
    obj = orb-&gt;resolve_initial_references("NameService");

    <I>// Narrow the reference returned.</I>
    rootContext = CosNaming::NamingContext::_narrow(obj);
    <B>if</B>( CORBA::is_nil(rootContext) ) {
      cerr &lt;&lt; "Failed to narrow the root naming context." &lt;&lt; endl;
      <B>return</B> 0;
    }
  }
  <B>catch</B> (CORBA::NO_RESOURCES&amp;) {
    cerr &lt;&lt; "Caught NO_RESOURCES exception. You must configure omniORB "
         &lt;&lt; "with the location" &lt;&lt; endl
         &lt;&lt; "of the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }
  <B>catch</B> (CORBA::ORB::InvalidName&amp;) {
    <I>// This should not happen!</I>
    cerr &lt;&lt; "Service required is invalid [does not exist]." &lt;&lt; endl;
    <B>return</B> 0;
  }

  <B>try</B> {
    <I>// Bind a context called "test" to the root context:</I>

    CosNaming::Name contextName;
    contextName.length(1);
    contextName[0].id   = (<B>const</B> <B>char</B>*) "test";       <I>// string copied</I>
    contextName[0].kind = (<B>const</B> <B>char</B>*) "my_context"; <I>// string copied</I>
    <I>// Note on kind: The kind field is used to indicate the type</I>
    <I>// of the object. This is to avoid conventions such as that used</I>
    <I>// by files (name.type -- e.g. test.ps = postscript etc.)</I>

    CosNaming::NamingContext_var testContext;
    <B>try</B> {
      <I>// Bind the context to root.</I>
      testContext = rootContext-&gt;bind_new_context(contextName);
    }
    <B>catch</B>(CosNaming::NamingContext::AlreadyBound&amp; ex) {
      <I>// If the context already exists, this exception will be raised.</I>
      <I>// In this case, just resolve the name and assign testContext</I>
      <I>// to the object returned:</I>
      CORBA::Object_var obj;
      obj = rootContext-&gt;resolve(contextName);
      testContext = CosNaming::NamingContext::_narrow(obj);
      <B>if</B>( CORBA::is_nil(testContext) ) {
        cerr &lt;&lt; "Failed to narrow naming context." &lt;&lt; endl;
        <B>return</B> 0;
      }
    }

    <I>// Bind objref with name Echo to the testContext:</I>
    CosNaming::Name objectName;
    objectName.length(1);
    objectName[0].id   = (<B>const</B> <B>char</B>*) "Echo";   <I>// string copied</I>
    objectName[0].kind = (<B>const</B> <B>char</B>*) "Object"; <I>// string copied</I>

    <B>try</B> {
      testContext-&gt;bind(objectName, objref);
    }
    <B>catch</B>(CosNaming::NamingContext::AlreadyBound&amp; ex) {
      testContext-&gt;rebind(objectName, objref);
    }
    <I>// Note: Using rebind() will overwrite any Object previously bound</I>
    <I>//       to /test/Echo with obj.</I>
    <I>//       Alternatively, bind() can be used, which will raise a</I>
    <I>//       CosNaming::NamingContext::AlreadyBound exception if the name</I>
    <I>//       supplied is already bound to an object.</I>

    <I>// Amendment: When using OrbixNames, it is necessary to first try bind</I>
    <I>// and then rebind, as rebind on it's own will throw a NotFoundexception if</I>
    <I>// the Name has not already been bound. [This is incorrect behaviour -</I>
    <I>// it should just bind].</I>
  }
  <B>catch</B>(CORBA::TRANSIENT&amp; ex) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "naming service." &lt;&lt; endl
         &lt;&lt; "Make sure the naming server is running and that omniORB is "
         &lt;&lt; "configured correctly." &lt;&lt; endl;

    <B>return</B> 0;
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name()
         &lt;&lt; " while using the naming service." &lt;&lt; endl;
    <B>return</B> 0;
  }
  <B>return</B> 1;
}</DIV><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note3" HREF="#text3">1</A></DT><DD CLASS="dd-thefootnotes">The stub
code is the C++ code that provides the object mapping as defined in
the CORBA specification.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note4" HREF="#text4">2</A></DT><DD CLASS="dd-thefootnotes">In
omniORB, all object reference variable types are instantiated from the
template type <TT>_CORBA_ObjRef_Var</TT>.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note5" HREF="#text5">3</A></DT><DD CLASS="dd-thefootnotes">However, the implementation
of the type conversion operator between <TT>Echo_var</TT> and
<TT>Echo_ptr</TT> varies slightly among different C++ compilers; you
may need to do an explicit cast if the compiler complains about the
conversion being ambiguous.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note6" HREF="#text6">4</A></DT><DD CLASS="dd-thefootnotes">In the previous 1.0 version of the C++
mapping, servant reference counting was optional, chosen by inheriting
from a mixin class named <TT>RefCountServantBase</TT>. That has been
deprecated in the 1.1 version of the C++ mapping, but the class is
still available as an empty struct, so existing code that inherits
from <TT>RefCountServantBase</TT> will continue to work.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note7" HREF="#text7">5</A></DT><DD CLASS="dd-thefootnotes">A conversion operator of
<TT>CORBA::String_var</TT> converts a <TT>CORBA::String_var</TT>
to a <TT>char*</TT>.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note8" HREF="#text8">6</A></DT><DD CLASS="dd-thefootnotes">Please refer to the C++
mapping specification for details of the String_var mapping.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note9" HREF="#text9">7</A></DT><DD CLASS="dd-thefootnotes">For backwards compatibility, the ORB identifiers
&#X2018;omniORB2&#X2019; and &#X2018;omniORB3&#X2019; are also accepted.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note10" HREF="#text10">8</A></DT><DD CLASS="dd-thefootnotes">If a system exception is not caught, the C++
runtime will call the <TT>terminate()</TT> function. This function is
defaulted to abort the whole process and on some systems will cause a
core file to be produced.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note11" HREF="#text11">9</A></DT><DD CLASS="dd-thefootnotes">Run Time Type
Identification
</DD><DT CLASS="dt-thefootnotes"><A NAME="note12" HREF="#text12">10</A></DT><DD CLASS="dd-thefootnotes">The POA itself
can be activated on demand with an adapter activator.
</DD><DT CLASS="dt-thefootnotes"><A NAME="note13" HREF="#text13">11</A></DT><DD CLASS="dd-thefootnotes">There are escaping rules to cope
with id and kind fields which contain &#X2018;.&#X2019; and &#X2018;/&#X2019; characters. See
chapter&#XA0;<A HREF="#chap:ins">6</A> of this manual, and chapter 3 of the CORBA
services specification, as updated for the Interoperable Naming
Service&#XA0;[<A HREF="#inschapters">OMG00</A>].
</DD></DL>
<!--END NOTES-->
<!--TOC chapter C++ language mapping-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc40">Chapter&#XA0;3</A>&#XA0;&#XA0;C++ language mapping</H1><!--SEC END --><P>Now that you are familiar with the basics, it is important to
familiarise yourself with the standard IDL to C++ language mapping.
The mapping is described in detail in&#XA0;[<A HREF="#cxxmapping">OMG03</A>]. If you have
not done so, you should obtain a copy of the document and use that as
the programming guide to omniORB.</P><P>The specification is not an easy read. The alternative is to use one
of the books on CORBA programming that has begun to appear. For
instance, Henning and Vinoski&#X2019;s &#X2018;Advanced CORBA Programming with
C++&#X2019;&#XA0;[<A HREF="#henning1999">HV99</A>] includes many example code bits to illustrate
how to use the C++ mapping.</P><!--TOC section omniORB 2 BOA compatibility-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc41">3.1</A>&#XA0;&#XA0;omniORB 2 BOA compatibility</H2><!--SEC END --><P>
<A NAME="sec:BOAcompat"></A></P><P>If you use the <TT>-WbBOA</TT> option to omniidl, it will generate
skeleton code with the same interface as the old omniORB 2 BOA
mapping, as well as code to be used with the POA. Note that since the
major problem with the BOA specification was that server code was not
portable between ORBs, it is unlikely that omniORB 4.1&#X2019;s BOA
compatibility will help you much if you are moving from a different
BOA-based ORB.</P><P>The BOA compatibility permits the majority of BOA code to compile
without difficulty. However, there are a number of constructs which
relied on omniORB 2 implementation details which no longer work.</P><UL CLASS="itemize"><LI CLASS="li-itemize">omniORB 2 did not use distinct types for object references and
servants, and often accepted a pointer to a servant when the CORBA
specification says it should only accept an object reference. Such
code will not compile under omniORB 4.1.</LI><LI CLASS="li-itemize">The reverse is true for <TT>BOA::obj_is_ready()</TT>. It now only
works when passed a pointer to a servant object, not an object
reference. The more commonly used mechanism of calling
<TT>_obj_is_ready(boa)</TT> on the servant object still works as
expected.</LI><LI CLASS="li-itemize">It used to be the case that the skeleton class for interface
<TT>I</TT> (<TT>_sk_I</TT>) was derived from class <TT>I</TT>. This meant
that the names of any types declared in the interface were available
in the scope of the skeleton class. This is no longer true. If you
have an interface:<DIV CLASS="lstlisting"><B>interface</B> I {
  <B>struct</B> S {
    <B>long</B> a,b;
  };
  S op();
};</DIV><P>then where before the implementation code might have been:</P><DIV CLASS="lstlisting"><B>class</B> I_impl : <B>public</B> <B>virtual</B> _sk_I {
  S op();  <I>// _sk_I is derived from I</I>
};
I::S I_impl::op() {
  S ret;
  <I>// ...</I>
}</DIV><P>it is now necessary to fully qualify all uses of <TT>S</TT>:</P><DIV CLASS="lstlisting"><B>class</B> I_impl : <B>public</B> <B>virtual</B> _sk_I {
  I::S op(); <I>// _sk_I is not derived from I</I>
};
I::S I_impl::op() {
  I::S ret;
  <I>// ...</I>
}</DIV></LI><LI CLASS="li-itemize">The proprietary omniORB 2 LifeCycle extensions are no longer
supported. All of the facilities it offered can be implemented with
the POA interfaces, and the <TT>omniORB::LOCATION_FORWARD</TT>
exception (see section&#XA0;<A HREF="#sec:locationForward">4.8</A>). Code which used the
old interfaces will have to be rewritten.</LI></UL><!--TOC section omniORB 3.0 compatibility-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc42">3.2</A>&#XA0;&#XA0;omniORB 3.0 compatibility</H2><!--SEC END --><P>omniORB 4.1 is almost completely source-code compatible with omniORB
3.0. There are two main cases where code may have to change. The first
is code that uses the omniORB API, some aspects of which have
changed. The omniORB configuration file also has a new format. See the
next chapter for details of the new API and configuration file.</P><P>The second case of code that may have to change is code using the
Dynamic Any interfaces. The standard changed quite significantly
between CORBA 2.2 and CORBA 2.3; omniORB 3.0 supported the old CORBA
2.2 interfaces; omniORB 4.1 uses the new mapping. The changes are
largely syntax changes, rather than semantic differences.</P><!--TOC section omniORB 4.0 compatibility-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc43">3.3</A>&#XA0;&#XA0;omniORB 4.0 compatibility</H2><!--SEC END --><P>omniORB 4.1 is source-code compatible with omniORB 4.0, with four
exceptions:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">As required by the 1.1 version of the CORBA C++ mapping
specification, the <TT>RefCountServantBase</TT> class has been
deprecated, and the reference counting functionality moved into
<TT>ServantBase</TT>. For backwards compatibility,
<TT>RefCountServantBase</TT> still exists, but is now defined as an
empty struct. Most code will continue to work unchanged, but code
that explicitly calls <TT>RefCountServantBase::_add_ref()</TT> or
<TT>_remove_ref()</TT> will no longer compile.</LI><LI CLASS="li-enumerate">omniORB 4.0 had an option for Any extraction semantics that was
compatible with omniORB 2.7, where ownership of extracted values was
not maintained by the Any. That option is no longer available.</LI><LI CLASS="li-enumerate">The members of the <TT>clientSendRequest</TT> interceptor have
been changed, replacing all the separate variables with a single
member of type <TT>GIOP_C</TT>. All the values previously available
can be accessed through the <TT>GIOP_C</TT> instance.</LI><LI CLASS="li-enumerate">The C++ mapping contains Any insertion operators for sequence
types that are passed by pointer, which cause the Any to take
ownership of the inserted sequence. In omniORB 4.0 and earlier, the
sequence was immediately marshalled into the Any&#X2019;s internal buffer,
and the sequence was deleted. In omniORB 4.1, the sequence pointer
is stored by the Any, and the sequence is deleted later when the Any
is destroyed.<P>For most uses, this change is not visible to application code.
However, if a sequence is constructed using an application-supplied
buffer with the release flag set to false (meaning that the
application continues to own the buffer), it is now important that
the buffer is not deleted or modified while the Any exists, since
the Any continues to refer to the buffer contents. This change
means that code that worked with omniORB 4.0 may now fail with 4.1,
with the Any seeing modified data or the process crashing due to
accessing deleted data. To avoid this situation, use the alternative
Any insertion operator using a const reference, which copies the
sequence.</P></LI></OL><!--TOC chapter omniORB configuration and API-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc44">Chapter&#XA0;4</A>&#XA0;&#XA0;omniORB configuration and API</H1><!--SEC END --><P>
<A NAME="chap:config"></A></P><P>omniORB 4.1 has a wide range of parameters that can be
configured. They can be set in the configuration file / Windows
registry, as environment variables, on the command line, or within a
proprietary extra argument to <TT>CORBA::ORB_init()</TT>. A few parameters
can be configured at run time. This chapter lists all the
configuration parameters, and how they are used.</P><!--TOC section Setting parameters-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc45">4.1</A>&#XA0;&#XA0;Setting parameters</H2><!--SEC END --><P>When <TT>CORBA::ORB_init()</TT> is called, the value for each configuration
parameter is searched for in the following order:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">Command line arguments
</LI><LI CLASS="li-enumerate"><TT>ORB_init()</TT> options
</LI><LI CLASS="li-enumerate">Environment variables
</LI><LI CLASS="li-enumerate">Configuration file / Windows registry
</LI><LI CLASS="li-enumerate">Built-in defaults</LI></OL><!--TOC subsection Command line arguments-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc46">4.1.1</A>&#XA0;&#XA0;Command line arguments</H3><!--SEC END --><P>Command line arguments take the form
&#X2018;<TT>-ORB</TT><I>parameter</I>&#X2019;, and usually expect another
argument. An example is &#X2018;<TT>-ORBtraceLevel 10</TT>&#X2019;.</P><!--TOC subsection ORB_init() parameter-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc47">4.1.2</A>&#XA0;&#XA0;ORB_init() parameter</H3><!--SEC END --><P><TT>ORB_init()</TT>&#X2019;s extra argument accepts an array of two-dimensional
string arrays, like this:</P><DIV CLASS="lstlisting"><B>const</B> <B>char</B>* options[][2] = { { "traceLevel", "1" }, { 0, 0 } };
orb = CORBA::ORB_init(argc,argv,"omniORB4",options);</DIV><!--TOC subsection Environment variables-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc48">4.1.3</A>&#XA0;&#XA0;Environment variables</H3><!--SEC END --><P>Environment variables consist of the parameter name prefixed with
&#X2018;<TT>ORB</TT>&#X2019;. Using bash, for example</P><DIV CLASS="lstlisting">export ORBtraceLevel=10</DIV><!--TOC subsection Configuration file-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc49">4.1.4</A>&#XA0;&#XA0;Configuration file</H3><!--SEC END --><P>The best way to understand the format of the configuration file is to
look at the <TT>sample.cfg</TT> file in the omniORB distribution. Each
parameter is set on a single line like</P><PRE CLASS="verbatim">traceLevel = 10
</PRE><P>Some parameters can have more than one value, in which case the
parameter name may be specified more than once, or you can leave it
out:</P><PRE CLASS="verbatim">InitRef = NameService=corbaname::host1.example.com
        = InterfaceRepository=corbaloc::host2.example.com:1234/IfR
</PRE><DIV CLASS="minipage"><HR SIZE=2><DL CLASS="list"><DT CLASS="dt-list">

</DT><DD CLASS="dd-list">
Note how command line arguments and environment variables prefix
parameter names with &#X2018;-ORB&#X2019; and &#X2018;ORB&#X2019; respectively, but the
configuration file and the extra argument to <TT>ORB_init()</TT> do not use
a prefix.
</DD></DL><HR SIZE=2></DIV><!--TOC subsection Windows registry-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc50">4.1.5</A>&#XA0;&#XA0;Windows registry</H3><!--SEC END --><P>On Windows, configuration parameters can be stored in the registry,
under the key <TT>HKEY_LOCAL_MACHINE\SOFTWARE\omniORB</TT>.</P><P>The file <TT>sample.reg</TT> shows the settings that can be made. It can
be edited and then imported into regedit.</P><!--TOC section Tracing options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc51">4.2</A>&#XA0;&#XA0;Tracing options</H2><!--SEC END --><P>The following options control debugging trace output.</P><P><TT>traceLevel</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>omniORB can output tracing and diagnostic messages to the standard
error stream. The following levels are defined:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left NOWRAP>&nbsp;</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
level 0</TD><TD VALIGN=top ALIGN=left>critical errors only</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>level 1</TD><TD VALIGN=top ALIGN=left>informational messages only</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>level 2</TD><TD VALIGN=top ALIGN=left>configuration information and warnings</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
level 5</TD><TD VALIGN=top ALIGN=left>notifications when server threads are
created and communication endpoints are shutdown</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
level 10</TD><TD VALIGN=top ALIGN=left>execution and exception traces</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>level 25</TD><TD VALIGN=top ALIGN=left>trace each send or receive of a giop message</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>level 30</TD><TD VALIGN=top ALIGN=left>dump up to 128 bytes of each giop message</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>level 40</TD><TD VALIGN=top ALIGN=left>dump complete contents of each giop message</TD></TR>
</TABLE><P>The trace level is cumulative, so at level 40, all trace
messages are output.</P><P><TT>traceExceptions</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If the <TT>traceExceptions</TT> parameter is set true, all system
exceptions are logged as they are thrown, along with details about
where the exception is thrown from. This parameter is enabled by
default if the traceLevel is set to 10 or more.</P><P><TT>traceInvocations</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If the <TT>traceInvocations</TT> parameter is set true, all local and
remote invocations are logged, in addition to any logging that may
have been selected with <TT>traceLevel</TT>.</P><P><TT>traceInvocationReturns</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If the <TT>traceInvocationReturns</TT> parameter is set true, a log
message is output as an operation invocation returns. In conjunction
with <TT>traceInvocations</TT> and <TT>traceTime</TT> (described below),
this provides a simple way of timing CORBA calls within your
application.</P><P><TT>traceThreadId</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If <TT>traceThreadId</TT> is set true, all trace messages are prefixed
with the id of the thread outputting the message. This can be handy
for tracking down race conditions, but it adds significant overhead to
the logging function so it is turned off by default.</P><P><TT>traceTime</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If <TT>traceTime</TT> is set true, all trace messages are prefixed with
the time. This is useful, but on some platforms it adds a very large
overhead, so it is turned off by default.</P><P><TT>traceFile</TT> &#XA0;&#XA0; <I>default</I> =
</P><P>omniORB&#X2019;s tracing is normally sent to stderr. if <TT>traceFile</TT> it
set, the specified file name is used for trace messages.</P><!--TOC subsection Tracing API-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc52">4.2.1</A>&#XA0;&#XA0;Tracing API</H3><!--SEC END --><P>The tracing parameters can be modified at runtime by assigning to the
following variables</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {
  CORBA::ULong   traceLevel;
  CORBA::Boolean traceExceptions;
  CORBA::Boolean traceInvocations;
  CORBA::Boolean traceInvocationReturns;
  CORBA::Boolean traceThreadId;
  CORBA::Boolean traceTime;
};</DIV><P>Log messages can be sent somewhere other than stderr by registering a
logging function which is called with the text of each log message:</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {
  <B>typedef</B> <B>void</B> (*logFunction)(<B>const</B> <B>char</B>*);
  <B>void</B> setLogFunction(logFunction f);
};</DIV><P>The log function must not make any CORBA calls, since that could lead
to infinite recursion as outputting a log message caused other log
messages to be generated, and so on.</P><!--TOC section Miscellaneous global options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc53">4.3</A>&#XA0;&#XA0;Miscellaneous global options</H2><!--SEC END --><P>These options control miscellaneous features that affect the whole ORB
runtime.</P><P><TT>dumpConfiguration</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If set true, the ORB dumps the values of all configuration parameters
at start-up.</P><P><TT>scanGranularity</TT> &#XA0;&#XA0; <I>default</I> =
<TT>5</TT></P><P>As explained in chapter&#XA0;<A HREF="#chap:connections">8</A>, omniORB regularly
scans incoming and outgoing connections, so it can close unused
ones. This value is the granularity in seconds at which the ORB
performs its scans. A value of zero turns off the scanning altogether.</P><P><TT>nativeCharCodeSet</TT> &#XA0;&#XA0; <I>default</I> =
<TT>ISO-8859-1</TT></P><P>The native code set the application is using for <TT>char</TT> and
<TT>string</TT>. See chapter&#XA0;<A HREF="#chap:codesets">9</A>.</P><P><TT>nativeWCharCodeSet</TT> &#XA0;&#XA0; <I>default</I> =
<TT>UTF-16</TT></P><P>The native code set the application is using for <TT>wchar</TT> and
<TT>wstring</TT>. See chapter&#XA0;<A HREF="#chap:codesets">9</A>.</P><P><TT>copyValuesInLocalCalls</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>Determines whether valuetype parameters in local calls are copied or
not. See chapter&#XA0;<A HREF="#chap:valuetype">13</A>.</P><P><TT>abortOnInternalError</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If this is set true, internal fatal errors will abort immediately,
rather than throwing the <TT>omniORB::fatalException</TT> exception.
This can be helpful for tracking down bugs, since it leaves the call
stack intact.</P><P><TT>abortOnNativeException</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>On Windows, &#X2018;native&#X2019; exceptions such as segmentation faults and divide
by zero appear as C++ exceptions that can be caught with <TT>catch
(...)</TT>. Setting this parameter to true causes such exceptions to
abort the process instead.</P><P><TT>maxSocketSend</TT><BR>
<TT>maxSocketRecv</TT><BR>

On some platforms, calls to send() and recv() have a limit on the
buffer size that can be used. These parameters set the limits in bytes
that omniORB uses when sending / receiving bulk data.</P><P>The default values are platform specific. It is unlikely that you will
need to change the values from the defaults.</P><P>The minimum valid limit is 1KB, 1024 bytes.</P><P><TT>socketSendBuffer</TT> &#XA0;&#XA0; <I>default</I> =
<TT>-1 </TT><TT><I>or</I></TT><TT> 16384</TT></P><P>On Windows, there is a kernel buffer used during send operations. A
bug in Windows means that if a send uses the entire kernel buffer, a
select() on the socket blocks until all the data has been acknowledged
by the receiver, resulting in dreadful performance. This parameter
modifies the socket send buffer from its default (8192 bytes on
Windows) to the value specified. If this parameter is set to -1, the
socket send buffer is left at the system default.</P><P>On Windows, the default value of this parameter is 16384 bytes; on all
other platforms the default is -1.</P><P><TT>validateUTF8</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>When transmitting a string that is supposed to be UTF-8, omniORB
usually passes it directly, assuming that it is valid. With this
parameter set true, omniORB checks that all UTF-8 strings are valid,
and throws DATA_CONVERSION if not.</P><!--TOC section Client side options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc54">4.4</A>&#XA0;&#XA0;Client side options</H2><!--SEC END --><P>These options control aspects of client-side behaviour.</P><P><TT>InitRef</TT> &#XA0;&#XA0; <I>default</I> =
<TT><I>none</I></TT></P><P>Specify objects available from
<TT>ORB::resolve_initial_references()</TT>. The arguments take the form
&lt;<I>key</I>&gt;=&lt;<I>uri</I>&gt;, where <I>key</I> is the name given to
<TT>resolve_initial_references()</TT> and <I>uri</I> is a
valid CORBA object reference URI, as detailed in
chapter&#XA0;<A HREF="#chap:ins">6</A>.</P><P><TT>DefaultInitRef</TT> &#XA0;&#XA0; <I>default</I> =
<TT><I>none</I></TT></P><P>Specify the default URI prefix for
<TT>resolve_initial_references()</TT>, as explained in
chapter&#XA0;<A HREF="#chap:ins">6</A>.</P><P><TT>clientTransportRule</TT> &#XA0;&#XA0; <I>default</I> =
<TT>* unix,tcp,ssl</TT></P><P>Used to specify the way the client contacts a server, depending on the
server&#X2019;s address. See section&#XA0;<A HREF="#sec:clientRule">8.7.1</A> for details.</P><P><TT>clientCallTimeOutPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>Call timeout in milliseconds for the client side. If a call takes
longer than the specified number of milliseconds, the ORB closes the
connection to the server and raises a <TT>TRANSIENT</TT> exception. A
value of zero means no timeout; calls can block for ever. See
section&#XA0;<A HREF="#sec:timeoutAPI">8.3.1</A> for more information about timeouts.</P><P><B>Note</B>: omniORB 3 had timeouts specified in seconds;
omniORB 4.0 and later use milliseconds for timeouts.</P><P><TT>clientConnectTimeOutPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>The timeout that is used in the case that a new network connection is
established to the server. A value of zero means that the normal call
timeout is used. See section&#XA0;<A HREF="#sec:timeoutAPI">8.3.1</A> for more information
about timeouts.</P><P><TT>supportPerThreadTimeOut</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If this parameter is set true, timeouts can be set on a per thread
basis, as well as globally and per object. Checking per-thread storage
has a noticeable performance impact, so it is turned off by default.</P><P><TT>resetTimeoutOnRetries</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If true, the call timeout is reset when an exception handler causes a
call to be retried. If false, the timeout is not reset, and therefore
applies to the call as a whole, rather than to each individual call
attempt.</P><P><TT>outConScanPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>120</TT></P><P>Idle timeout in seconds for outgoing (i.e. client initiated)
connections. If a connection has been idle for this amount of time,
the ORB closes it. See section&#XA0;<A HREF="#sec:connShutdown">8.5</A>.</P><P><TT>maxGIOPConnectionPerServer</TT> &#XA0;&#XA0; <I>default</I> =
<TT>5</TT></P><P>The maximum number of concurrent connections the ORB will open to a
<EM>single</EM> server. If multiple threads on the client call the same
server, the ORB opens additional connections to the server, up to the
maximum specified by this parameter. If the maximum is reached,
threads are blocked until a connection becomes free for them to use.</P><P><TT>oneCallPerConnection</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>When this parameter is set to true (the default), the ORB will only
send a single call on a connection at a time. If multiple client
threads invoke on the same server, multiple connections are opened, up
to the limit specified by
<TT>maxGIOPConnectionPerServer</TT>. With this parameter set to
false, the ORB will allow concurrent calls on a single
connection. This saves connection resources, but requires slightly
more management work for both client and server. Some server-side ORBs
(including omniORB versions before 4.0) serialise all calls on a
single connection.</P><P><TT>maxInterleavedCallsPerConnection</TT> &#XA0;&#XA0; <I>default</I> =
<TT>5</TT></P><P>The maximum number of calls that can be interleaved on a connection.
If more concurrent calls are made, they are queued.</P><P><TT>offerBiDirectionalGIOP</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If set true, the client will indicate to servers that it is willing to
accept callbacks on client-initiated connections using bidirectional
GIOP, provided the relevant POA policies are set. See
section&#XA0;<A HREF="#sec:bidir">8.8</A>.</P><P><TT>diiThrowsSysExceptions</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If this is true, DII functions throw system exceptions; if it is
false, system exceptions that occur are passed through the
<TT>Environment</TT> object.</P><P><TT>verifyObjectExistsAndType</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>By default, omniORB uses the GIOP <TT>LOCATE_REQUEST</TT> message to
verify the existence of an object prior to the first invocation. In
the case that the full type of the object is not known, it instead
calls the <TT>_is_a()</TT> operation to check the object&#X2019;s type. Some ORBs
have bugs that mean one or other of these operations fail. Setting
this parameter false prevents omniORB from making these calls.</P><P><TT>giopTargetAddressMode</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>GIOP 1.2 supports three addressing modes for contacting objects. This
parameter selects the mode that omniORB uses. A value of 0 means
<TT>GIOP::KeyAddr</TT>; 1 means <TT>GIOP::ProfileAddr</TT>; 2 means
<TT>GIOP::ReferenceAddr</TT>.</P><P><TT>immediateAddressSwitch</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If true, the client will immediately switch to use a new address to
contact an object after a failure. If false (the default), the current
address will be retried in certain circumstances.</P><P><TT>bootstrapAgentHostname</TT> &#XA0;&#XA0; <I>default</I> =
<TT><I>none</I></TT></P><P>If set, this parameter indicates the hostname to use for look-ups
using the obsolete Sun bootstrap agent. This mechanism is superseded
by the interoperable naming service.</P><P><TT>bootstrapAgentPort</TT> &#XA0;&#XA0; <I>default</I> =
<TT>900</TT></P><P>The port number for the obsolete Sun bootstrap agent.</P><P><TT>principal</TT> &#XA0;&#XA0; <I>default</I> =
<TT><I>none</I></TT></P><P>GIOP 1.0 and 1.1 have a request header field named &#X2018;principal&#X2019;, which
contains a sequence of octets. It was never defined what it should
mean, and its use is now deprecated; GIOP 1.2 has no such field. Some
systems (e.g. Gnome) use the principal field as a primitive
authentication scheme. This parameter sets the data omniORB uses in
the principal field. The default is an empty sequence.</P><!--TOC section Server side options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc55">4.5</A>&#XA0;&#XA0;Server side options</H2><!--SEC END --><P>These parameters affect server-side operations.</P><P><TT>endPoint&#XA0;&#XA0;&#XA0;&#XA0;&#XA0;&#XA0;&#XA0;&#XA0;&#XA0;</TT> &#XA0;&#XA0; <I>default</I> = <TT>giop:tcp::</TT><BR>
<TT>endPointNoListen</TT><BR>
<TT>endPointPublish</TT><BR>
<TT>endPointNoPublish</TT><BR>
<TT>endPointPublishAllIFs</TT><BR>

These options determine the end-points the ORB should listen on, and
the details that should be published in IORs. See
chapter&#XA0;<A HREF="#chap:connections">8</A> for details.</P><P><TT>serverTransportRule</TT> &#XA0;&#XA0; <I>default</I> =
<TT>* unix,tcp,ssl</TT></P><P>Configure the rules about whether a server should accept an incoming
connection from a client. See section&#XA0;<A HREF="#sec:serverRule">8.7.2</A> for
details.</P><P><TT>serverCallTimeOutPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>This timeout is used to catch the situation that the server starts
receiving a request, but the end of the request never comes. If a
calls takes longer than the specified number of milliseconds to
arrive, the ORB shuts the connection. A value of zero means never
timeout.</P><P><TT>inConScanPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>180</TT></P><P>Idle timeout in seconds for incoming. If a connection has been idle
for this amount of time, the ORB closes it. See
section&#XA0;<A HREF="#sec:connShutdown">8.5</A>.</P><P><TT>threadPerConnectionPolicy</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>If true (the default), the ORB dedicates one server thread to each
incoming connection. Setting it false means the server should use a
thread pool.</P><P><TT>maxServerThreadPerConnection</TT> &#XA0;&#XA0; <I>default</I> =
<TT>100</TT></P><P>If the client multiplexes several concurrent requests on a single
connection, omniORB uses extra threads to service them. This parameter
specifies the maximum number of threads that are allowed to service a
single connection at any one time.</P><P><TT>maxServerThreadPoolSize</TT> &#XA0;&#XA0; <I>default</I> =
<TT>100</TT></P><P>The maximum number of threads the server will allocate to do various
tasks, including dispatching calls in the thread pool mode. This
number does not include threads dispatched under the thread per
connection server mode.</P><P><TT>threadPerConnectionUpperLimit</TT> &#XA0;&#XA0; <I>default</I> =
<TT>10000</TT></P><P>If the <TT>threadPerConnectionPolicy</TT> parameter is true, the ORB can
automatically transition to thread pool mode if too many connections
arrive. This parameter sets the number of connections at which thread
pooling is started. The default of 10000 is designed to mean that it
never happens.</P><P><TT>threadPerConnectionLowerLimit</TT> &#XA0;&#XA0; <I>default</I> =
<TT>9000</TT></P><P>If thread pooling was started because the number of connections hit
the upper limit, this parameter determines when thread per connection
should start again.</P><P><TT>threadPoolWatchConnection</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>After dispatching an upcall in thread pool mode, the thread that has
just performed the call can watch the connection for a short time
before returning to the pool. This leads to less thread switching for
a series of calls from a single client, but is less fair if there are
concurrent clients. The connection is watched if the number of threads
concurrently handling the connection is &lt;= the value of this
parameter. i.e. if the parameter is zero, the connection is never
watched; if it is 1, the last thread managing a connection watches it;
if 2, the connection is still watched if there is one other thread
still in an upcall for the connection, and so on.</P><P>See section&#XA0;<A HREF="#sec:watchConn">8.4.2</A>.</P><P><TT>connectionWatchPeriod</TT> &#XA0;&#XA0; <I>default</I> =
<TT>50000</TT></P><P>For each endpoint, the ORB allocates a thread to watch for new
connections and to monitor existing connections for calls that should
be handed by the thread pool. The thread blocks in select() or similar
for a period, after which it re-scans the lists of connections it
should watch. This parameter is specified in microseconds.</P><P><TT>connectionWatchImmediate</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>When a thread handles an incoming call, it unmarshals the arguments
then marks the connection as watchable by the connection watching
thread, in case the client sends a concurrent call on the same
connection. If this parameter is set to the default false, the
connection is not actually watched until the next connection watch
period (determined by the <TT>connectionWatchPeriod</TT> parameter). If
this parameter is set true, the connection watching thread is
immediately signalled to watch the connection. That leads to faster
interactive response to clients that multiplex calls, but adds
significant overhead along the call chain.</P><P>Note that this setting has no effect on Windows, since it has no
mechanism for signalling the connection watching thread.</P><P><TT>acceptBiDirectionalGIOP</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>Determines whether a server will ever accept clients&#X2019; offers of
bidirectional GIOP connections. See section&#XA0;<A HREF="#sec:bidir">8.8</A>.</P><P><TT>unixTransportDirectory</TT> &#XA0;&#XA0; <I>default</I> =
<TT>/tmp/omni-%u</TT></P><P>(Unix platforms only). Selects the location used to store Unix domain
sockets. The &#X2018;<TT>%u</TT>&#X2019; is expanded to the user name.</P><P><TT>unixTransportPermission</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0777</TT></P><P>(Unix platforms only). Determines the octal permission bits for Unix
domain sockets. By default, all users can connect to a server, just as
with TCP.</P><P><TT>supportCurrent</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>omniORB supports the <TT>PortableServer::Current</TT> interface to
provide thread context information to servants. Supporting current has
a small but noticeable run-time overhead due to accessing thread
specific storage, so this option allows it to be turned off.</P><P><TT>objectTableSize</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>Hash table size of the Active Object Map. If this is zero, the ORB
uses a dynamically resized open hash table. This is normally the best
option, but it leads to less predictable performance since any
operation which adds or removes a table entry may trigger a resize. If
set to a non-zero value, the hash table has the specified number of
entries, and is never resized. Note that the hash table is open, so
this does not limit the number of active objects, just how efficiently
they can be located.</P><P><TT>poaHoldRequestTimeout</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If a POA is put in the <TT>HOLDING</TT> state, calls to it will be timed
out after the specified number of milliseconds, by raising a
<TT>TRANSIENT</TT> exception. Zero means no timeout.</P><P><TT>poaUniquePersistentSystemIds</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>The POA specification requires that object ids in POAs with the
PERSISTENT and SYSTEM_ID policies are unique between instantiations
of the POA. Older versions of omniORB did not comply with that, and
reused object ids. With this value true, the POA has the correct
behaviour; with false, the POA uses the old scheme for compatibility.</P><P><TT>idleThreadTimeout</TT> &#XA0;&#XA0; <I>default</I> =
<TT>10</TT></P><P>When a thread created by omniORB becomes idle, it is kept alive for a
while, in case a new thread is required. Once a thread has been idle
for the number of seconds specified in this parameter, it exits.</P><P><TT>supportBootstrapAgent</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If set true, servers support the Sun bootstrap agent protocol.</P><!--TOC subsection Main thread selection-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc56">4.5.1</A>&#XA0;&#XA0;Main thread selection</H3><!--SEC END --><P>There is one server-side parameter that must be set with an API
function, rather than a normal configuration parameter:</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {
  <B>void</B> setMainThread();
};</DIV><P>POAs with the <TT>MAIN_THREAD</TT> policy dispatch calls on the &#X2018;main&#X2019;
thread. By default, omniORB assumes that the thread that initialised
the omnithread library is the &#X2018;main&#X2019; thread. To choose a different
thread, call this function from the desired &#X2018;main&#X2019; thread. The calling
thread must have an <TT>omni_thread</TT> associated with it (i.e. it
must have been created by omnithread, or
<TT>omni_thread::create_dummy()</TT> must have been called). If it
does not, the function throws <TT>CORBA::INITIALIZE</TT>.</P><P>Note that calls are only actually dispatched to the &#X2018;main&#X2019; thread if
<TT>ORB::run()</TT> or <TT>ORB::perform_work()</TT> is called from that thread.</P><!--TOC section GIOP and interoperability options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc57">4.6</A>&#XA0;&#XA0;GIOP and interoperability options</H2><!--SEC END --><P>These options control omniORB&#X2019;s use of GIOP, and cover some areas
where omniORB can work around buggy behaviour by other ORBs.</P><P><TT>maxGIOPVersion</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1.2</TT></P><P>Choose the maximum GIOP version the ORB should support. Valid values
are 1.0, 1.1 and 1.2.</P><P><TT>giopMaxMsgSize</TT> &#XA0;&#XA0; <I>default</I> =
<TT>2097152</TT></P><P>The largest message, in bytes, that the ORB will send or receive, to
avoid resource starvation. If the limit is exceeded, a <TT>MARSHAL</TT>
exception is thrown. The size must be &gt;= 8192.</P><P><TT>strictIIOP</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>If true, be strict about interpretation of the IIOP specification; if
false, permit some buggy behaviour to pass.</P><P><TT>lcdMode</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If true, select &#X2018;Lowest Common Denominator&#X2019; mode. This disables
various IIOP and GIOP features that are known to cause problems with
some ORBs.</P><P><TT>tcAliasExpand</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>This flag is used to indicate whether TypeCodes associated with Anys
should have aliases removed. This functionality is included because
some ORBs will not recognise an Any containing a TypeCode with aliases
to be the same as the actual type contained in the Any. Note that
omniORB will always remove top-level aliases, but will not remove
aliases from TypeCodes that are members of other TypeCodes (e.g.
TypeCodes for members of structs etc.), unless <TT>tcAliasExpand</TT> is
set to 1. There is a performance penalty when inserting into an Any if
<TT>tcAliasExpand</TT> is set to 1.</P><P><TT>useTypeCodeIndirections</TT> &#XA0;&#XA0; <I>default</I> =
<TT>1</TT></P><P>TypeCode Indirections reduce the size of marshalled TypeCodes, and are
essential for recursive types, but some old ORBs do not support them.
Setting this flag to false prevents the use of indirections (and,
therefore, recursive TypeCodes).</P><P><TT>acceptMisalignedTcIndirections</TT> &#XA0;&#XA0; <I>default</I> =
<TT>0</TT></P><P>If true, try to fix a mis-aligned indirection in a typecode. This is
used to work around a bug in some old versions of Visibroker&#X2019;s Java
ORB.</P><!--TOC section System Exception Handlers-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc58">4.7</A>&#XA0;&#XA0;System Exception Handlers</H2><!--SEC END --><P>By default, all system exceptions that are raised during an operation
invocation, with the exception of some cases of
<TT>CORBA::TRANSIENT</TT>, are propagated to the application code. Some
applications may prefer to trap these exceptions within the proxy
objects so that the application logic does not have to deal with the
error condition. For example, when a <TT>CORBA::COMM_FAILURE</TT> is
received, an application may just want to retry the invocation until
it finally succeeds. This approach is useful for objects that are
persistent and have idempotent operations.</P><P>omniORB provides a set of functions to install exception handlers.
Once they are installed, proxy objects will call these handlers when
the associated system exceptions are raised by the ORB runtime.
Handlers can be installed for <TT>CORBA::TRANSIENT</TT>,
<TT>CORBA::COMM_FAILURE</TT> and <TT>CORBA::SystemException</TT>. This
last handler covers all system exceptions other than the two covered
by the first two handlers. An exception handler can be installed for
individual proxy objects, or it can be installed for all proxy objects
in the address space.</P><!--TOC subsection Minor codes-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc59">4.7.1</A>&#XA0;&#XA0;Minor codes</H3><!--SEC END --><P>omniORB makes extensive use of exception minor codes to indicate the
specific circumstances surrounding a system exception. The file
<TT>include/omniORB4/minorCode.h</TT> contains definitions of all the
minor codes used in omniORB, covering codes allocated in the CORBA
specification, and ones specific to omniORB. In compilers with
namespace support, the minor code constants appear in namespace
<TT>omni</TT>; otherwise they are in the global scope.</P><P>Applications can use minor codes to adjust their behaviour according
to the condition, e.g.</P><DIV CLASS="lstlisting"><B>try</B> {
  ...
}
<B>catch</B> (CORBA::TRANSIENT&amp; ex) {
  <B>if</B> (ex.minor() == omni::TRANSIENT_ConnectFailed) {
    <I>// retry with a different object reference...</I>
  }
  <B>else</B> {
    <I>// print an error message...</I>
  }
}</DIV><!--TOC subsection CORBA::TRANSIENT handlers-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc60">4.7.2</A>&#XA0;&#XA0;CORBA::TRANSIENT handlers</H3><!--SEC END --><P><TT>TRANSIENT</TT> exceptions can occur in many circumstances. One
circumstance is as follows:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">The client invokes on an object reference.
</LI><LI CLASS="li-enumerate">The object replies with a <TT>LOCATION_FORWARD</TT> message.
</LI><LI CLASS="li-enumerate">The client caches the new location and retries to the new location.
</LI><LI CLASS="li-enumerate">Time passes...
</LI><LI CLASS="li-enumerate">The client tries to invoke on the object again, using the
cached, forwarded location. 
</LI><LI CLASS="li-enumerate">The attempt to contact the object fails.
</LI><LI CLASS="li-enumerate">The ORB runtime resets the location cache and throws a
<TT>TRANSIENT</TT> exception with minor code
<TT>TRANSIENT_FailedOnForwarded</TT>.</LI></OL><P>In this situation, the default <TT>TRANSIENT</TT> exception handler
retries the call, using the object&#X2019;s original location. If the retry
results in another <TT>LOCATION_FORWARD</TT>, to the same or a
different location, and <EM>that</EM> forwarded location fails
immediately, the <TT>TRANSIENT</TT> exception will occur again, and the
pattern will repeat. With repeated exceptions, the handler starts
adding delays before retries, with exponential back-off.</P><P>In all other circumstances, the default <TT>TRANSIENT</TT> handler just
passes the exception on to the caller.</P><P>Applications can override the default behaviour by installing their
own exception handler. The API to do so is summarised below:</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {

  <B>typedef</B> CORBA::Boolean
  (*transientExceptionHandler_t)(<B>void</B>* cookie,
                                 CORBA::ULong n_retries,
                                 <B>const</B> CORBA::TRANSIENT&amp; ex);

  <B>void</B>
  installTransientExceptionHandler(<B>void</B>* cookie,
                                   transientExceptionHandler_t fn);

  <B>void</B>
  installTransientExceptionHandler(CORBA::Object_ptr obj,
                                   <B>void</B>* cookie,
                                   transientExceptionHandler_t fn);
}</DIV><P>The overloaded function <TT>installTransientExceptionHandler()</TT> can be
used to install the exception handlers for <TT>CORBA::TRANSIENT</TT>.
Two forms are available: the first form installs an exception handler
for all object references except for those which have an exception
handler installed by the second form, which takes an additional
argument to identify the target object reference. The argument
<TT>cookie</TT> is an opaque pointer which will be passed on by the ORB
when it calls the exception handler.</P><P>An exception handler will be called by proxy objects with three
arguments. The <TT>cookie</TT> is the opaque pointer registered by
<TT>installTransientExceptionHandler()</TT>. The argument
<TT>n_retries</TT> is the number of times the proxy has called this
handler for the same invocation. The argument <TT>ex</TT> is the value
of the exception caught. The exception handler is expected to do
whatever is appropriate and return a boolean value. If the return
value is TRUE(1), the proxy object retries the operation. If the
return value is FALSE(0), the original exception is propagated into
the application code. In the case of a <TT>TRANSIENT</TT> exception due
to a failed location forward, the exception propagated to the
application is the <EM>original</EM> exception that caused the
<TT>TRANSIENT</TT> (e.g. a <TT>COMM_FAILURE</TT> or
<TT>OBJECT_NOT_EXIST</TT>), rather than the <TT>TRANSIENT</TT>
exception<SUP><A NAME="text14" HREF="#note14">1</A></SUP>.</P><P>The following sample code installs a simple exception handler for all
objects and for a specific object:</P><DIV CLASS="lstlisting">CORBA::Boolean my_transient_handler1 (<B>void</B>* cookie,
                                      CORBA::ULong retries,
                                      <B>const</B> CORBA::TRANSIENT&amp; ex)
{
   cerr &lt;&lt; "transient handler 1 called." &lt;&lt; endl;
   <B>return</B> 1;           <I>// retry immediately.</I>
}

CORBA::Boolean my_transient_handler2 (<B>void</B>* cookie,
                                      CORBA::ULong retries,
                                      <B>const</B> CORBA::TRANSIENT&amp; ex)
{
   cerr &lt;&lt; "transient handler 2 called." &lt;&lt; endl;
   <B>return</B> 1;           <I>// retry immediately.</I>
}


<B>static</B> Echo_ptr myobj;

<B>void</B> installhandlers()
{
   omniORB::installTransientExceptionHandler(0,my_transient_handler1);
   <I>// All proxy objects will call my_transient_handler1 from now on.</I>

   omniORB::installTransientExceptionHandler(myobj,0,my_transient_handler2);
   <I>// The proxy object of myobj will call my_transient_handler2 from now on.</I>
}</DIV><!--TOC subsection CORBA::COMM_FAILURE-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc61">4.7.3</A>&#XA0;&#XA0;CORBA::COMM_FAILURE</H3><!--SEC END --><P>If the ORB has successfully contacted an object at some point, and
access to it subsequently fails (and the condition for
<TT>TRANSIENT</TT> described above does not occur), the ORB raises a
<TT>CORBA::COMM_FAILURE</TT> exception.</P><P>The default behaviour of the proxy objects is to propagate this
exception to the application. Applications can override the default
behaviour by installing their own exception handlers. The API to do so
is summarised below:</P><DIV CLASS="lstlisting"><B>typedef</B> CORBA::Boolean
(*commFailureExceptionHandler_t)(<B>void</B>* cookie,
                                 CORBA::ULong n_retries,
                                 <B>const</B> CORBA::COMM_FAILURE&amp; ex);

<B>void</B>
installCommFailureExceptionHandler(<B>void</B>* cookie,
                                   commFailureExceptionHandler_t fn);

<B>void</B>
installCommFailureExceptionHandler(CORBA::Object_ptr obj,
                                   <B>void</B>* cookie,
                                   commFailureExceptionHandler_t fn);</DIV><P>The functions are equivalent to their counterparts for
<TT>CORBA::TRANSIENT</TT>.</P><!--TOC subsection CORBA::SystemException-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc62">4.7.4</A>&#XA0;&#XA0;CORBA::SystemException</H3><!--SEC END --><P>If a system exceptions other than <TT>TRANSIENT</TT> or
<TT>COMM_FAILURE</TT> occurs, the default behaviour of the proxy
objects is to propagate this exception to the application.
Applications can override the default behaviour by installing their
own exception handlers. The API to do so is summarised below:</P><DIV CLASS="lstlisting"><B>typedef</B> CORBA::Boolean
(*systemExceptionHandler_t)(<B>void</B>* cookie,
                            CORBA::ULong n_retries,
                            <B>const</B> CORBA::SystemException&amp; ex);

<B>void</B>
installSystemExceptionHandler(<B>void</B>* cookie,
                              systemExceptionHandler_t fn);

<B>void</B>
installSystemExceptionHandler(CORBA::Object_ptr obj,
                              <B>void</B>* cookie,
                              systemExceptionHandler_t fn);</DIV><P>The functions are equivalent to their counterparts for
<TT>CORBA::TRANSIENT</TT>.</P><!--TOC section Location forwarding-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc63">4.8</A>&#XA0;&#XA0;Location forwarding</H2><!--SEC END --><P>
<A NAME="sec:locationForward"></A></P><P>Any CORBA operation invocation can return a <TT>LOCATION_FORWARD</TT>
message to the caller, indicating that it should retry the invocation
on a new object reference. The standard allows ServantManagers to
trigger <TT>LOCATION_FORWARD</TT>s by raising the
<TT>PortableServer::ForwardRequest</TT> exception, but it does not
provide a similar mechanism for normal servants. omniORB provides the
<TT>omniORB::LOCATION_FORWARD</TT> exception for this purpose. It
can be thrown by any operation implementation.</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {
  <B>class</B> LOCATION_FORWARD {
  <B>public</B>:
    LOCATION_FORWARD(CORBA::Object_ptr objref);
  };
};</DIV><P>The exception object consumes the object reference it is
passed.</P><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note14" HREF="#text14">1</A></DT><DD CLASS="dd-thefootnotes">This is a change from omniORB 4.0 and earlier,
where it was the <TT>TRANSIENT</TT> exception that was propagated to the
application.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter The IDL compiler-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc64">Chapter&#XA0;5</A>&#XA0;&#XA0;The IDL compiler</H1><!--SEC END --><P>
<A NAME="chap:omniidl"></A></P><P>omniORB&#X2019;s IDL compiler is called omniidl. It consists of a generic
front-end parser written in C++, and a number of back-ends written in
Python. omniidl is very strict about IDL validity, so you may find
that it reports errors in IDL which compiles fine with other IDL
compilers.</P><P>The general form of an omniidl command line is:</P><BLOCKQUOTE CLASS="quote"> <TT>omniidl </TT>[<I>options</I>]<TT> -b</TT>&lt;<I>back-end</I>&gt;<TT> </TT>[<I>back-end options</I>]<TT> </TT>&lt;<I>file 1</I>&gt;<TT> </TT>&lt;<I>file 2</I>&gt;<TT> </TT>&#X2026;</BLOCKQUOTE><!--TOC section Common options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc65">5.1</A>&#XA0;&#XA0;Common options</H2><!--SEC END --><P>The following options are common to all back-ends:</P><TABLE border=0 cellspacing=0 cellpadding=0><TR><TD ALIGN=left NOWRAP></TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-b</TT><I>back-end</I></TD><TD ALIGN=left NOWRAP>Run the specified back-end. For the C++ ORB, use <TT>-bcxx</TT>.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-D</TT><I>name</I>[<TT>=</TT><I>value</I>]</TD><TD ALIGN=left NOWRAP>Define <I>name</I> for the preprocessor.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-U</TT><I>name</I></TD><TD ALIGN=left NOWRAP>Undefine <I>name</I> for the preprocessor.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-I</TT><I>dir</I></TD><TD ALIGN=left NOWRAP>Include <I>dir</I> in the preprocessor search path.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-E</TT></TD><TD ALIGN=left NOWRAP>Only run the preprocessor, sending its output to stdout.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Y</TT><I>cmd</I></TD><TD ALIGN=left NOWRAP>Use <I>cmd</I> as the preprocessor, rather than the normal C
preprocessor.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-N</TT></TD><TD ALIGN=left NOWRAP>Do not run the preprocessor.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-T</TT></TD><TD ALIGN=left NOWRAP>Use a temporary file, not a pipe, for preprocessor output.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wp</TT><I>arg</I>[,<I>arg</I>&#X2026;]</TD><TD ALIGN=left NOWRAP>Send arguments to the preprocessor.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wb</TT><I>arg</I>[,<I>arg</I>&#X2026;]</TD><TD ALIGN=left NOWRAP>Send arguments to the back-end.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-nf</TT></TD><TD ALIGN=left NOWRAP>Do not warn about unresolved forward declarations.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-k</TT></TD><TD ALIGN=left NOWRAP>Keep comments after declarations, to be used by some back-ends.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-K</TT></TD><TD ALIGN=left NOWRAP>Keep comments before declarations, to be used by some back-ends.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-C</TT><I>dir</I></TD><TD ALIGN=left NOWRAP>Change directory to <I>dir</I> before writing output files.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-d</TT></TD><TD ALIGN=left NOWRAP>Dump the parsed IDL then exit, without running a back-end.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-p</TT><I>dir</I></TD><TD ALIGN=left NOWRAP>Use <I>dir</I> as a path to find omniidl back-ends.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-V</TT></TD><TD ALIGN=left NOWRAP>Print version information then exit.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-u</TT></TD><TD ALIGN=left NOWRAP>Print usage information.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-v</TT></TD><TD ALIGN=left NOWRAP>Verbose: trace compilation stages.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
</TD></TR>
</TABLE><P>Most of these options are self explanatory, but some are not
so obvious.</P><!--TOC subsection Preprocessor interactions-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc66">5.1.1</A>&#XA0;&#XA0;Preprocessor interactions</H3><!--SEC END --><P>IDL is processed by the C preprocessor before omniidl parses it.
omniidl always uses the GNU C preprocessor (which it builds with the
name omnicpp). The <TT>-D</TT>, <TT>-U</TT>, and <TT>-I</TT>
options are just sent to the preprocessor. Note that the current
directory is not on the include search path by default&#X2014;use
&#X2018;<TT>-I.</TT>&#X2019; for that. The <TT>-Y</TT> option can be used to
specify a different preprocessor to omnicpp. Beware that line
directives inserted by other preprocessors are likely to confuse
omniidl.</P><!--TOC subsubsection Windows 9x-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR --><A NAME="htoc67">5.1.1.1</A>&#XA0;&#XA0;Windows 9x</H4><!--SEC END --><P>The output from the C preprocessor is normally fed to the omniidl
parser through a pipe. On some Windows 98 machines (but not all!) the
pipe does not work, and the preprocessor output is echoed to the
screen. When this happens, the omniidl parser sees an empty file, and
produces useless stub files with strange long names. To avoid the
problem, use the &#X2018;<TT>-T</TT>&#X2019; option to create a temporary file
between the two stages.</P><!--TOC subsection Forward-declared interfaces-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc68">5.1.2</A>&#XA0;&#XA0;Forward-declared interfaces</H3><!--SEC END --><P>If you have an IDL file like:</P><DIV CLASS="lstlisting"><B>interface</B> I;
<B>interface</B> J {
  <B>attribute</B> I the_I;
};</DIV><P>then omniidl will normally issue a warning:</P><PRE CLASS="verbatim">  test.idl:1: Warning: Forward declared interface `I' was never
  fully defined
</PRE><P>It is illegal to declare such IDL in isolation, but it
<EM>is</EM> valid to define interface <TT>I</TT> in a separate file. If
you have a lot of IDL with this sort of construct, you will drown
under the warning messages. Use the <TT>-nf</TT> option to suppress
them.</P><!--TOC subsection Comments-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc69">5.1.3</A>&#XA0;&#XA0;Comments</H3><!--SEC END --><P>By default, omniidl discards comments in the input IDL. However, with
the <TT>-k</TT> and <TT>-K</TT> options, it preserves the comments
for use by the back-ends. The C++ back-end ignores this information,
but it is relatively easy to write new back-ends which <EM>do</EM> make
use of comments.</P><P>The two different options relate to how comments are attached to
declarations within the IDL. Given IDL like:</P><DIV CLASS="lstlisting"><B>interface</B> I {
  <B>void</B> op1();
  <I>// A comment</I>
  <B>void</B> op2();
};</DIV><P>the <TT>-k</TT> flag will attach the comment to <TT>op1()</TT>;
the <TT>-K</TT> flag will attach it to <TT>op2()</TT>.</P><!--TOC section C++ back-end options-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc70">5.2</A>&#XA0;&#XA0;C++ back-end options</H2><!--SEC END --><P>When you specify the C++ back-end (with <TT>-bcxx</TT>), the
following <TT>-Wb</TT> options are available. Note that the
<TT>-Wb</TT> options must be specified <EM>after</EM> the
<TT>-bcxx</TT> option, so omniidl knows which back-end to give the
arguments to.</P><TABLE border=0 cellspacing=0 cellpadding=0><TR><TD ALIGN=left NOWRAP></TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbh=</TT><I>suffix</I></TD><TD ALIGN=left NOWRAP>Use <I>suffix</I> for generated header files. Default
&#X2018;<TT>.hh</TT>&#X2019;.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbs=</TT><I>suffix</I></TD><TD ALIGN=left NOWRAP>Use <I>suffix</I> for generated stub files. Default
&#X2018;<TT>SK.cc</TT>.&#X2019;</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbd=</TT><I>suffix</I></TD><TD ALIGN=left NOWRAP>Use <I>suffix</I> for generated dynamic files. Default
&#X2018;<TT>DynSK.cc</TT>.&#X2019;</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wba</TT></TD><TD ALIGN=left NOWRAP>Generate stubs for TypeCode and Any.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbinline</TT></TD><TD ALIGN=left NOWRAP>Output stubs for <TT>#include</TT>d IDL files in line with the
main file.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbtp</TT></TD><TD ALIGN=left NOWRAP>Generate &#X2018;tie&#X2019; implementation skeletons.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbtf</TT></TD><TD ALIGN=left NOWRAP>Generate flattened &#X2018;tie&#X2019; implementation skeletons.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbsplice-modules</TT></TD><TD ALIGN=left NOWRAP>Splice together multiply-opened modules into one.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbexample</TT></TD><TD ALIGN=left NOWRAP>Generate example implementation code.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-WbF</TT></TD><TD ALIGN=left NOWRAP>Generate code fragments (for experts only).</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-WbBOA</TT></TD><TD ALIGN=left NOWRAP>Generate BOA compatible skeletons.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbold</TT></TD><TD ALIGN=left NOWRAP>Generate old CORBA 2.1 signatures for skeletons.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbold_prefix</TT></TD><TD ALIGN=left NOWRAP>Map C++ reserved words with prefix &#X2018;<TT>_</TT>&#X2019; rather than
&#X2018;<TT>_cxx_</TT>&#X2019;.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbkeep_inc_path</TT></TD><TD ALIGN=left NOWRAP>Preserve IDL &#X2018;<TT>#include</TT>&#X2019; paths in generated
	&#X2018;<TT>#include</TT>&#X2019; directives.</TD></TR>
<TR><TD ALIGN=left NOWRAP>
<TT>-Wbuse_quotes</TT></TD><TD ALIGN=left NOWRAP>Use quotes in &#X2018;<TT>#include</TT>&#X2019; directives 
(e.g. <TT>"foo"</TT> rather than <TT>&lt;foo&gt;</TT>.)</TD></TR>
</TABLE><P>Again, most of these are self-explanatory.</P><!--TOC subsection Stub / skeleton files-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc71">5.2.1</A>&#XA0;&#XA0;Stub / skeleton files</H3><!--SEC END --><P>By default, omniidl separates the normal stub and skeleton file (the
<TT>SK.cc</TT> file) from the &#X2018;dynamic&#X2019; stubs (the <TT>DynSK.cc</TT>
file), so applications that do not need support for Any and TypeCode
for a particular IDL file do not waste space with unnecessary
definitions. It is possible to output both the normal stubs <EM>and</EM>
the dynamic stubs to a single file, by simply specifying the same
extension for both files. This command places both the normal stubs
and the dynamic stubs in <TT>aSK.cc</TT>:</P><BLOCKQUOTE CLASS="quote">
<TT>omniidl -bcxx -Wba -Wbd=SK.cc a.idl</TT>
</BLOCKQUOTE><!--TOC subsection Module splicing-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc72">5.2.2</A>&#XA0;&#XA0;Module splicing</H3><!--SEC END --><P>On ancient C++ compilers without namespace support, IDL modules map to
C++ classes, and so cannot be reopened. For some IDL, it is possible
to &#X2018;splice&#X2019; reopened modules on to the first occurrence of the module,
so all module definitions are in a single class. It is possible in
this sort of situation:</P><DIV CLASS="lstlisting"><B>module</B> M1 {
  <B>interface</B> I {};
};
<B>module</B> M2 {
  <B>interface</B> J {
    <B>attribute</B> M1::I ok;
  };
};
<B>module</B> M1 {
  <B>interface</B> K {
    <B>attribute</B> I still_ok;
  };
};</DIV><P>but not if there are cross-module dependencies:</P><DIV CLASS="lstlisting"><B>module</B> M1 {
  <B>interface</B> I {};
};
<B>module</B> M2 {
  <B>interface</B> J {
    <B>attribute</B> M1::I ok;
  };
};
<B>module</B> M1 {
  <B>interface</B> K {
    <B>attribute</B> M2::J oh_dear;
  };
};</DIV><P>In both of these cases, the <TT>-Wbsplice-modules</TT>
option causes omniidl to put all of the definitions for module
<TT>M1</TT> into a single C++ class. For the first case, this will work
fine. For the second case, class <TT>M1::K</TT> will contain a reference
to <TT>M2::J</TT>, which has not yet been defined; the C++ compiler will
complain.</P><!--TOC subsection Flattened tie classes-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc73">5.2.3</A>&#XA0;&#XA0;Flattened tie classes</H3><!--SEC END --><P>Another problem with mapping IDL modules to C++ classes arises with
tie templates. The C++ mapping says that for the interface
<TT>M::I</TT>, the C++ tie template class should be named
<TT>POA_M::I_tie</TT>. However, since template classes cannot be
declared inside other classes, this naming scheme cannot be used with
compilers without namespace support.</P><P>The standard solution is to produce &#X2018;flattened&#X2019; tie class names, using
the <TT>-Wbtf</TT> command line argument. With that flag, the
template class is declared at global scope with the name
<TT>POA_M_I_tie</TT>. i.e. all occurrences of &#X2018;<TT>::</TT>&#X2019; are
replaced by &#X2018;<TT>_</TT>&#X2019;.</P><!--TOC subsection Generating example implementations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc74">5.2.4</A>&#XA0;&#XA0;Generating example implementations</H3><!--SEC END --><P>If you use the <TT>-Wbexample</TT> flag, omniidl will generate an
example implementation file as well as the stubs and skeletons. For
IDL file <TT>foo.idl</TT>, the example code is written to
<TT>foo_i.cc</TT>. The example file contains class and method
declarations for the operations of all interfaces in the IDL file,
along with a <TT>main()</TT> function which creates an instance of each
object. You still have to fill in the operation implementations, of
course.</P><!--TOC section Examples-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc75">5.3</A>&#XA0;&#XA0;Examples</H2><!--SEC END --><P>Generate the C++ headers and stubs for a file <TT>a.idl</TT>:</P><BLOCKQUOTE CLASS="quote">
<TT>omniidl -bcxx a.idl</TT>
</BLOCKQUOTE><P>Generate with Any support:</P><BLOCKQUOTE CLASS="quote">
<TT>omniidl -bcxx -Wba a.idl</TT>
</BLOCKQUOTE><P>As above, but also generate Python stubs (assuming omniORBpy
is installed):</P><BLOCKQUOTE CLASS="quote">
<TT>omniidl -bcxx -Wba -bpython a.idl</TT>
</BLOCKQUOTE><P>Just check the IDL files for validity, generating no output:</P><BLOCKQUOTE CLASS="quote">
<TT>omniidl a.idl b.idl</TT>
</BLOCKQUOTE><!--TOC chapter Interoperable Naming Service-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc76">Chapter&#XA0;6</A>&#XA0;&#XA0;Interoperable Naming Service</H1><!--SEC END --><P>
<A NAME="chap:ins"></A></P><P>omniORB supports the Interoperable Naming Service (INS). The following
is a summary of its facilities.</P><!--TOC section Object URIs-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc77">6.1</A>&#XA0;&#XA0;Object URIs</H2><!--SEC END --><P>As well as accepting IOR-format strings, <TT>ORB::string_to_object()</TT>
also supports two Uniform Resource Identifier (URI)&#XA0;[<A HREF="#rfc2396">BLFIM98</A>]
formats, which can be used to specify objects in a convenient
human-readable form. IOR-format strings are now also considered URIs.</P><!--TOC subsection corbaloc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc78">6.1.1</A>&#XA0;&#XA0;corbaloc</H3><!--SEC END --><P><TT>corbaloc</TT> URIs allow you to specify object references which
can be contacted by IIOP, or found through
<TT>ORB::resolve_initial_references()</TT>. To specify an IIOP object
reference, you use a URI of the form:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc:iiop:</TT>&lt;<I>host</I>&gt;<TT>:</TT>&lt;<I>port</I>&gt;<TT>/</TT>&lt;<I>object key</I>&gt;
</BLOCKQUOTE><P>for example:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc:iiop:myhost.example.com:1234/MyObjectKey</TT>
</BLOCKQUOTE><P>which specifies an object with key &#X2018;MyObjectKey&#X2019; within a
process running on myhost.example.com listening on port 1234. Object
keys containing non-ASCII characters can use the standard URI %
escapes:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc:iiop:myhost.example.com:1234/My</TT><TT>%</TT><TT>efObjectKey</TT>
</BLOCKQUOTE><P>denotes an object key with the value 239 (hex ef) in the
third octet.</P><P>The protocol name &#X2018;<TT>iiop</TT>&#X2019; can be abbreviated to the empty
string, so the original URI can be written:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc::myhost.example.com:1234/MyObjectKey</TT>
</BLOCKQUOTE><P>The IANA has assigned port number 2809<SUP><A NAME="text15" HREF="#note15">1</A></SUP> for use by <TT>corbaloc</TT>, so if
the server is listening on that port, you can leave the port number
out. The following two URIs refer to the same object:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc::myhost.example.com:2809/MyObjectKey</TT><BR>
<TT>corbaloc::myhost.example.com/MyObjectKey</TT>
</BLOCKQUOTE><P>You can specify an object which is available at more than
one location by separating the locations with commas:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc::myhost.example.com,:localhost:1234/MyObjectKey</TT>
</BLOCKQUOTE><P>Note that you must restate the protocol for each address,
hence the &#X2018;<TT>:</TT>&#X2019; before &#X2018;<TT>localhost</TT>&#X2019;. It could
equally have been written &#X2018;<TT>iiop:localhost</TT>&#X2019;.</P><P>You can also specify an IIOP version number:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc::1.2@myhost.example.com/MyObjectKey</TT>
</BLOCKQUOTE><P>Specifying IIOP versions above 1.0 is slightly risky since higher
versions make use of various information stored in IORs that is not
present in a corbaloc URI. It is generally best to contact initial
corbaloc objects with IIOP 1.0, and rely on higher versions for all
other object references.</P><P>Alternatively, to use <TT>resolve_initial_references()</TT>, you
use a URI of the form:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaloc:rir:/NameService</TT>
</BLOCKQUOTE><!--TOC subsection corbaname-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc79">6.1.2</A>&#XA0;&#XA0;corbaname</H3><!--SEC END --><P>
<A NAME="sec:corbaname"></A></P><P><TT>corbaname</TT> URIs cause <TT>string_to_object()</TT> to look-up a
name in a CORBA Naming service. They are an extension of the
<TT>corbaloc</TT> syntax:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaname:</TT>&lt;<I>corbaloc location</I>&gt;<TT>/</TT>&lt;<I>object key</I>&gt;<TT>#</TT>&lt;<I>stringified name</I>&gt;
</BLOCKQUOTE><P>for example:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaname::myhost/NameService#project/example/echo.obj</TT><BR>
<TT>corbaname:rir:/NameService#project/example/echo.obj</TT>
</BLOCKQUOTE><P>The object found with the <TT>corbaloc</TT>-style portion
must be of type <TT>CosNaming::NamingContext</TT>, or something
derived from it. If the object key (or <TT>rir</TT> name) is
&#X2018;<TT>NameService</TT>&#X2019;, it can be left out:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaname::myhost#project/example/echo.obj</TT><BR>
<TT>corbaname:rir:#project/example/echo.obj</TT>
</BLOCKQUOTE><P>The stringified name portion can also be left out, in which
case the URI denotes the <TT>CosNaming::NamingContext</TT> which would
have been used for a look-up:</P><BLOCKQUOTE CLASS="quote">
<TT>corbaname::myhost.example.com</TT><BR>
<TT>corbaname:rir:</TT>
</BLOCKQUOTE><P>The first of these examples is the easiest way of specifying
the location of a naming service.</P><!--TOC section Configuring resolve_initial_references-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc80">6.2</A>&#XA0;&#XA0;Configuring resolve_initial_references</H2><!--SEC END --><P>
<A NAME="sec:insargs"></A></P><P>The INS specifies two standard command line arguments which provide a
portable way of configuring <TT>ORB::resolve_initial_references()</TT>:</P><!--TOC subsection ORBInitRef-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc81">6.2.1</A>&#XA0;&#XA0;ORBInitRef</H3><!--SEC END --><P><TT>-ORBInitRef</TT> takes an argument of the form
&lt;<I>ObjectId</I>&gt;<TT>=</TT>&lt;<I>ObjectURI</I>&gt;. So, for example,
with command line arguments of:</P><BLOCKQUOTE CLASS="quote">
<TT>-ORBInitRef NameService=corbaname::myhost.example.com</TT>
</BLOCKQUOTE><P><TT>resolve_initial_references("NameService")</TT> will
return a reference to the object with key &#X2018;NameService&#X2019; available on
myhost.example.com, port 2809. Since IOR-format strings are considered
URIs, you can also say things like:</P><BLOCKQUOTE CLASS="quote">
<TT>-ORBInitRef NameService=IOR:00ff...</TT>
</BLOCKQUOTE><!--TOC subsection ORBDefaultInitRef-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc82">6.2.2</A>&#XA0;&#XA0;ORBDefaultInitRef</H3><!--SEC END --><P><TT>-ORBDefaultInitRef</TT> provides a prefix string which is used to
resolve otherwise unknown names. When
<TT>resolve_initial_references()</TT> is unable to resolve a name which
has been specifically configured (with <TT>-ORBInitRef</TT>), it
constructs a string consisting of the default prefix, a &#X2018;<TT>/</TT>&#X2019;
character, and the name requested. The string is then fed to
<TT>string_to_object()</TT>. So, for example, with a command line of:</P><BLOCKQUOTE CLASS="quote">
<TT>-ORBDefaultInitRef corbaloc::myhost.example.com</TT>
</BLOCKQUOTE><P>a call to <TT>resolve_initial_references("MyService")</TT>
will return the object reference denoted by
&#X2018;<TT>corbaloc::myhost.example.com/MyService</TT>&#X2019;.</P><P>Similarly, a <TT>corbaname</TT> prefix can be used to cause
look-ups in the naming service. Note, however, that since a
&#X2018;<TT>/</TT>&#X2019; character is always added to the prefix, it is
impossible to specify a look-up in the root context of the naming
service&#X2014;you have to use a sub-context, like:</P><BLOCKQUOTE CLASS="quote">
<TT>-ORBDefaultInitRef corbaname::myhost.example.com#services</TT>
</BLOCKQUOTE><!--TOC section omniNames-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc83">6.3</A>&#XA0;&#XA0;omniNames</H2><!--SEC END --><!--TOC subsection NamingContextExt-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc84">6.3.1</A>&#XA0;&#XA0;NamingContextExt</H3><!--SEC END --><P>omniNames supports the extended <TT>CosNaming::NamingContextExt</TT>
interface:</P><DIV CLASS="lstlisting"><B>module</B> CosNaming {
  <B>interface</B> NamingContextExt : NamingContext {
    <B>typedef</B> <B>string</B> StringName;
    <B>typedef</B> <B>string</B> Address;
    <B>typedef</B> <B>string</B> URLString;

    StringName  to_string(<B>in</B> Name n)        <B>raises</B>(InvalidName);
    Name        to_name  (<B>in</B> StringName sn) <B>raises</B>(InvalidName);

    <B>exception</B> InvalidAddress {};

    URLString   to_url(<B>in</B> Address addr, <B>in</B> StringName sn)
      <B>raises</B>(InvalidAddress, InvalidName);

    <B>Object</B>      resolve_str(<B>in</B> StringName n)
      <B>raises</B>(NotFound, CannotProceed, InvalidName, AlreadyBound);
  };
};</DIV><P><TT>to_string()</TT> and <TT>to_name()</TT> convert from <TT>CosNaming::Name</TT>
sequences to flattened strings and vice-versa. Note that calling
these operations involves remote calls to the naming service, so they
are not particularly efficient. You can use the omniORB specific local
<TT>omniURI::nameToString()</TT> and <TT>omniURI::stringToName()</TT>
functions instead.</P><P>A <TT>CosNaming::Name</TT> is stringified by separating name components
with &#X2018;<TT>/</TT>&#X2019; characters. The <TT>kind</TT> and <TT>id</TT> fields of
each component are separated by &#X2018;<TT>.</TT>&#X2019; characters. If the
<TT>kind</TT> field is empty, the representation has no trailing
&#X2018;<TT>.</TT>&#X2019;; if the <TT>id</TT> is empty, the representation starts
with a &#X2018;<TT>.</TT>&#X2019; character; if both <TT>id</TT> and <TT>kind</TT>
are empty, the representation is just a &#X2018;<TT>.</TT>&#X2019;. The backslash
&#X2018;<TT>\</TT>&#X2019; is used to escape the meaning of
&#X2018;<TT>/</TT>&#X2019;, &#X2018;<TT>.</TT>&#X2019; and &#X2018;<TT>\</TT>&#X2019; itself.</P><P><TT>to_url()</TT> takes a <TT>corbaloc</TT> style address and key string
(but without the <TT>corbaloc:</TT> part), and a stringified name,
and returns a <TT>corbaname</TT> URI (incorrectly called a URL)
string, having properly escaped any invalid characters. The
specification does not make it clear whether or not the address string
should also be escaped by the operation; omniORB does not escape
it. For this reason, it is best to avoid calling <TT>to_url()</TT> if the
address part contains escapable characters. omniORB provides the
equivalent local function <TT>omniURI::addrAndNameToURI()</TT>.</P><P><TT>resolve_str()</TT> is equivalent to calling <TT>to_name()</TT> followed by
the inherited <TT>resolve()</TT> operation. There are no string-based
equivalents of the various bind operations.</P><!--TOC subsection Use with corbaname-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc85">6.3.2</A>&#XA0;&#XA0;Use with corbaname</H3><!--SEC END --><P>To make it easy to use omniNames with <TT>corbaname</TT> URIs, it
starts with the default port of 2809, and an object key of
&#X2018;<TT>NameService</TT>&#X2019; for the root naming context.</P><!--TOC section omniMapper-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc86">6.4</A>&#XA0;&#XA0;omniMapper</H2><!--SEC END --><P>omniMapper is a simple daemon which listens on port 2809 (or any other
port), and redirects IIOP requests for configured object keys to
associated persistent object references. It can be used to make a
naming service (even an old non-INS aware version of omniNames or
other ORB&#X2019;s naming service) appear on port 2809 with the object key
&#X2018;<TT>NameService</TT>&#X2019;. The same goes for any other service you may
wish to specify, such as an interface repository. omniMapper is
started with a command line of:</P><BLOCKQUOTE CLASS="quote">
<TT>omniMapper [-port </TT>&lt;<I>port</I>&gt;<TT>] [-config </TT>&lt;<I>config file</I>&gt;<TT>] [-v]</TT>
</BLOCKQUOTE><P>The <TT>-port</TT> option allows you to choose a port other
than 2809 to listen on. The <TT>-config</TT> option specifies a
location for the configuration file. The default name is
<TT>/etc/omniMapper.cfg</TT>, or <TT>C:\omniMapper.cfg</TT> on
Windows. omniMapper does not normally print anything; the <TT>-v</TT>
option makes it verbose so it prints configuration information and a
record of the redirections it makes, to standard output.</P><P>The configuration file is very simple. Each line contains a string to
be used as an object key, some white space, and an IOR (or any valid
URI) that it will redirect that object key to. Comments should be
prefixed with a &#X2018;<TT>#</TT>&#X2019; character. For example:</P><BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim"># Example omniMapper.cfg
NameService         IOR:000f...
InterfaceRepository IOR:0100...
</PRE></BLOCKQUOTE><P>omniMapper can either be run on a single machine, in much the same way
as omniNames, or it can be run on <EM>every</EM> machine, with a common
configuration file. That way, each machine&#X2019;s omniORB configuration
file could contain the line:</P><BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">ORBDefaultInitRef corbaloc::localhost
</PRE></BLOCKQUOTE><!--TOC section Creating objects with simple object keys-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc87">6.5</A>&#XA0;&#XA0;Creating objects with simple object keys</H2><!--SEC END --><P>In normal use, omniORB creates object keys containing various
information including POA names and various non-ASCII characters.
Since object keys are supposed to be opaque, this is not usually a
problem. The INS breaks this opacity and requires servers to create
objects with human-friendly keys.</P><P>If you wish to make your objects available with human-friendly URIs,
there are two options. The first is to use omniMapper as described
above, in conjunction with a <TT>PERSISTENT</TT> POA. The second is to
create objects with the required keys yourself. You do this with a
special POA with the name &#X2018;<TT>omniINSPOA</TT>&#X2019;, acquired from
<TT>resolve_initial_references()</TT>. This POA has the <TT>USER_ID</TT>
and <TT>PERSISTENT</TT> policies, and the special property that the
object keys it creates contain only the object ids given to the POA,
and no other data. It is a normal POA in all other respects, so you
can activate/deactivate it, create children, and so on, in the usual
way.</P><P>Children of the omniINSPOA do not inherit its special properties of
creating simple object keys. If the omniINSPOA&#X2019;s policies are not
suitable for your application, you cannot create a POA with different
policies (such as single threading, for example), and still generate
simple object keys. Instead, you can activate a servant in the
omniINSPOA that uses location forwarding to redirect requests to
objects in a different POA.</P><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note15" HREF="#text15">1</A></DT><DD CLASS="dd-thefootnotes">Not 2089 as
printed in [<A HREF="#inschapters">OMG00</A>]!
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Interface Type Checking-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc88">Chapter&#XA0;7</A>&#XA0;&#XA0;Interface Type Checking</H1><!--SEC END --><P>
<A NAME="ch_intf"></A></P><P>This chapter describes the mechanism used by omniORB to ensure type
safety when object references are exchanged across the network. This
mechanism is handled completely within the ORB. There is no
programming interface visible at the application level. However, for
the sake of diagnosing the problem when there is a type violation, it
is useful to understand the underlying mechanism in order to interpret
the error conditions reported by the ORB.</P><!--TOC section Introduction-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc89">7.1</A>&#XA0;&#XA0;Introduction</H2><!--SEC END --><P>In GIOP/IIOP, an object reference is encoded as an Interoperable
Object Reference (IOR) when it is sent across a network connection.
The IOR contains a Repository ID (RepoId) and one or more
communication profiles. The communication profiles describe where and
how the object can be contacted. The RepoId is a string which uniquely
identifies the IDL interface of the object.</P><P>Unless the <TT>ID</TT> pragma is specified in the IDL, the ORB generates
the RepoId string in the so-called OMG IDL Format<SUP><A NAME="text16" HREF="#note16">1</A></SUP>. For instance, the RepoId for the <TT>Echo</TT>
interface used in the examples of chapter&#XA0;<A HREF="#chap:basic">2</A> is
<TT>IDL:Echo:1.0</TT>.</P><P>When interface inheritance is used in the IDL, the ORB always sends the
RepoId of the most derived interface. For example:</P><DIV CLASS="lstlisting">   <I>// IDL</I>
   <B>interface</B> A {
     ...
   };
   <B>interface</B> B : A {
     ...
   };
   <B>interface</B> C {
      <B>void</B> op(<B>in</B> A arg);
   };</DIV><DIV CLASS="lstlisting">   <I>// C++</I>
   C_ptr server;
   B_ptr objB;
   A_ptr objA = objB;
   server-&gt;op(objA);  <I>// Send B as A</I></DIV><P>In the example, the operation <TT>C::op()</TT> accepts an object reference
of type <TT>A</TT>. The real type of the reference passed to <TT>C::op()</TT>
is <TT>B</TT>, which inherits from <TT>A</TT>. In this case, the RepoId of
<TT>B</TT>, and not that of <TT>A</TT>, is sent across the network.</P><P>The GIOP/IIOP specification allows an ORB to send a null string in the
RepoId field of an IOR. It is up to the receiving end to work out the
real type of the object. omniORB never sends out null strings as
RepoIds, but it may receive null RepoIds from other ORBs. In that
case, it will use the mechanism described below to ensure type safety.</P><!--TOC section Interface Inheritance-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc90">7.2</A>&#XA0;&#XA0;Interface Inheritance</H2><!--SEC END --><P>When the ORB receives an IOR of interface type B when it expects the
type to be A, it must find out if B inherits from A. When the ORB has
no local knowledge of the type B, it must work out the type of B
dynamically.</P><P>The CORBA specification defines an Interface Repository (IR) from
which IDL interfaces can be queried dynamically. In the above
situation, the ORB could contact the IR to find out the type of B.
However, this approach assumes that an IR is always available and
contains the up-to-date information of all the interfaces used in the
domain. This assumption may not be valid in many applications.</P><P>An alternative is to use the <TT>_is_a()</TT> operation to work out the
actual type of an object. This approach is simpler and more robust
than the previous one because no 3rd party is involved, so this is
what omniORB does.</P><DIV CLASS="lstlisting"><B>class</B> Object{
    CORBA::Boolean _is_a(<B>const</B> <B>char</B>* type_id);
};</DIV><P>The <TT>_is_a()</TT> operation is part of the <TT>CORBA::Object</TT>
interface and must be implemented by every object. The input argument
is a RepoId. The function returns true(1) if the object is really an
instance of that type, including if that type is a base type of the
most derived type of that object.</P><P>In the situation above, the ORB would invoke the <TT>_is_a()</TT>
operation on the object and ask if the object is of type A
<EM>before</EM> it processes any application invocation on the object.</P><P>Notice that the <TT>_is_a()</TT> call is <EM>not</EM> performed when the IOR
is unmarshalled. It is performed just prior to the first application
invocation on the object. This leads to some interesting failure modes
if B reports that it is not an A. Consider the following example:</P><DIV CLASS="lstlisting"><I>// IDL</I>
<B>interface</B> A { ... };
<B>interface</B> B : A { ... };
<B>interface</B> D { ... };
<B>interface</B> C {
  A      op1();
  <B>Object</B> op2();
};</DIV><DIV CLASS="lstlisting"><FONT SIZE=1>   1</FONT> <I>// C++</I>
<FONT SIZE=1>   2</FONT> C_ptr objC;
<FONT SIZE=1>   3</FONT> A_ptr objA;
<FONT SIZE=1>   4</FONT> CORBA::Object_ptr objR;
<FONT SIZE=1>   5</FONT> 
<FONT SIZE=1>   6</FONT> objA =  objC-&gt;op1();
<FONT SIZE=1>   7</FONT> (<B>void</B>) objA-&gt;_non_existent();
<FONT SIZE=1>   8</FONT> 
<FONT SIZE=1>   9</FONT> objR =  objC-&gt;op2();
<FONT SIZE=1>  10</FONT> objA =  A::_narrow(objR);</DIV><P>If the stubs of A,B,C,D are linked into the executable and:</P><DL CLASS="description"><DT CLASS="dt-description">
<B>Case 1</B></DT><DD CLASS="dd-description"> <TT>C::op1()</TT> and <TT>C::op2()</TT> return a B. Lines 6&#X2013;10
complete successfully. The remote object is only contacted at line 7.</DD><DT CLASS="dt-description"><B>Case 2</B></DT><DD CLASS="dd-description"> <TT>C::op1()</TT> and <TT>C::op2()</TT> return a D. This condition
only occurs if the runtime of the remote end is buggy. Even though the
IDL definitions show that D is not derived from A, omniORB gives it
the benefit of the doubt, in case it actually has a more derived
interface that is derived from both A and D. At line 7, the object is
contacted to ask if it is an A. The answer is no, so a
<TT>CORBA::INV_OBJREF</TT> exception is raised. At line 10, the narrow
operation will fail, and objA will be set to nil.
</DD></DL><P>If only the stubs of A are linked into the executable and:</P><DL CLASS="description"><DT CLASS="dt-description">
<B>Case 1</B></DT><DD CLASS="dd-description"> <TT>C::op1()</TT> and <TT>C::op2()</TT> return a B. Lines 6&#X2013;10
complete successfully. When lines 7 and 10 are executed, the object is
contacted to ask if it is an A.</DD><DT CLASS="dt-description"><B>Case 2</B></DT><DD CLASS="dd-description"> <TT>C::op1()</TT> and <TT>C::op2()</TT> return a D. This condition
only occurs if the runtime of the remote end is buggy. Line 6
completes and no exception is raised. At line 7, the object is
contacted to ask if it is an A. If the answer is no, a
<TT>CORBA::INV_OBJREF</TT> exception is raised. At line 10, the narrow
operation will fail, and objA will be set to nil.
</DD></DL><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note16" HREF="#text16">1</A></DT><DD CLASS="dd-thefootnotes">For further
details of the repository ID formats, see section 10.6 in the CORBA
2.6 specification.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Connection and Thread Management-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc91">Chapter&#XA0;8</A>&#XA0;&#XA0;Connection and Thread Management</H1><!--SEC END --><P>
<A NAME="chap:connections"></A></P><P>This chapter describes how omniORB manages threads and network
connections.</P><!--TOC section Background-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc92">8.1</A>&#XA0;&#XA0;Background</H2><!--SEC END --><P>In CORBA, the ORB is the &#X2018;middleware&#X2019; that allows a client to invoke
an operation on an object without regard to its implementation or
location. In order to invoke an operation on an object, a client needs
to &#X2018;bind&#X2019; to the object by acquiring its object reference. Such a
reference may be obtained as the result of an operation on another
object (such as a naming service or factory object) or by conversion
from a stringified representation. If the object is in a different
address space, the binding process involves the ORB building a proxy
object in the client&#X2019;s address space. The ORB arranges for invocations
on the proxy object to be transparently mapped to equivalent
invocations on the implementation object.</P><P>For the sake of interoperability, CORBA mandates that all ORBs should
support IIOP as the means to communicate remote invocations over a
TCP/IP connection. IIOP is usually<SUP><A NAME="text17" HREF="#note17">1</A></SUP>
asymmetric with respect to the roles of the parties at the two ends of
a connection. At one end is the client which can only initiate remote
invocations. At the other end is the server which can only receive
remote invocations.</P><P>Notice that in CORBA, as in most distributed systems, remote bindings
are established implicitly without application intervention. This
provides the illusion that all objects are local, a property known as
&#X2018;location transparency&#X2019;. CORBA does not specify when such bindings
should be established or how they should be multiplexed over the
underlying network connections. Instead, ORBs are free to implement
implicit binding by a variety of means.</P><P>The rest of this chapter describes how omniORB manages network
connections and the programming interface to fine tune the management
policy.</P><!--TOC section The model-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc93">8.2</A>&#XA0;&#XA0;The model</H2><!--SEC END --><P>omniORB is designed from the ground up to be fully multi-threaded. The
objective is to maximise the degree of concurrency and at the same
time eliminate any unnecessary thread overhead. Another objective is
to minimise the interference by the activities of other threads on the
progress of a remote invocation. In other words, thread &#X2018;cross-talk&#X2019;
should be minimised within the ORB. To achieve these objectives, the
degree of multiplexing at every level is kept to a minimum by default.</P><P>Minimising multiplexing works well when the ORB is relatively lightly
loaded. However, when the ORB is under heavy load, it can sometimes be
beneficial to conserve operating system resources such as threads and
network connections by multiplexing at the ORB level. omniORB has
various options that control its multiplexing behaviour.</P><!--TOC section Client side behaviour-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc94">8.3</A>&#XA0;&#XA0;Client side behaviour</H2><!--SEC END --><P>On the client side of a connection, the thread that invokes on a proxy
object drives the GIOP protocol directly and blocks on the connection
to receive the reply. The first time the client makes a call to a
particular address space, the ORB opens a suitable connection to the
remote address space (based on the client transport rule as described
in section&#XA0;<A HREF="#sec:clientRule">8.7.1</A>). After the reply has been received,
the ORB caches the open network connection, ready for use by another
call.</P><P>If two (or more) threads in a multi-threaded client attempt to contact
the same address space simultaneously, there are two different ways to
proceed. The default way is to open another network connection to the
server. This means that neither the client or server ORB has to
perform any multiplexing on the network connections&#X2014;multiplexing is
performed by the operating system, which has to deal with multiplexing
anyway. The second possibility is for the client to multiplex the
concurrent requests on a single network connection. This conserves
operating system resources (network connections), but means that both
the client and server have to deal with multiplexing issues
themselves.</P><P>In the default one call per connection mode, there is a limit to the
number of concurrent connections that are opened, set with the
<TT>maxGIOPConnectionPerServer</TT> parameter. To tell the ORB
that it may multiplex calls on a single connection, set the
<TT>oneCallPerConnection</TT> parameter to zero. If the
<TT>oneCallPerConnection</TT> parameter is set to the default
value of one, and there are more concurrent calls than specified by
<TT>maxGIOPConnectionPerServer</TT>, calls block waiting for connections
to become free.</P><P>Note that some server-side ORBs, including omniORB versions before
version 4.0, are unable to deal with concurrent calls multiplexed on a
single connection, so they serialise the calls. It is usually best to
keep to the default mode of opening multiple connections.</P><!--TOC subsection Client side timeouts-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc95">8.3.1</A>&#XA0;&#XA0;Client side timeouts</H3><!--SEC END --><P>
<A NAME="sec:timeoutAPI"></A></P><P>omniORB can associate a timeout with a call, meaning that if the call
takes too long a <TT>TRANSIENT</TT> exception is thrown. Timeouts can be
set for the whole process, for a specific thread, or for a specific
object reference.</P><P>Timeouts are set using this API:</P><DIV CLASS="lstlisting"><B>namespace</B> omniORB {
  <B>void</B> setClientCallTimeout(CORBA::ULong millisecs);
  <B>void</B> setClientCallTimeout(CORBA::Object_ptr obj, CORBA::ULong millisecs);
  <B>void</B> setClientThreadCallTimeout(CORBA::ULong millisecs);
  <B>void</B> setClientConnectTimeout(CORBA::ULong millisecs);
};</DIV><P><TT>setClientCallTimeout()</TT> sets either the global timeout or the
timeout for a specific object reference.
<TT>setClientThreadCallTimeout()</TT> sets the timeout for the calling
thread. The calling thread must have an <TT>omni_thread</TT> associated
with it. Setting any timeout value to zero disables it.</P><P>Accessing per-thread state is a relatively expensive operation, so per
thread timeouts are disabled by default. The
<TT>supportPerThreadTimeOut</TT> parameter must be set true to enable
them.</P><P>To choose the timeout value to use for a call, the ORB first looks to
see if there is a timeout for the object reference, then to the
calling thread, and finally to the global timeout.</P><P>When a client has no existing connection to communicate with a server,
it must open a new connection before performing the
call. <TT>setClientConnectTimeout()</TT> sets an overriding timeout for
cases where a new connection must be established. The effect of the
connect timeout depends upon whether the connect timeout is greater
or less than the timeout that would otherwise be used.</P><P>As an example, imagine that the usual call timeout is 10 seconds:</P><!--TOC subsubsection Connect timeout &gt; usual timeout-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->Connect timeout &gt; usual timeout</H4><!--SEC END --><P>If the connect timeout is set to 20 seconds, then a call that
establishes a new connection will be permitted 20 seconds before it
times out. Subsequent calls using the same connection have the normal
10 second timeout. If establishing the connection takes 8 seconds,
then the call itself takes 5 seconds, the call succeeds despite having
taken 13 seconds in total, longer than the usual timeout.</P><P>This kind of configuration is good when connections are slow to be
established.</P><P>If an object reference has multiple possible endpoints available, and
connecting to the first endpoint times out, only that one endpoint
will have been tried before an exception is raised. However, once the
timeout has occurred, the object reference will switch to use the next
endpoint. If the application attempts to make another call, it will
use the next endpoint.</P><!--TOC subsubsection Connect timeout &lt; usual timeout-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR -->Connect timeout &lt; usual timeout</H4><!--SEC END --><P>If the connect timeout is set to 2 seconds, the actual network-level
connect is only permitted to take 2 seconds. As long as the connection
is established in less than 2 seconds, the call can proceed. The 10
second call timeout still applies to the time taken for the whole call
(including the connection establishment). So, if establishing the
connection takes 1.5 seconds, and the call itself takes 9.5 seconds,
the call will time out because although it met the connection timeout,
it exceeded the 10 second total call timeout. On the other hand, if
establishing the connection takes 3 seconds, the call will fail after
only 2 seconds, since only 2 seconds are permitted for the connect.</P><P>If an object reference has multiple possible endpoints available, the
client will attempt to connect to them in turn, until one succeeds.
The connect timeout applies to each connection attempt. So with a
connect timeout of 2 seconds, the client will spend up to 2 seconds
attempting to connect to the first address and then, if that fails, up
to 2 seconds trying the second address, and so on. The 10 second
timeout still applies to the call as a whole, so if the total time
taken on timed-out connection attempts exceeds 10 seconds, the call
will time out.</P><P>This kind of configuration is useful where calls may take a long time
to complete (so call timeouts are long), but a fast indication of
connection failure is required.</P><!--TOC section Server side behaviour-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc96">8.4</A>&#XA0;&#XA0;Server side behaviour</H2><!--SEC END --><P>The server side has two primary modes of operation: thread per
connection and thread pooling. It is able to dynamically transition
between the two modes, and it supports a hybrid scheme that behaves
mostly like thread pooling, but has the same fast turn-around for
sequences of calls as thread per connection.</P><!--TOC subsection Thread per connection mode-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc97">8.4.1</A>&#XA0;&#XA0;Thread per connection mode</H3><!--SEC END --><P>In thread per connection mode (the default, and the only option in
omniORB versions before 4.0), each connection has a single thread
dedicated to it. The thread blocks waiting for a request. When it
receives one, it unmarshals the arguments, makes the up-call to the
application code, marshals the reply, and goes back to watching the
connection. There is thus no thread switching along the call chain,
meaning the call is very efficient.</P><P>As explained above, a client can choose to multiplex multiple
concurrent calls on a single connection, so once the server has
received the request, and just before it makes the call into
application code, it marks the connection as &#X2018;selectable&#X2019;, meaning
that another thread should watch it to see if any other requests
arrive. If they do, extra threads are dispatched to handle the
concurrent calls. GIOP 1.2 actually allows the argument data for
multiple calls to be interleaved on a connection, so the unmarshalling
code has to handle that too. As soon as any multiplexing occurs on the
connection, the aim of removing thread switching cannot be met, and
there is inevitable inefficiency due to thread switching.</P><P>The <TT>maxServerThreadPerConnection</TT> parameter can be set to limit
the number of threads that can be allocated to a single connection
containing concurrent calls. Setting the parameter to 1 mimics the
behaviour of omniORB versions before 4.0, that did not support
calls multiplexed on one connection.</P><!--TOC subsection Thread pool mode-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc98">8.4.2</A>&#XA0;&#XA0;Thread pool mode</H3><!--SEC END --><P>
<A NAME="sec:watchConn"></A></P><P>In thread pool mode, selected by setting the
<TT>threadPerConnectionPolicy</TT> parameter to zero, a single thread
watches all incoming connections. When a call arrives on one of them,
a thread is chosen from a pool of threads, and set to work
unmarshalling the arguments and performing the up-call. There is
therefore at least one thread switch for each call.</P><P>The thread pool is not pre-initialised. Instead, threads are started
on demand, and idle threads are stopped after a period of inactivity.
The maximum number of threads that can be started in the pool is set
with the <TT>maxServerThreadPoolSize</TT> parameter. The default
is 100.</P><P>A common pattern in CORBA applications is for a client to make several
calls to a single object in quick succession. To handle this situation
most efficiently, the default behaviour is to not return a thread to
the pool immediately after a call is finished. Instead, it is set to
watch the connection it has just served for a short while, mimicking
the behaviour in thread per connection mode. If a new call comes in
during the watching period, the call is dispatched without any thread
switching, just as in thread per connection mode. Of course, if the
server is supporting a very large number of connections (more than the
size of the thread pool), this policy can delay a call coming from
another connection. If the <TT>threadPoolWatchConnection</TT>
parameter is set to zero, connection watching is disabled and threads
return to the pool immediately after finishing a single request.</P><P>In the face of multiplexed calls on a single connection, multiple
threads from the pool can be dispatched for one connection, just as in
thread per connection mode. With <TT>threadPoolWatchConnection</TT> set
to the default value of 1, only the last thread servicing a connection
will watch it when it finishes a request. Setting the parameter to a
larger number allows the last <EM>n</EM> connections to watch the
connection.</P><!--TOC subsection Policy transition-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc99">8.4.3</A>&#XA0;&#XA0;Policy transition</H3><!--SEC END --><P>If the server is dealing with a relatively small number of
connections, it is most efficient to use thread per connection mode.
If the number of connections becomes too large, however, operating
system limits on the number of threads may cause a significant
slowdown, or even prevent the acceptance of new connections
altogether.</P><P>To give the most efficient response in all circumstances, omniORB
allows a server to start in thread per connection mode, and transition
to thread pooling if many connections arrive. This is controlled with
the <TT>threadPerConnectionUpperLimit</TT> and
<TT>threadPerConnectionLowerLimit</TT> parameters. The former must
always be larger than the latter. The upper limit chooses the number
of connections at which time the ORB transitions to thread pool mode;
the lower limit selects the point at which the transition back to
thread per connection is made.</P><P>For example, setting the upper limit to 50 and the lower limit to 30
would mean that the first 49 connections would receive dedicated
threads. The 50th to arrive would trigger thread pooling. All future
connections to arrive would make use of threads from the pool. Note
that the existing dedicated threads continue to service their
connections until the connections are closed. If the number of
connections falls below 30, thread per connection is reactivated and
new connections receive their own dedicated threads (up to the limit
of 50 again). Once again, existing connections in thread pool mode
stay in that mode until they are closed.</P><!--TOC section Idle connection shutdown-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc100">8.5</A>&#XA0;&#XA0;Idle connection shutdown</H2><!--SEC END --><P>
<A NAME="sec:connShutdown"></A></P><P>It is wasteful to leave a connection open when it has been left unused
for a considerable time. Too many idle connections could block out new
connections when it runs out of spare communication channels. For
example, most platforms have a limit on the number of file handles a
process can open. Many platforms have a very small default limit like
64. The value can often be increased to a maximum of a thousand or
more by changing the &#X2018;ulimit&#X2019; in the shell.</P><P>Every so often, a thread scans all open connections to see which are
idle. The scanning period (in seconds) is set with the
<TT>scanGranularity</TT> parameter. The default is 5 seconds.</P><P>Outgoing connections (initiated by clients) and incoming connections
(initiated by servers) have separate idle timeouts. The timeouts are
set with the <TT>outConScanPeriod</TT> and <TT>inConScanPeriod</TT>
parameters respectively. The values are in seconds, and must be a
multiple of the scan granularity.</P><P>Beware that setting <TT>outConScanPeriod</TT> or <TT>inConScanPeriod</TT>
to be equal to (or less than) <TT>scanGranularity</TT> means that
connections are considered candidates for closure immediately after
they are opened. That can mean that the connections are closed before
any calls have been sent through them. If oneway calls are used, such
connection closure can result in silent loss of calls.</P><!--TOC subsection Interoperability Considerations-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc101">8.5.1</A>&#XA0;&#XA0;Interoperability Considerations</H3><!--SEC END --><P>The IIOP specification allows both the client and the server to
shutdown a connection unilaterally. When one end is about to shutdown
a connection, it should send a CloseConnection message to the other
end. It should also make sure that the message will reach the other
end before it proceeds to shutdown the connection.</P><P>The client should distinguish between an orderly and an abnormal
connection shutdown. When a client receives a CloseConnection message
before the connection is closed, the condition is an orderly shutdown.
If the message is not received, the condition is an abnormal shutdown.
In an abnormal shutdown, the ORB should raise a <TT>COMM_FAILURE</TT>
exception whereas in an orderly shutdown, the ORB should <EM>not</EM>
raise an exception and should try to re-establish a new connection
transparently.</P><P>omniORB implements these semantics completely. However, it is known
that some ORBs are not (yet) able to distinguish between an orderly
and an abnormal shutdown. Usually this is manifested as the client in
these ORBs seeing a <TT>COMM_FAILURE</TT> occasionally when connected
to an omniORB server. The work-around is either to catch the exception
in the application code and retry, or to turn off the idle connection
shutdown inside the omniORB server.</P><!--TOC section Transports and endpoints-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc102">8.6</A>&#XA0;&#XA0;Transports and endpoints</H2><!--SEC END --><P>omniORB can support multiple network transports. All platforms
(usually) have a TCP transport available. Unix platforms support a
Unix domain socket transport. Platforms with the OpenSSL library
available can support an SSL transport.</P><P>Servers must be configured in two ways with regard to transports: the
transports and interfaces on which they listen, and the details that
are published in IORs for clients to see. Usually the published
details will be the same as the listening details, but there are times
when it is useful to publish different information.</P><P>Details are selected with the <TT>endPoint</TT> family of parameters.
The simplest is plain <TT>endPoint</TT>, which chooses a transport and
interface details, and publishes the information in IORs. Endpoint
parameters are in the form of URIs, with a scheme name of
&#X2018;<TT>giop:</TT>&#X2019;, followed by the transport name. Different transports
have different parameters following the transport.</P><P>TCP endpoints have the format:</P><BLOCKQUOTE CLASS="quote">
<TT>giop:tcp:</TT><I>&lt;host&gt;</I><TT>:</TT><I>&lt;port&gt;</I>
</BLOCKQUOTE><P>The host must be a valid host name or IP address for the
server machine. It determines the network interface on which the
server listens. The port selects the TCP port to listen on, which must
be unoccupied. Either the host or port, or both can be left empty. If
the host is empty, the ORB publishes the IP address of the first
non-loopback network interface it can find (or the loopback if that is
the only interface), but listens on <EM>all</EM> network interfaces. If
the port is empty, the operating system chooses a port.</P><P>Multiple TCP endpoints can be selected, either to specify multiple
network interfaces on which to listen, or (less usefully) to select
multiple TCP ports on which to listen.</P><P>If no <TT>endPoint</TT> parameters are set, the ORB assumes a single
parameter of <TT>giop:tcp::</TT>, meaning IORs contain the address of
the first non-loopback network interface, the ORB listens on all
interfaces, and the OS chooses a port number.</P><P>SSL endpoints have the same format as TCP ones, except &#X2018;<TT>tcp</TT>&#X2019;
is replaced with &#X2018;<TT>ssl</TT>&#X2019;. Unix domain socket endpoints have the
format:</P><BLOCKQUOTE CLASS="quote">
<TT>giop:unix:</TT><I>&lt;filename&gt;</I>
</BLOCKQUOTE><P>where the filename is the name of the socket within the
filesystem. If the filename is left blank, the ORB chooses a name
based on the process id and a timestamp.</P><P>To listen on an endpoint without publishing it in IORs, specify it
with the <TT>endPointNoPublish</TT> configuration parameter. See below
for more details about endpoint publishing.</P><!--TOC subsection IPv6-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc103">8.6.1</A>&#XA0;&#XA0;IPv6</H3><!--SEC END --><P>On platforms where it is available, omniORB supports IPv6. On most
Unix platforms, IPv6 sockets accept both IPv6 and IPv4 connections, so
omniORB&#X2019;s default <TT>giop:tcp::</TT> endpoint accepts both IPv4 and
IPv6 connections. On Windows versions before Windows Vista, each
socket type only accepts incoming connections of the same type, so an
IPv6 socket cannot be used with IPv4 clients. For this reason, the
default <TT>giop:tcp::</TT> endpoint only listens for IPv4 connections.
Since endpoints with a specific host name or address only listen on a
single network interface, they are inherently limited to just one
protocol family.</P><P>To explicitly ask for just IPv4 or just IPv6, an endpoint with the
wildcard address for the protocol family should be used. For IPv4, the
wildcard address is &#X2018;<TT>0.0.0.0</TT>&#X2019;, and for IPv6 it is &#X2018;<TT>::</TT>&#X2019;.
So, to listen for IPv4 connections on all IPv4 network interfaces, use
an endpoint of:</P><BLOCKQUOTE CLASS="quote">
<TT>giop:tcp:0.0.0.0:</TT>
</BLOCKQUOTE><P>All IPv6 addresses contain colons, so the address portion in
URIs must be contained within <TT>[]</TT> characters. Therefore, to
listen just for IPv6 connections on all IPv6 interfaces, use the
somewhat cryptic:</P><BLOCKQUOTE CLASS="quote">
<TT>giop:tcp:[::]:</TT>
</BLOCKQUOTE><P>To listen for both IPv4 and IPv6 connections on Windows
versions prior to Vista, both endpoints must be explicitly provided.</P><!--TOC subsubsection Link local addresses-->
<H4 CLASS="subsubsection"><!--SEC ANCHOR --><A NAME="htoc104">8.6.1.1</A>&#XA0;&#XA0;Link local addresses</H4><!--SEC END --><P>In IPv6, all network interfaces are assigned a <I>link local</I>
address, starting with the digits <TT>fe80</TT>. The link local address
is only valid on the same &#X2018;link&#X2019; as the interface, meaning directly
connected to the interface, or possibly on the same subnet, depending
on how the network is switched. To connect to a server&#X2019;s link local
address, a client has to know which of its network interfaces is on
the same link as the server. Since there is no way for omniORB to know
which local interface a remote link local address may be connected to,
and in extreme circumstances may even end up contacting the wrong
server if it picks the wrong interface, link local addresses are not
considered valid. Servers do not publish link local addresses in their
IORs.</P><!--TOC subsection Endpoint publishing-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc105">8.6.2</A>&#XA0;&#XA0;Endpoint publishing</H3><!--SEC END --><P>For clients to be able to connect to a server, the server publishes
endpoint information in its IORs (Interoperable Object References).
Normally, omniORB publishes the first available address for each of
the endpoints it is listening on.</P><P>The endpoint information to publish is determined by the
<TT>endPointPublish</TT> configuration parameter. It contains a
comma-separated list of publish rules. The rules are applied in turn
to each of the configured endpoints; if a rule matches an endpoint, it
causes one or more endpoints to be published.</P><P>The following core rules are supported:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><TT>addr</TT></TD><TD VALIGN=top ALIGN=left>the first natural address of the endpoint</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>ipv4</TT></TD><TD VALIGN=top ALIGN=left>the first IPv4 address of a TCP or SSL endpoint</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>ipv6</TT></TD><TD VALIGN=top ALIGN=left>the first IPv6 address of a TCP or SSL endpoint</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>name</TT></TD><TD VALIGN=top ALIGN=left>the first address that can be resolved to a name</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>hostname</TT></TD><TD VALIGN=top ALIGN=left>the result of the gethostname() system call</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>fqdn</TT></TD><TD VALIGN=top ALIGN=left>the fully-qualified domain name</TD></TR>
</TABLE><P>The core rules can be combined using the vertical bar operator to
try several rules in turn until one succeeds. e.g:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><TT>name|ipv6|ipv4</TT></TD><TD VALIGN=top ALIGN=left>the name of the endpoint if it has one;
	failing that, its first IPv6 address;
	failing that, its first IPv4 address.</TD></TR>
</TABLE><P>Multiple rules can be combined using the comma operator to
publish more than one endpoint. e.g.</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><TT>name,addr</TT></TD><TD VALIGN=top ALIGN=left>the name of the endpoint (if it has one),
followed by its first address.</TD></TR>
</TABLE><P>For endpoints with multiple addresses (e.g. TCP endpoints on
multi-homed machines), the <TT>all()</TT> manipulator causes all
addresses to be published. e.g.:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><TT>all(addr)</TT></TD><TD VALIGN=top ALIGN=left>all addresses are published</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>all(name)</TT></TD><TD VALIGN=top ALIGN=left>all addresses that resolve to names are published</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>all(name|addr)</TT></TD><TD VALIGN=top ALIGN=left>all addresses are published by name if they have
one, address otherwise.</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>all(name,addr)</TT></TD><TD VALIGN=top ALIGN=left>all addresses are published by name (if they
have one), and by address.</TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>all(name), all(addr)</TT></TD><TD VALIGN=top ALIGN=left>first the names of all addresses are published,
followed by all the addresses.</TD></TR>
</TABLE><P>A specific endpoint can be published by giving its endpoint URI,
even if the server is not listening on that endpoint. e.g.:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left><TT>giop:tcp:not.my.host:12345</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left><TT>giop:unix:/not/my/socket-file</TT></TD></TR>
</TABLE><P>If the host or port number for a TCP or SSL URI are missed out,
they are filled in with the details from each listening TCP/SSL
endpoint. This can be used to publish a different name for a
TCP/SSL endpoint that is using an ephemeral port, for example.</P><P>omniORB 4.0 supported two options related to endpoint publishing that
are superseded by the <TT>endPointPublish</TT> parameter, and so are now
deprecated. Setting <TT>endPointPublishAllIFs</TT> to 1 is equivalent to
setting <TT>endPointPublish</TT> to &#X2018;<TT>all(addr)</TT>&#X2019;. The
<TT>endPointNoListen</TT> parameter is equivalent to adding endpoint
URIs to the <TT>endPointPublish</TT> parameter.</P><!--TOC section Connection selection and acceptance-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc106">8.7</A>&#XA0;&#XA0;Connection selection and acceptance</H2><!--SEC END --><P>In the face of IORs containing details about multiple different
endpoints, clients have to know how to choose the one to use to
connect a server. Similarly, servers may wish to restrict which
clients can connect to particular transports. This is achieved with
<I>transport rules</I>.</P><!--TOC subsection Client transport rules-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc107">8.7.1</A>&#XA0;&#XA0;Client transport rules</H3><!--SEC END --><P>
<A NAME="sec:clientRule"></A></P><P>The <TT>clientTransportRule</TT> parameter is used to filter and
prioritise the order in which transports specified in an IOR are
tried. Each rule has the form:</P><BLOCKQUOTE CLASS="quote">
<I>&lt;address mask&gt; [action]+</I>
</BLOCKQUOTE><P>The address mask can be one of</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left NOWRAP>1.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>localhost</TT></TD><TD VALIGN=top ALIGN=left>The address of this machine</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
2.</TD><TD VALIGN=top ALIGN=left NOWRAP><I>w.x.y.z</I><TT>/</TT><I>m1.m2.m3.m4</I></TD><TD VALIGN=top ALIGN=left>An IPv4 address
with bits selected by the mask, e.g.
 <TT>172.16.0.0/255.240.0.0</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
3.</TD><TD VALIGN=top ALIGN=left NOWRAP><I>w.x.y.z</I><TT>/</TT><I>prefixlen</I></TD><TD VALIGN=top ALIGN=left>An IPv4 address with
<I>prefixlen</I> significant bits, e.g.
 <TT>172.16.2.0/24</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
4.</TD><TD VALIGN=top ALIGN=left NOWRAP><I>a:b:c:d:e:f:g:h</I><TT>/</TT><I>prefixlen</I></TD><TD VALIGN=top ALIGN=left>An IPv6
address with <I>prefixlen</I> significant bits, e.g.
 <TT>3ffe:505:2:1::/64</TT></TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>
5.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>*</TT></TD><TD VALIGN=top ALIGN=left>Wildcard that matches any address</TD></TR>
</TABLE><P>The action is one or more of the following:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD VALIGN=top ALIGN=left NOWRAP>1.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>none</TT></TD><TD VALIGN=top ALIGN=left>Do not use this address</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>2.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>tcp</TT></TD><TD VALIGN=top ALIGN=left>Use a TCP transport</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>3.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>ssl</TT></TD><TD VALIGN=top ALIGN=left>Use an SSL transport</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>4.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>unix</TT></TD><TD VALIGN=top ALIGN=left>Use a Unix socket transport</TD></TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP>5.</TD><TD VALIGN=top ALIGN=left NOWRAP><TT>bidir</TT></TD><TD VALIGN=top ALIGN=left>Connections to this address can be used
bidirectionally (see section&#XA0;<A HREF="#sec:bidir">8.8</A>)</TD></TR>
</TABLE><P>The transport-selecting actions form a prioritised list, so
an action of &#X2018;<TT>unix,ssl,tcp</TT>&#X2019; means to use a Unix transport if
there is one, failing that a SSL transport, failing <EM>that</EM> a TCP
transport. In the absence of any explicit rules, the client uses the
implicit rule of &#X2018;<TT>* unix,ssl,tcp</TT>&#X2019;.</P><P>If more than one rule is specified, they are prioritised in the order
they are specified. For example, the configuration file might contain:</P><PRE CLASS="verbatim">  clientTransportRule = 192.168.1.0/255.255.255.0  unix,tcp
  clientTransportRule = 172.16.0.0/255.240.0.0     unix,tcp
                      =       *                    none
</PRE><P>This would be useful if there is a fast network
(192.168.1.0) which should be used in preference to another network
(172.16.0.0), and connections to other networks are not permitted at
all.</P><P>In general, the result of filtering the endpoint specifications in an
IOR with the client transport rule will be a prioritised list of
transports and networks. (If the transport rules do not prioritise one
endpoint over another, the order the endpoints are listed in the IOR
is used.) When trying to contact an object, the ORB tries its
possible endpoints in turn, until it finds one with which it can
contact the object. Only after it has unsuccessfully tried all
permissible endpoints will it raise a <TT>TRANSIENT</TT> exception to
indicate that the connect failed.</P><!--TOC subsection Server transport rules-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc108">8.7.2</A>&#XA0;&#XA0;Server transport rules</H3><!--SEC END --><P>
<A NAME="sec:serverRule"></A></P><P>The server transport rules have the same format as client transport
rules. Rather than being used to select which of a set of ways to
contact a machine, they are used to determine whether or not to accept
connections from particular clients. In this example, we only allow
connections from our intranet:</P><PRE CLASS="verbatim">  serverTransportRule = localhost                  unix,tcp,ssl
                      = 172.16.0.0/255.240.0.0     tcp,ssl
                      = *                          none
</PRE><P>And in this one, we accept only SSL connections if the
client is not on the intranet:</P><PRE CLASS="verbatim">  serverTransportRule = localhost                  unix,tcp,ssl
                      = 172.16.0.0/255.240.0.0     tcp,ssl
                      = *                          ssl,bidir
</PRE><P>In the absence of any explicit rules, the server uses the
implicit rule of &#X2018;<TT>* unix,ssl,tcp</TT>&#X2019;, meaning any kind of
connection is accepted from any client.</P><!--TOC section Bidirectional GIOP-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc109">8.8</A>&#XA0;&#XA0;Bidirectional GIOP</H2><!--SEC END --><P>
<A NAME="sec:bidir"></A></P><P>omniORB supports bidirectional GIOP, which allows callbacks to be made
using a connection opened by the original client, rather than the
normal model where the server opens a new connection for the callback.
This is important for negotiating firewalls, since they tend not to
allow connections back on arbitrary ports.</P><P>There are several steps required for bidirectional GIOP to be enabled
for a callback. Both the client and server must be configured
correctly. On the client side, these conditions must be met:</P><UL CLASS="itemize"><LI CLASS="li-itemize">The <TT>offerBiDirectionalGIOP</TT> parameter must be set to true. 
</LI><LI CLASS="li-itemize">The client transport rule for the target server must contain the
<TT>bidir</TT> action.
</LI><LI CLASS="li-itemize">The POA containing the callback object (or objects) must have
been created with a <TT>BidirectionalPolicy</TT> value of
<TT>BOTH</TT>.</LI></UL><P>On the server side, these conditions must be met:</P><UL CLASS="itemize"><LI CLASS="li-itemize">The <TT>acceptBiDirectionalGIOP</TT> parameter must be set to true. 
</LI><LI CLASS="li-itemize">The server transport rule for the requesting client must contain
the <TT>bidir</TT> action.
</LI><LI CLASS="li-itemize">The POA hosting the object contacted by the client must have
been created with a <TT>BidirectionalPolicy</TT> value of
<TT>BOTH</TT>.</LI></UL><!--TOC section SSL transport-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc110">8.9</A>&#XA0;&#XA0;SSL transport</H2><!--SEC END --><P>omniORB supports an SSL transport, using OpenSSL. It is only built if
OpenSSL is available. On platforms using Autoconf, it is autodetected
in many locations, or its location can be given with the
<TT>--with-openssl=</TT> argument to <TT>configure</TT>. On other
platforms, the <TT>OPEN_SSL_ROOT</TT> make variable must be set in the
platform file.</P><P>To use the SSL transport, you must link your application with the
<TT>omnisslTP</TT> library, and correctly set up certificates. See the
<TT>src/examples/ssl_echo</TT> directory for an example. That directory
contains a <TT>README</TT> file with more details.</P><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note17" HREF="#text17">1</A></DT><DD CLASS="dd-thefootnotes">GIOP 1.2 supports
&#X2018;bidirectional GIOP&#X2019;, which permits the r&#XF4;les to be reversed.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Code set conversion-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc111">Chapter&#XA0;9</A>&#XA0;&#XA0;Code set conversion</H1><!--SEC END --><P>
<A NAME="chap:codesets"></A></P><P>omniORB supports full code set negotiation, used to select and
translate between different character code sets, for the transmission
of chars, strings, wchars and wstrings. The support is mostly
transparent to application code, but there are a number of options
that can be selected. This chapter covers the options, and also gives
some pointers about how to implement your own code sets, in case the
ones that come with omniORB are not sufficient.</P><!--TOC section Native code sets-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc112">9.1</A>&#XA0;&#XA0;Native code sets</H2><!--SEC END --><P>For the ORB to know how to handle strings and wstrings given to it by
the application, it must know what code set they are represented
with, so it can properly translate them if need be. The defaults are
ISO 8859-1 (Latin 1) for char and string, and UTF-16 for wchar and
wstring. Different code sets can be chosen at initialisation time with
the <TT>nativeCharCodeSet</TT> and <TT>nativeWCharCodeSet</TT>
parameters. The supported code sets are printed out at initialisation
time if the ORB traceLevel is 15 or greater.</P><P>For most applications, the defaults are fine. Some applications may
need to set the native char code set to UTF-8, allowing the full
Unicode range to be supported in strings.</P><P>Note that the default for wchar is always UTF-16, even on Unix
platforms where wchar is a 32-bit type. Select the UCS-4 code set to
select characters outside the first plane without having to use UTF-16
surrogates<SUP><A NAME="text18" HREF="#note18">1</A></SUP>.</P><!--TOC section Code set library-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc113">9.2</A>&#XA0;&#XA0;Code set library</H2><!--SEC END --><P>To save space in the main ORB core library, most of the code set
implementations are in a separate library named omniCodeSets4. To use
the extra code sets, you must link your application with that
library. On most platforms, if you are using dynamic linking,
specifying the omniCodeSets4 library in the link command is sufficient
to have it initialised, and for the code sets to be available. With
static linking, or platforms with less intelligent dynamic linkers,
you must force the linker to initialise the library. You do that by
including the <TT>omniORB4/optionalFeatures.h</TT> header. By default,
that header enables several optional features. Look at the file
contents to see how to turn off particular features.</P><!--TOC section Implementing new code sets-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc114">9.3</A>&#XA0;&#XA0;Implementing new code sets</H2><!--SEC END --><P>It is quite easy to implement new code sets, if you need support for
code sets (or marshalling formats) that do not come with the omniORB
distribution. There are extensive comments in the headers and ORB code
that explain how to implement a code set; this section just serves to
point you in the right direction.</P><P>The main definitions for the code set support are in
<TT>include/omniORB4/codeSets.h</TT>. That defines a set of base classes
use to implement code sets, plus some derived classes that use look-up
tables to convert simple 8-bit and 16-bit code sets to Unicode.</P><P>When sending or receiving string data, there are a total of four code
sets in action: a native char code set, a transmission char code set,
a native wchar code set, and a transmission wchar code set. The native
code sets are as described above; the transmission code sets are the
ones selected to communicate with a remote machine. They are
responsible for understanding the GIOP marshalling formats, as well as
the code sets themselves. Each of the four code sets has an object
associated with it which contains methods for converting data.</P><P>There are two ways in which a string/wstring can be transmitted or
received. If the transmission code set in action knows how to deal
directly with the native code set (the trivial case being that they
are the same code set, but more complex cases are possible too), the
transmission code set object can directly marshal or unmarshal the
data into or out of the application buffer. If the transmission code
set does not know how to handle the native code set, it converts the
string/wstring into UTF-16, and passes that to the native code set
object (or vice-versa). All code set implementations must therefore
know how to convert to and from UTF-16.</P><P>With this explanation, the classes in <TT>codeSets.h</TT> should be easy
to understand. The next place to look is in the various existing code
set implementations, which are files of the form <TT>cs-*.cc</TT> in the
<TT>src/lib/omniORB/orbcore</TT> and <TT>src/lib/omniORB/codesets</TT>.
Note how all the 8-bit code sets (the ISO 8859-* family) consist
entirely of data and no code, since they are driven by look-up tables.</P><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note18" HREF="#text18">1</A></DT><DD CLASS="dd-thefootnotes">If you have no idea what this means, don&#X2019;t
worry&#X2014;you&#X2019;re better off not knowing unless you <EM>really</EM> have
to.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Interceptors-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc115">Chapter&#XA0;10</A>&#XA0;&#XA0;Interceptors</H1><!--SEC END --><P>
<A NAME="chap:interceptors"></A></P><P>omniORB supports interceptors that allow the application to insert
processing in various points along the call chain, and in various
other locations. It does not (yet) support the standard Portable
Interceptors API.</P><P>The interceptor interfaces are defined in a single header,
<TT>include/omniORB4/omniInterceptors.h</TT>. Each interception point
consists of a singleton object with <TT>add()</TT> and <TT>remove()</TT> methods,
and the definition of an &#X2018;interceptor info&#X2019; class. For example:</P><DIV CLASS="lstlisting"><B>class</B> omniInterceptors {
  ...
  <B>class</B> clientSendRequest_T {
  <B>public</B>:

    <B>class</B> info_T {
    <B>public</B>:
      GIOP_C&amp;                 giop_c;
      IOP::ServiceContextList service_contexts;

      info_T(GIOP_C&amp; c) : giop_c(c), service_contexts(5) {}

    <B>private</B>:
      info_T();
      info_T(<B>const</B> info_T&amp;);
      info_T&amp; <B>operator</B>=(<B>const</B> info_T&amp;);
    };

    <B>typedef</B> CORBA::Boolean (*interceptFunc)(info_T&amp; info);

    <B>void</B> add(interceptFunc);
    <B>void</B> remove(interceptFunc);
  };
  ...
};</DIV><P>You can see that the interceptors themselves are functions
that take the <TT>info_T</TT> object as their argument and return
boolean. Interceptors are called in the order they are registered;
normally, all interceptor functions return true, meaning that
processing should continue with subsequent interceptors. If an
interceptor returns false, later interceptors are not called. You
should only do that if you really know what you are doing.</P><P>Notice that the <TT>info_T</TT> contains references to omniORB internal
data types. The definitions of these types can be found in other
header files within <TT>include/omniORB4</TT> and
<TT>include/omniORB4/internal</TT>.</P><!--TOC section Interceptor registration-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc116">10.1</A>&#XA0;&#XA0;Interceptor registration</H2><!--SEC END --><P>All the interceptor singletons are registered within another singleton
object of class <TT>omniInterceptors</TT>. You retrieve a pointer to the
object with the <TT>omniORB::getInterceptors()</TT> function, which
must be called after the ORB has been initialised with
<TT>CORBA::ORB_init()</TT>, but before the ORB is used. The code to
register an interceptor looks, for example, like:</P><DIV CLASS="lstlisting">omniInterceptors* interceptors = omniORB::getInterceptors();
interceptors-&gt;clientSendRequest.add(myInterceptorFunc);</DIV><!--TOC section Available interceptors-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc117">10.2</A>&#XA0;&#XA0;Available interceptors</H2><!--SEC END --><P>The following interceptors are available:</P><DL CLASS="description"><DT CLASS="dt-description"><B>encodeIOR</B></DT><DD CLASS="dd-description"><BR>
Called when encoding an IOR to represent an object reference. This
interception point allows the application to insert extra profile
components into IORs. Note that you must understand and adhere to the
rules about data stored in IORs, otherwise the IORs created may be
invalid. omniORB itself uses this interceptor to insert various items,
so you can see an example of its use in the
<TT>insertSupportedComponents()</TT> function defined in
<TT>src/lib/omniORB/orbcore/ior.cc</TT>.</DD><DT CLASS="dt-description"><B>decodeIOR</B></DT><DD CLASS="dd-description"><BR>
Called when decoding an IOR. The application can use this to get out
whatever information they put into IORs with encodeIOR. Again, see
<TT>extractSupportedComponents()</TT> in
<TT>src/lib/omniORB/orbcore/ior.cc</TT> for an example.</DD><DT CLASS="dt-description"><B>clientOpenConnection</B></DT><DD CLASS="dd-description"><BR>
Called as a client opens a new connection to a server, after the
connection is opened but before it is used to send a request. The
interceptor function can set the <TT>info_T</TT>&#X2019;s <TT>reject</TT> member
to true to cause the client to immediately close the new connection
and throw CORBA::TRANSIENT to the calling code. In that case, the
interceptor function can also set the <TT>why</TT> member to provide a
message that is logged.</DD><DT CLASS="dt-description"><B>clientSendRequest</B></DT><DD CLASS="dd-description"><BR>
Called just before a request header is sent over the network. The
application can use it to insert service contexts in the header. See
<TT>setCodeSetServiceContext()</TT> in
<TT>src/lib/omniORB/orbcore/cdrStream.cc</TT> for an example of its use.</DD><DT CLASS="dt-description"><B>clientReceiveReply</B></DT><DD CLASS="dd-description"><BR>
Called as the client receives a reply, just after unmarshalling the
reply header. Called for normal replies and exceptions.</DD><DT CLASS="dt-description"><B>serverAcceptConnection</B></DT><DD CLASS="dd-description"><BR>
Called when a server accepts a new incoming connection, but before
it reads any data from it. The interceptor function can set the
<TT>info_T</TT>&#X2019;s <TT>reject</TT> member to true to cause the server to
immediately close the new connection. In that case, the interceptor
function can also set the <TT>why</TT> member to provide a message
that is logged.</DD><DT CLASS="dt-description"><B>serverReceiveRequest</B></DT><DD CLASS="dd-description"><BR>
Called when the server receives a request, just after unmarshalling
the request header. See the <TT>getCodeSetServiceContext()</TT> function in
<TT>src/lib/omniORB/orbcore/cdrStream.cc</TT> for an example.</DD><DT CLASS="dt-description"><B>serverSendReply</B></DT><DD CLASS="dd-description"><BR>
Called just before the server marshals a reply header.</DD><DT CLASS="dt-description"><B>serverSendException</B></DT><DD CLASS="dd-description"><BR>
Called just before the server marshals an exception reply header.</DD><DT CLASS="dt-description"><B>createIdentity</B></DT><DD CLASS="dd-description"><BR>
Called when the ORB is about to create an &#X2018;identity&#X2019; object to
represent a CORBA object. It allows application code to provide its
own identity implementations. It is very unlikely that an application
will need to do this.</DD><DT CLASS="dt-description"><B>createORBServer</B></DT><DD CLASS="dd-description"><BR>
Used internally by the ORB to register different kinds of server. At
present, only a GIOP server is registered. It is very unlikely that
application code will need to do this.</DD><DT CLASS="dt-description"><B>createThread</B></DT><DD CLASS="dd-description"><BR>
Called whenever the ORB creates a thread. The <TT>info_T</TT> class for
this interceptor is<DIV CLASS="lstlisting">    <B>class</B> info_T {
    <B>public</B>:
      <B>virtual</B> <B>void</B> run() = 0;
    };</DIV><P>The interceptor function is called in the context of the newly created
thread. The function <EM>must</EM> call the <TT>info_T</TT>&#X2019;s <TT>run()</TT>
method, to pass control to the thread body. <TT>run()</TT> returns just
before the thread exits. This arrangement allows the interceptor to
initialise some per-thread state before the thread body runs, then
release it just before the thread exits.</P></DD><DT CLASS="dt-description"><B>assignUpcallThread</B></DT><DD CLASS="dd-description"><BR>
The ORB maintains a general thread pool, from which threads are drawn
for various purposes. One purpose is for performing upcalls to
application code, in response to incoming CORBA calls. The
assignUpcallThread interceptor is called when a thread is assigned to
perform upcalls. In the thread per connection model, the thread stays
assigned to performing upcalls for the entire lifetime of the
underlying network connection; in the thread pool model, threads are
assigned for upcalls on a per call basis, so this interceptor is
triggered for every incoming call<SUP><A NAME="text19" HREF="#note19">1</A></SUP>. As with the
createThread interceptor, the interceptor function must call the
<TT>info_T</TT>&#X2019;s <TT>run()</TT> method to pass control to the upcall.<P>When a thread finishes its assignment of processing upcalls, it
returns to the pool (even in thread per connection mode), so the same
thread can be reassigned to perform more upcalls, or reused for a
different purpose.</P><P>Unlike the other interceptors, the interceptor functions for
createThread and assignUpcallThread have no return value. Interceptor
chaining is performed by calls through the <TT>info_T::run()</TT> method,
rather than by visiting interceptor functions in turn.</P></DD></DL><!--BEGIN NOTES chapter-->
<HR CLASS="footnoterule"><DL CLASS="thefootnotes"><DT CLASS="dt-thefootnotes">
<A NAME="note19" HREF="#text19">1</A></DT><DD CLASS="dd-thefootnotes">Except that with the
threadPoolWatchConnection parameter set true, a thread can perform
multiple upcalls even when thread pool mode is active.
</DD></DL>
<!--END NOTES-->
<!--TOC chapter Type Any and TypeCode-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc118">Chapter&#XA0;11</A>&#XA0;&#XA0;Type Any and TypeCode</H1><!--SEC END --><P>
<A NAME="chap:any"></A></P><P>The CORBA specification provides for a type that can hold the value of
any OMG IDL type. This type is known as type Any. The OMG also
specifies a pseudo-object, TypeCode, that can encode a description of
any type specifiable in OMG IDL.</P><P>In this chapter, an example demonstrating the use of type Any is
presented. This is followed by sections describing the behaviour of
type Any and TypeCode in omniORB. For further information on type
Any, refer to the C++ Mapping specification., and for more information
on TypeCode, refer to the Interface Repository chapter in the CORBA
core section of the CORBA specification.</P><!--TOC section Example using type Any-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc119">11.1</A>&#XA0;&#XA0;Example using type Any</H2><!--SEC END --><P>Before going through this example, you should make sure that you have
read and understood the examples in chapter&#XA0;<A HREF="#chap:basic">2</A>. The
source code for this example is included in the omniORB distribution,
in the directory <TT>src/examples/anyExample</TT>. A listing of the
source code is provided at the end of this chapter.</P><!--TOC subsection Type Any in IDL-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc120">11.1.1</A>&#XA0;&#XA0;Type Any in IDL</H3><!--SEC END --><P>
Type Any allows one to delay the decision on the type used in an
operation until run-time. To use type any in IDL, use the keyword
<TT>any</TT>, as in the following example:</P><DIV CLASS="lstlisting"><I>// IDL</I>
<B>interface</B> anyExample {
  <B>any</B> testOp(<B>in</B> <B>any</B> mesg);
};</DIV><P>The operation <TT>testOp()()</TT> in this example can now take any
value expressible in OMG IDL as an argument, and can also return any
type expressible in OMG IDL.</P><P>Type Any is mapped into C++ as the type <TT>CORBA::Any</TT>. When passed
as an argument or as a result of an operation, the following rules
apply:</P><TABLE CELLSPACING=6 CELLPADDING=0><TR><TD ALIGN=left NOWRAP><B>In </B></TD><TD ALIGN=left NOWRAP><B>InOut </B></TD><TD ALIGN=left NOWRAP><B>Out </B></TD><TD ALIGN=left NOWRAP><B>Return </B></TD></TR>
<TR><TD CLASS="hbar" COLSPAN=4></TD></TR>
<TR><TD ALIGN=left NOWRAP><TT>const CORBA::Any&amp; </TT></TD><TD ALIGN=left NOWRAP><TT>CORBA::Any&amp; </TT></TD><TD ALIGN=left NOWRAP><TT>CORBA::Any*&amp; </TT></TD><TD ALIGN=left NOWRAP><TT>CORBA::Any* </TT></TD></TR>
</TABLE><P>So, the above IDL would map to the following C++:</P><DIV CLASS="lstlisting"><I>// C++</I>

<B>class</B> anyExample_i : <B>public</B> <B>virtual</B> POA_anyExample {
<B>public</B>:
  anyExample_i() { }
  <B>virtual</B> ~anyExample_i() { }
  <B>virtual</B> CORBA::Any* testOp(<B>const</B> CORBA::Any&amp; a);
};</DIV><!--TOC subsection Inserting and Extracting Basic Types from an Any-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc121">11.1.2</A>&#XA0;&#XA0;Inserting and Extracting Basic Types from an Any</H3><!--SEC END --><P>The question now arises as to how values are inserted into and removed
from an Any. This is achieved using two overloaded operators:
<TT>&lt;&lt;=</TT> and <TT>&gt;&gt;=</TT>.</P><P>To insert a value into an Any, the <TT>&lt;&lt;=</TT> operator is used, as
in this example:</P><DIV CLASS="lstlisting"><I>// C++</I>
CORBA::Any an_any;
CORBA::Long l = 100;
an_any &lt;&lt;= l;</DIV><P>Note that the overloaded <TT>&lt;&lt;=</TT> operator has a return
type of <TT>void</TT>.</P><P>To extract a value, the <TT>&gt;&gt;=</TT> operator is used, as in this
example (where the Any contains a long):</P><DIV CLASS="lstlisting"><I>// C++</I>
CORBA::Long l;
an_any &gt;&gt;= l;

cout &lt;&lt; "This is a long: " &lt;&lt; l &lt;&lt; endl;</DIV><P>The overloaded <TT>&gt;&gt;=</TT> operator returns a <TT>CORBA::Boolean</TT>.
If an attempt is made to extract a value from an Any when it contains
a different type of value (e.g. an attempt to extract a long from an
Any containing a double), the overloaded <TT>&gt;&gt;=</TT> operator will
return False; otherwise it will return True. Thus, a common tactic to
extract values from an Any is as follows:</P><DIV CLASS="lstlisting"><I>// C++</I>
CORBA::Long l;
CORBA::Double d;
<B>const</B> <B>char</B>* str;

<B>if</B> (an_any &gt;&gt;= l) {
  cout &lt;&lt; "Long: " &lt;&lt; l &lt;&lt; endl;
}
<B>else</B> <B>if</B> (an_any &gt;&gt;= d) {
  cout &lt;&lt; "Double: " &lt;&lt; d &lt;&lt; endl;
}
<B>else</B> <B>if</B> (an_any &gt;&gt;= str) {
  cout &lt;&lt; "String: " &lt;&lt; str &lt;&lt; endl;
  <I>// The storage of the extracted string is still owned by the any.</I>
}
<B>else</B> {
  cout &lt;&lt; "Unknown value." &lt;&lt; endl;
}</DIV><!--TOC subsection Inserting and Extracting Constructed Types from an Any-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc122">11.1.3</A>&#XA0;&#XA0;Inserting and Extracting Constructed Types from an Any</H3><!--SEC END --><P>It is also possible to insert and extract constructed types and object
references from an Any. omniidl will generate insertion and extraction
operators for the constructed type. Note that it is necessary to
specify the <TT>-WBa</TT> command-line flag when running omniidl in
order to generate these operators. The following example illustrates
the use of constructed types with type Any:</P><DIV CLASS="lstlisting"><I>// IDL</I>
<B>struct</B> testStruct {
  <B>long</B> l;
  <B>short</B> s;
};

<B>interface</B> anyExample {
  <B>any</B> testOp(<B>in</B> <B>any</B> mesg);
};</DIV><P>Upon compiling the above IDL with <TT>omniidl -bcxx -Wba</TT>, the
following overloaded operators are generated:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
<CODE>void operator&lt;&lt;=(CORBA::Any&amp;, const testStruct&amp;)</CODE>
</LI><LI CLASS="li-enumerate"><CODE>void operator&lt;&lt;=(CORBA::Any&amp;, testStruct*)</CODE>
</LI><LI CLASS="li-enumerate"><CODE>CORBA::Boolean operator&gt;&gt;=(const CORBA::Any&amp;,</CODE><BR>
 <CODE>const testStruct*&amp;)</CODE>
</LI></OL><P>Operators of this form are generated for all constructed types, and
for interfaces.</P><P>The first operator, <EM>(1)</EM>, copies the constructed type, and
inserts it into the Any. The second operator, <EM>(2)</EM>, inserts the
constructed type into the Any, and then manages it. Note that if the
second operator is used, the Any consumes the constructed type, and
the caller should not use the pointer to access the data after
insertion. The following is an example of how to insert a value into
an Any using operator <EM>(1)</EM>:</P><DIV CLASS="lstlisting"><I>// C++</I>
CORBA::Any an_any;

testStruct t;
t.l = 456;
t.s = 8;

an_any &lt;&lt;= t;</DIV><P>The third operator, <EM>(3)</EM>, is used to extract the constructed
type from the Any, and can be used as follows:</P><DIV CLASS="lstlisting"><B>const</B> testStruct* tp;

<B>if</B> (an_any &gt;&gt;= tp) {
    cout &lt;&lt; "testStruct: l: " &lt;&lt; tp-&gt;l &lt;&lt; endl;
    cout &lt;&lt; "            s: " &lt;&lt; tp-&gt;s &lt;&lt; endl;
}
<B>else</B> {
    cout &lt;&lt; "Unknown value contained in Any." &lt;&lt; endl;
}</DIV><P>As with basic types, if an attempt is made to extract a type from an
Any that does not contain a value of that type, the extraction
operator returns False. If the Any does contain that type, the
extraction operator returns True. If the extraction is successful, the
caller&#X2019;s pointer will point to memory managed by the Any. The caller
must not delete or otherwise change this storage, and should not use
this storage after the contents of the Any are replaced (either by
insertion or assignment), or after the Any has been destroyed. In
particular, management of the pointer should not be assigned to a
<TT>_var</TT> type.</P><P>If the extraction fails, the caller&#X2019;s pointer will be set to point to
null.</P><P>Note that there are special rules for inserting and extracting arrays
(using the <TT>_forany</TT> types), and for inserting and extracting
bounded strings, booleans, chars, and octets. Please refer to the C++
Mapping specification for further information.</P><!--TOC section Type Any in omniORB-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc123">11.2</A>&#XA0;&#XA0;Type Any in omniORB</H2><!--SEC END --><P>
<A NAME="anyOmniORB"></A></P><P>This section contains some notes on the use and behaviour of type Any
in omniORB.</P><!--TOC subsection Generating Insertion and Extraction Operators.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc124">11.2.1</A>&#XA0;&#XA0;Generating Insertion and Extraction Operators.</H3><!--SEC END --><P>
To generate type Any insertion and extraction operators for
constructed types and interfaces, the <TT>-Wba</TT> command line flag
should be specified when running omniidl.</P><!--TOC subsection TypeCode comparison when extracting from an Any.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc125">11.2.2</A>&#XA0;&#XA0;TypeCode comparison when extracting from an Any.</H3><!--SEC END --><P>
When an attempt is made to extract a type from an Any, the TypeCode of
the type is checked for <EM>equivalence</EM> with the TypeCode of the
type stored by the Any. The <TT>equivalent()</TT> test in the TypeCode
interface is used for this purpose.</P><P>Examples:</P><DIV CLASS="lstlisting"><I>// IDL 1</I>
<B>typedef</B> <B>double</B> Double1;

<B>struct</B> Test1 {
  Double1 a;
};</DIV><DIV CLASS="lstlisting"><I>// IDL 2</I>
<B>typedef</B> <B>double</B> Double2;

<B>struct</B> Test1 {
  Double2 a;
};</DIV><P>If an attempt is made to extract the type <TT>Test1</TT> defined in IDL
1 from an Any containing the <TT>Test1</TT> defined in IDL 2, this will
succeed (and vice-versa), as the two types differ only by an alias.</P><!--TOC subsection Top-level aliases.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc126">11.2.3</A>&#XA0;&#XA0;Top-level aliases.</H3><!--SEC END --><P>
When a type is inserted into an Any, the Any stores both the value of
the type and the TypeCode for that type. However, in some cases, a
top-level alias can be lost due to the details of the C++ mapping. For
example, consider these IDL definitions:</P><DIV CLASS="lstlisting"><I>// IDL 3</I>
<B>typedef</B> <B>sequence</B>&lt;<B>double</B>&gt; seqDouble1;
<B>typedef</B> <B>sequence</B>&lt;<B>double</B>&gt; seqDouble2;
<B>typedef</B> seqDouble2       seqDouble3;</DIV><P>omniidl generates distinct types for <TT>seqDouble1</TT> and
<TT>seqDouble2</TT>, and therefore each has its own set of C++ operators
for Any insertion and extraction. That means inserting a
<TT>seqDouble1</TT> into an Any sets the Any&#X2019;s TypeCode to include the
alias &#X2018;seqDouble1&#X2019;, and inserting a <TT>seqDouble2</TT> sets the
TypeCode to the alias &#X2018;seqDouble2&#X2019;.</P><P>However, in the C++ mapping, <TT>seqDouble3</TT> is required to be just
a C++ typedef to <TT>seqDouble2</TT>, so the C++ compiler uses the Any
insertion operator for <TT>seqDouble2</TT>. Therefore, inserting a
<TT>seqDouble3</TT> sets the Any&#X2019;s TypeCode to the <TT>seqDouble2</TT>
alias. If this is not desirable, you can use the member function
&#X2018;<TT>void type(TypeCode_ptr)</TT>&#X2019; of the Any interface to explicitly
set the TypeCode to the correct one.</P><!--TOC subsection Removing aliases from TypeCodes.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc127">11.2.4</A>&#XA0;&#XA0;Removing aliases from TypeCodes.</H3><!--SEC END --><P>
Some ORBs (such as old versions of Orbix) will not accept TypeCodes
containing <TT>tk_alias</TT> TypeCodes. When using type Any while
interoperating with these ORBs, it is necessary to remove
<TT>tk_alias</TT> TypeCodes from throughout the TypeCode representing a
constructed type.</P><P>To remove all <TT>tk_alias</TT> TypeCodes from TypeCodes transmitted in
Anys, supply the <TT>-ORBtcAliasExpand 1</TT> command-line flag when
running an omniORB executable. There will be some (small) performance
penalty when transmitting Any values.</P><P>Note that the <TT>_tc_</TT> TypeCodes generated for all constructed
types will contain the complete TypeCode for the type (including any
<TT>tk_alias</TT> TypeCodes), regardless of whether the
<TT>-ORBtcAliasExpand</TT> flag is set to 1 or not. It is only when
Anys are transmitted that the aliases are stripped.</P><!--TOC subsection Recursive TypeCodes.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc128">11.2.5</A>&#XA0;&#XA0;Recursive TypeCodes.</H3><!--SEC END --><P>
omniORB supports recursive TypeCodes. This means that types such as
the following can be inserted or extracted from an Any:</P><DIV CLASS="lstlisting"><I>// IDL 4</I>
<B>struct</B> Test4 {
  <B>sequence</B>&lt;Test4&gt; a;
};</DIV><!--TOC subsection Threads and type Any.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc129">11.2.6</A>&#XA0;&#XA0;Threads and type Any.</H3><!--SEC END --><P>
Inserting and extracting simultaneously from the same Any (in 2
different threads) results in undefined behaviour.</P><P>In versions of omniORB before 4.0, extracting simultaneously from the
same Any (in 2 or more different threads) also led to undefined
behaviour. That is no longer the case&#X2014;Any extraction is now thread
safe.</P><!--TOC section TypeCode in omniORB-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc130">11.3</A>&#XA0;&#XA0;TypeCode in omniORB</H2><!--SEC END --><P>This section contains some notes on the use and behaviour of TypeCode
in omniORB</P><!--TOC subsection TypeCodes in IDL.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc131">11.3.1</A>&#XA0;&#XA0;TypeCodes in IDL.</H3><!--SEC END --><P>When using TypeCodes in IDL, note that they are defined in the CORBA
scope. Therefore, <TT>CORBA::TypeCode</TT> should be used. Example:</P><DIV CLASS="lstlisting"><I>// IDL 5</I>
<B>struct</B> Test5 {
  <B>long</B> length;
  CORBA::TypeCode desc;
};</DIV><!--TOC subsection orb.idl-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc132">11.3.2</A>&#XA0;&#XA0;orb.idl</H3><!--SEC END --><P>The CORBA specification says that IDL using <TT>CORBA::TypeCode</TT>
must include the file <TT>orb.idl</TT>. That is not required in omniORB,
but a suitable <TT>orb.idl</TT> is available.</P><!--TOC subsection Generating TypeCodes for constructed types.-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc133">11.3.3</A>&#XA0;&#XA0;Generating TypeCodes for constructed types.</H3><!--SEC END --><P>To generate a TypeCode for constructed types, specify the
<TT>-Wba</TT> command-line flag when running omniidl. This will
generate a <TT>_tc_</TT> TypeCode describing the type, at the same
scope as the type. Example:</P><DIV CLASS="lstlisting"><I>// IDL 6</I>
<B>struct</B> Test6 {
  <B>double</B> a;
  <B>sequence</B>&lt;<B>long</B>&gt; b;
};</DIV><P>A TypeCode, <TT>_tc_Test6</TT>, will be generated to describe the
struct <TT>Test6</TT>. The operations defined in the TypeCode interface
can be used to query the TypeCode about the type it represents.</P><!--TOC section Source Listing-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc134">11.4</A>&#XA0;&#XA0;Source Listing</H2><!--SEC END --><!--TOC subsection anyExample_impl.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc135">11.4.1</A>&#XA0;&#XA0;anyExample_impl.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// anyExample_impl.cc - This is the source code of the example used in</I>
<I>//                      Chapter 9 "Type Any and TypeCode" of the omniORB</I>
<I>//                      users guide.</I>
<I>//</I>
<I>//                      This is the object implementation.</I>
<I>//</I>
<I>// Usage: anyExample_impl</I>
<I>//</I>
<I>//        On startup, the object reference is printed to cout as a</I>
<I>//        stringified IOR. This string should be used as the argument to </I>
<I>//        anyExample_clt.</I>
<I>//</I>

<B>#include</B> &lt;anyExample.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>

<B>class</B> anyExample_i : <B>public</B> POA_anyExample {
<B>public</B>:
  <B>inline</B> anyExample_i() {}
  <B>virtual</B> ~anyExample_i() {}
  <B>virtual</B> CORBA::Any* testOp(<B>const</B> CORBA::Any&amp; a);
};


CORBA::Any* anyExample_i::testOp(<B>const</B> CORBA::Any&amp; a)
{
  cout &lt;&lt; "Any received, containing: " &lt;&lt; endl;

<B>#ifndef</B> NO_FLOAT
  CORBA::Double d;
<B>#endif</B>

  CORBA::Long l;
  <B>const</B> <B>char</B>* str;

  testStruct* tp;


  <B>if</B> (a &gt;&gt;= l) {
    cout &lt;&lt; "Long: " &lt;&lt; l &lt;&lt; endl;
  }
<B>#ifndef</B> NO_FLOAT
  <I>// XXX - should we provide stream ops for _CORBA_Double_ and</I>
  <I>// _CORBA_Float_on VMS??</I>
  <B>else</B> <B>if</B> (a &gt;&gt;= d) {
    cout &lt;&lt; "Double: " &lt;&lt; (<B>double</B>)d &lt;&lt; endl;
  }
<B>#endif</B>
  <B>else</B> <B>if</B> (a &gt;&gt;= str) {
    cout &lt;&lt; "String: " &lt;&lt; str &lt;&lt; endl;
  }
  <B>else</B> <B>if</B> (a &gt;&gt;= tp) {
    cout &lt;&lt; "testStruct: l: " &lt;&lt; tp-&gt;l &lt;&lt; endl;
    cout &lt;&lt; "            s: " &lt;&lt; tp-&gt;s &lt;&lt; endl;
  }
  <B>else</B> {
    cout &lt;&lt; "Unknown value." &lt;&lt; endl;
  }

  CORBA::Any* ap = <B>new</B> CORBA::Any;

  *ap &lt;&lt;= (CORBA::ULong) 314;

  cout &lt;&lt; "Returning Any containing: ULong: 314\n" &lt;&lt; endl;
  <B>return</B> ap;
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    CORBA::Object_var obj = orb-&gt;resolve_initial_references("RootPOA");
    PortableServer::POA_var poa = PortableServer::POA::_narrow(obj);

    anyExample_i* myobj = <B>new</B> anyExample_i();

    PortableServer::ObjectId_var myobjid = poa-&gt;activate_object(myobj);

    obj = myobj-&gt;_this();
    CORBA::String_var sior(orb-&gt;object_to_string(obj));
    cout &lt;&lt; (<B>char</B>*)sior &lt;&lt; endl;

    myobj-&gt;_remove_ref();

    PortableServer::POAManager_var pman = poa-&gt;the_POAManager();
    pman-&gt;activate();

    orb-&gt;run();
    orb-&gt;destroy();
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}</DIV><!--TOC subsection anyExample_clt.cc-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc136">11.4.2</A>&#XA0;&#XA0;anyExample_clt.cc</H3><!--SEC END --><DIV CLASS="lstlisting"><I>// anyExample_clt.cc -  This is the source code of the example used in </I>
<I>//                      Chapter 9 "Type Any and TypeCode" of the omniORB</I>
<I>//                      users guide.</I>
<I>//</I>
<I>//                      This is the client.</I>
<I>//</I>
<I>// Usage: anyExample_clt &lt;object reference&gt;</I>
<I>//</I>

<B>#include</B> &lt;anyExample.hh&gt;

<B>#ifdef</B> HAVE_STD
<B>#  include</B> &lt;iostream&gt;
   <B>using</B> <B>namespace</B> std;
<B>#else</B>
<B>#  include</B> &lt;iostream.h&gt;
<B>#endif</B>


<B>static</B> <B>void</B> invokeOp(anyExample_ptr&amp; tobj, <B>const</B> CORBA::Any&amp; a)
{
  CORBA::Any_var bp;

  cout &lt;&lt; "Invoking operation." &lt;&lt; endl;
  bp = tobj-&gt;testOp(a);

  cout &lt;&lt; "Operation completed. Returned Any: ";
  CORBA::ULong ul;

  <B>if</B> (bp &gt;&gt;= ul) {
    cout &lt;&lt; "ULong: " &lt;&lt; ul &lt;&lt; "\n" &lt;&lt; endl;
  }
  <B>else</B> {
    cout &lt;&lt; "Unknown value." &lt;&lt; "\n" &lt;&lt; endl;
  }
}


<B>static</B> <B>void</B> hello(anyExample_ptr tobj)
{
  CORBA::Any a;

  <I>// Sending Long</I>
  CORBA::Long l = 100;
  a &lt;&lt;= l;
  cout &lt;&lt; "Sending Any containing Long: " &lt;&lt; l &lt;&lt; endl;
  invokeOp(tobj,a);

  <I>// Sending Double</I>
<B>#ifndef</B> NO_FLOAT
  CORBA::Double d = 1.2345;
  a &lt;&lt;= d;
  cout &lt;&lt; "Sending Any containing Double: " &lt;&lt; d &lt;&lt; endl;
  invokeOp(tobj,a);
<B>#endif</B>

  <I>// Sending String</I>
  <B>const</B> <B>char</B>* str = "Hello";
  a &lt;&lt;= str;
  cout &lt;&lt; "Sending Any containing String: " &lt;&lt; str &lt;&lt; endl;
  invokeOp(tobj,a);

  <I>// Sending testStruct  [Struct defined in IDL]</I>
  testStruct t;
  t.l = 456;
  t.s = 8;
  a &lt;&lt;= t;
  cout &lt;&lt; "Sending Any containing testStruct: l: " &lt;&lt; t.l &lt;&lt; endl;
  cout &lt;&lt; "                                   s: " &lt;&lt; t.s &lt;&lt; endl;
  invokeOp(tobj,a);
}

<I>//////////////////////////////////////////////////////////////////////</I>

<B>int</B> main(<B>int</B> argc, <B>char</B>** argv)
{
  <B>try</B> {
    CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

    <B>if</B>( argc != 2 ) {
      cerr &lt;&lt; "usage:  anyExample_clt &lt;object reference&gt;" &lt;&lt; endl;
      <B>return</B> 1;
    }

    {
      CORBA::Object_var obj = orb-&gt;string_to_object(argv[1]);
      anyExample_var ref = anyExample::_narrow(obj);
      <B>if</B>( CORBA::is_nil(ref) ) {
        cerr &lt;&lt; "Can't narrow reference to type anyExample (or it was nil)."
             &lt;&lt; endl;
        <B>return</B> 1;
      }
      hello(ref);
    }
    orb-&gt;destroy();
  }
  <B>catch</B>(CORBA::TRANSIENT&amp;) {
    cerr &lt;&lt; "Caught system exception TRANSIENT -- unable to contact the "
         &lt;&lt; "server." &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::SystemException&amp; ex) {
    cerr &lt;&lt; "Caught a CORBA::" &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(CORBA::Exception&amp; ex) {
    cerr &lt;&lt; "Caught CORBA::Exception: " &lt;&lt; ex._name() &lt;&lt; endl;
  }
  <B>catch</B>(omniORB::fatalException&amp; fe) {
    cerr &lt;&lt; "Caught omniORB::fatalException:" &lt;&lt; endl;
    cerr &lt;&lt; "  file: " &lt;&lt; fe.file() &lt;&lt; endl;
    cerr &lt;&lt; "  line: " &lt;&lt; fe.line() &lt;&lt; endl;
    cerr &lt;&lt; "  mesg: " &lt;&lt; fe.errmsg() &lt;&lt; endl;
  }
  <B>return</B> 0;
}</DIV><!--TOC chapter Packaging stubs into DLLs-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc137">Chapter&#XA0;12</A>&#XA0;&#XA0;Packaging stubs into DLLs</H1><!--SEC END --><P>
<A NAME="chap:dlls"></A></P><P>omniORB&#X2019;s stubs can be packaged into shared libraries or DLLs. On Unix
platforms this is mostly painless, but on Windows things are slightly
more tricky.</P><!--TOC section Dynamic loading and unloading-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc138">12.1</A>&#XA0;&#XA0;Dynamic loading and unloading</H2><!--SEC END --><P>As long as your platform supports running static initialisers and
destructors as libraries are loaded and unloaded, you can package
stubs into shared libraries / DLLs, and load them dynamically at
runtime.</P><P>There is one minor problem with this, which is that normally nil
object references are heap allocated, and only deallocated when the
ORB is destroyed. That means that if you unload a stub library from
which nil references have been obtained (just by creating an object
reference _var for example), there is a risk of a segmentation fault
when the ORB is destroyed. To avoid that problem, define the
<TT>OMNI_UNLOADABLE_STUBS</TT> C pre-processor symbol while you are
compiling the stub files. Unfortunately, with that define set, there
is a risk that object reference _vars at global scope will segfault
as they are unloaded. You must not create _vars at global scope if
you are using <TT>OMNI_UNLOADABLE_STUBS</TT>.</P><!--TOC section Windows DLLs-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc139">12.2</A>&#XA0;&#XA0;Windows DLLs</H2><!--SEC END --><P>On Unix platforms, the linker figures out how to link the symbols
exported by a library in to the running program. On Windows,
unfortunately, you have to tell the linker where symbols are coming
from. This causes all manner of difficulties.</P><!--TOC subsection Exporting symbols-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc140">12.2.1</A>&#XA0;&#XA0;Exporting symbols</H3><!--SEC END --><P>To (statically) link with a DLL file in Windows, you link with a LIB
file which references the symbols exported from the DLL. To build the
LIB and DLL files, the correct symbols must be exported. One way to do
that is to decorate the source code with magic tags that tell the
compiler to export the symbols. The alternative is to provide a DEF
file that lists all the symbols to be exported. omniORB uses a DEF
file.</P><P>The question is, how do you create the DEF file? The answer is to use
a Python script named <TT>makedeffile.py</TT> that lives in the
<TT>bin\scripts</TT> directory in the omniORB distribution.
<TT>makedeffile.py</TT> runs the dumpbin program that comes with
Visual C++, and processes its output to extract the necessary symbols.
Although it is designed for exporting the symbols from omniORB stub
files, it can actually be used for arbitrary C++ code. To use it to
create a DLL from a single source file, use the following steps:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
Compile the source:<P><TT>cl -c -O2 -MD -GX -Fofoo.o -Tpfoo.cc</TT></P></LI><LI CLASS="li-enumerate">Build a static library (It probably won&#X2019;t work on its own due to
the -MD switch to cl, but we just need it to get the symbols
out):<P><TT>lib -out:foo_static.lib foo.o</TT></P></LI><LI CLASS="li-enumerate">Use the script to build a .def file:<P><TT>makedeffile.py foo_static.lib foo 1.0 foo.def</TT></P></LI><LI CLASS="li-enumerate">Build the .dll and .lib with the def file.<P><TT>link -out:foo.dll -dll -def:foo.def -implib:foo.lib foo.o</TT>
</P></LI></OL><P>Of course, you can link together many separate C++ files, rather than
just the one shown here.</P><!--TOC subsection Importing constant symbols-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc141">12.2.2</A>&#XA0;&#XA0;Importing constant symbols</H3><!--SEC END --><P>As if exporting the symbols from a DLL was not complicated enough, any
constant values exported by a DLL have to be explicitly
<EM>imported</EM> into the code using them. omniORB&#X2019;s stub files declare
a number of such constants. This time, the constant declarations in
the generated header files are decorated in a way that tells the
compiler what to do. When the stub headers are #included, the correct
pre-processor defines must be set. If things are not set correctly,
the code all links without problems, but then mysteriously blows up at
run time.</P><P>Depending on how complex your situation is, there are a range of
solutions. Starting with the simplest, here are some scenarios you may
find yourself in:</P><OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">All stub code, and all code that uses it is wrapped up in a
single DLL.<P>Do nothing special.</P></LI><LI CLASS="li-enumerate">All stub code is in a single DLL. Code using it is in another
DLL, or not in a DLL at all.<P><TT>#define USE_stub_in_nt_dll</TT> before <TT>#include</TT> of
the stub headers.</P></LI><LI CLASS="li-enumerate">The stubs for each IDL file are in separate DLLs, one DLL per
IDL file.<P>In this case, if the IDL files <TT>#include</TT> each other, when
the stub files are compiled, import declarations are needed so
that references between the separate DLLs work. To do this,
first compile the IDL files with the <TT>-Wbdll_stubs</TT>
flag:</P><P><TT>omniidl -bcxx -Wbdll_stubs example.idl</TT></P><P>Then define the <TT>INCLUDED_stub_in_nt_dll</TT> pre-processor
symbol when compiling the stub files. As above, define
<TT>USE_stub_in_nt_dll</TT> when including the stub headers
into application code.</P></LI><LI CLASS="li-enumerate">Stubs and application code are packaged into multiple DLLs, but
DLLs contain the stubs for more than one IDL file.<P>This situation is handled by &#X2018;annotating&#X2019; the IDL files to
indicate which DLLs they will be compiled into. The annotation
takes the form of some <TT>#ifdefs</TT> to be inserted in the
stub headers. For example,</P><DIV CLASS="lstlisting"><I>// one.idl</I>

<B>#pragma</B> hh #ifndef COMPILING_FIRST_DLL
<B>#pragma</B> hh # ifndef USE_stub_in_nt_dll
<B>#pragma</B> hh #   define USE_stub_in_nt_dll
<B>#pragma</B> hh # endif
<B>#pragma</B> hh #endif

<B>#include</B> &lt;two.idl&gt;

<B>module</B> ModuleOne {
  ...
};


<I>// two.idl</I>

<B>#pragma</B> hh #ifndef COMPILING_SECOND_DLL
<B>#pragma</B> hh # ifndef USE_stub_in_nt_dll
<B>#pragma</B> hh #   define USE_stub_in_nt_dll
<B>#pragma</B> hh # endif
<B>#pragma</B> hh #endif

<B>#include</B> &lt;three.idl&gt;
...</DIV><P>Here, <TT>one.idl</TT> is packaged into <TT>first.dll</TT> and
<TT>two.idl</TT> is in <TT>second.dll</TT>. When compiling
<TT>first.dll</TT>, the <TT>COMPILING_FIRST_DLL</TT> define is
set, meaning definitions from <TT>one.idl</TT> (and any other
files in that DLL) are not imported. Any other module that
includes the stub header for <TT>one.idl</TT> does not define
<TT>COMPILING_FIRST_DLL</TT>, and thus imports the necessary
symbols from the DLL.</P><P>Rather than explicitly listing all the pre-processor code, it
can be cleaner to use a C++ header file for each DLL. See the
COS services IDL files in <TT>idl/COS</TT> for an example.</P></LI></OL><!--TOC chapter Objects by value, etc.-->
<H1 CLASS="chapter"><!--SEC ANCHOR --><A NAME="htoc142">Chapter&#XA0;13</A>&#XA0;&#XA0;Objects by value, abstract interfaces and local interfaces</H1><!--SEC END --><P>
<A NAME="chap:valuetype"></A></P><P>omniORB 4.1 supports objects by value, declared with the
<TT>valuetype</TT> keyword in IDL, and both abstract and local
interfaces. This chapter outlines some issues to do with using these
types in omniORB. You are assumed to have read the relevant parts of
the CORBA specification, specifically chapters 3, 4, 5 and 6 of the
CORBA 2.6 specification, and sections 1.17, 1.18 and 1.35 of the C++
mapping specification, version 1.1.</P><!--TOC section Features-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc143">13.1</A>&#XA0;&#XA0;Features</H2><!--SEC END --><P>omniORB supports the complete objects by value specification, with the
exception of custom valuetypes. All other valuetype features including
value boxes, value sharing semantics, abstract valuetypes, and
abstract interfaces are supported. Local interfaces are supported,
with a number of caveats outlined in
section&#XA0;<A HREF="#sec:LocalInterfaces">13.8</A>.</P><!--TOC section Reference counting-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc144">13.2</A>&#XA0;&#XA0;Reference counting</H2><!--SEC END --><P>Values are reference counted. This means that, as long as your
application properly manages reference counts, values are usually
automatically deleted when they are no longer required. However, one
of the features of valuetypes is that they support the representation
of cyclic graph structures. In that kind of situation, the reference
counting garbage collection does not work, because references internal
to the graph prevent the reference counts ever becoming zero.</P><P>To avoid memory leaks, application code must explicitly break any
reference cycles in values it manipulates. This includes graphs of
values received as parameters and return values from CORBA operations.</P><!--TOC section Value sharing and local calls-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc145">13.3</A>&#XA0;&#XA0;Value sharing and local calls</H2><!--SEC END --><P>When valuetypes are passed as parameters in CORBA calls (i.e. calls
on CORBA objects declared with <TT>interface</TT> in IDL), the structure
of related values is maintained. Consider, for example, the following
IDL definitions (which are from the example code in
<TT>src/examples/valuetype/simple</TT>:</P><DIV CLASS="lstlisting"><B>module</B> ValueTest {
  <B>valuetype</B> One {
    <B>public</B> <B>string</B> s;
    <B>public</B> <B>long</B>   l;
  };

  <B>interface</B> Test {
    One op1(<B>in</B> One a, <B>in</B> One b);
  };
};</DIV><P>If the client to the <TT>Test</TT> object passes the same value in both
parameters, just one value is transmitted, and the object
implementation receives a copy of the single value, with references to
it in both parameters.</P><P>In the case that the object is remote from the client, there is
obviously a copying step involved. In the case that the object is in
the same address space as the client, the same copying semantics must
be maintained so that the object implementation can modify the values
it receives without the client seeing the modifications. To support
that, omniORB must copy the entire parameter list in one operation, in
case there is sharing between different parameters. Such copying is a
rather more time-consuming process than the parameter-by-parameter
copy that takes place in calls not involving valuetypes.</P><P>To avoid the overhead of copying parameters in this way, applications
can choose to relax the semantics of value copying in local calls, so
values are not copied at all, but are passed by reference. In that
case, the client to a call <EM>will</EM> see any modifications to the
values it passes as parameters (and similarly, the object
implementation will see any changes the client makes to returned
values). To choose this option, set the <TT>copyValuesInLocalCalls</TT>
configuration parameter to zero.</P><!--TOC section Value box factories-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc146">13.4</A>&#XA0;&#XA0;Value box factories</H2><!--SEC END --><P>With normal valuetypes, omniidl generates factory classes (with names
ending <TT>_init</TT>) as required by the C++ mapping specification.
The application is responsible for registering the factories with the
ORB.</P><P>Unfortunately, the C++ mapping makes no mention of factories for value
boxes. In omniORB, factories for value boxes are automatically
registered with the ORB, and there are no application-visible factory
classes generated for them. Some other CORBA implementations generate
application visible factories, and the application <EM>does</EM> have to
register the factories with the ORB.</P><!--TOC section Standard value boxes-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc147">13.5</A>&#XA0;&#XA0;Standard value boxes</H2><!--SEC END --><P>The standard <TT>CORBA::StringValue</TT> and <TT>CORBA::WStringValue</TT>
value boxes are available to application code. To make the definitions
available in IDL, #include the standard <TT>orb.idl</TT>.</P><!--TOC section Covariant returns-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc148">13.6</A>&#XA0;&#XA0;Covariant returns</H2><!--SEC END --><P>As required by the C++ mapping, on C++ compilers that support
covariant return types, omniidl generates code for the
<TT>_copy_value()</TT> function that returns the most derived type of the
value. On older compilers, <TT>_copy_value()</TT> returns
<TT>CORBA::ValueBase</TT>.</P><P>If you write code that calls <TT>_copy_value()</TT>, and you need to
support older compilers, you should assign the result to a variable of
type <TT>CORBA::ValueBase*</TT> and downcast to the target type, rather
than using the covariant return.</P><P>If you are overriding <TT>_copy_value()</TT>, you must correctly take
account of the <TT>OMNI_HAVE_COVARIANT_RETURNS</TT> preprocessor
definition.</P><!--TOC section Values inside Anys-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc149">13.7</A>&#XA0;&#XA0;Values inside Anys</H2><!--SEC END --><P>Valuetypes inserted into Anys cause a number of interesting issues.
Even when inside Anys, values are required to support complete sharing
semantics. Take this IDL for example:</P><DIV CLASS="lstlisting"><B>module</B> ValueTest {
  <B>valuetype</B> One {
    <B>public</B> <B>string</B> s;
    <B>public</B> <B>long</B>   l;
  };

  <B>interface</B> AnyTest {
    <B>void</B> op1(<B>in</B> One v, <B>in</B> Any a);
  };
};</DIV><P>Now, suppose the client behaves as follows:</P><DIV CLASS="lstlisting">ValueTest::One* v = <B>new</B> One_impl("hello", 123);
CORBA::Any a;
a &lt;&lt;= v;
obj-&gt;op1(v, a);</DIV><P>then on the server side:</P><DIV CLASS="lstlisting"><B>void</B> AnyTest_impl::op1(ValueTest::One* v, CORBA::Any&amp; a)
{
  ValueTest::One* v2;
  a &gt;&gt;= v2;
  assert(v2 == v);
}</DIV><P>This is all very well in this kind of simple situation, but problems
can arise if truncatable valuetypes are used. Imagine this derived
value:</P><DIV CLASS="lstlisting"><B>module</B> ValueTest {
  <B>valuetype</B> Two : <B>truncatable</B> One {
    <B>public</B> <B>double</B> d;
  };
};</DIV><P>Now, suppose that the client shown above sends an instance of
valuetype <TT>Two</TT> in both parameters, and suppose that the server
has not seen the definition of valuetype <TT>Two</TT>. In this
situation, as the first parameter is unmarshalled, it will be
truncated to valuetype <TT>One</TT>, as required. Now, when the Any is
unmarshalled, it refers to the same value, which has been truncated.
So, even though the TypeCode in the Any indicates that the value has
type <TT>Two</TT>, the stored value actually has type <TT>One</TT>. If the
receiver of the Any tries to pass it on, transmission will fail
because the Any&#X2019;s value does not match its TypeCode.</P><P>In the opposite situation, where an Any parameter comes before a
valuetype parameter, a different problem occurs. In that case, as the
Any is unmarshalled, there is no type information available for
valuetype <TT>Two</TT>, so the value inside the Any has an internal
omniORB type used for unknown valuetypes. As the next parameter is
unmarshalled, omniORB sees that the shared value is unknown, and is
able to convert it to the target <TT>One</TT> valuetype with
truncation. In this case, the Any and the plain valuetype both have
the correct types and values, but the fact that both should have
referred to the same value has been lost.</P><P>Because of these issues, it is best to avoid defining interfaces that
mix valuetypes and Anys in a single operation, and certainly to avoid
trying to share plain values with values inside Anys.</P><!--TOC subsection Values inside DynAnys-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc150">13.7.1</A>&#XA0;&#XA0;Values inside DynAnys</H3><!--SEC END --><P>The sharing semantics of valuetypes can also cause difficulties for
DynAny. The CORBA 2.6 specification does not mention how shared values
inside DynAnys should be handled; the CORBA 3.x specification slightly
clarifies the situation, but it is still unclear. To write portable
code it is best to avoid manipulating DynAnys containing values that
are shared.</P><P>In omniORB, when a value inside an Any is converted into a DynAny, the
value&#X2019;s state is copied into the DynAny, and manipulated there. When
converting back to an Any a new value is created. This means that any
other references to the original value (whether themselves inside Anys
of not) still relate to the original value, with unchanged state.
However, this copying only occurs when a DynValue is actually created,
so for example a structure with two value members referring to the
same value can manipulated inside a DynAny without breaking the
sharing, provided the value members are not accessed as DynAnys.
Extracting the value members as ValueBase will reveal the sharing, for
example.</P><!--TOC section Local Interfaces-->
<H2 CLASS="section"><!--SEC ANCHOR --><A NAME="htoc151">13.8</A>&#XA0;&#XA0;Local Interfaces</H2><!--SEC END --><P>
<A NAME="sec:LocalInterfaces"></A></P><P>Local interfaces are somewhat under-specified in the C++ mapping. This
section outlines the way local interfaces are supported in omniORB,
and details the limitations and issues.</P><!--TOC subsection Simple local interfaces-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc152">13.8.1</A>&#XA0;&#XA0;Simple local interfaces</H3><!--SEC END --><P>With simple IDL, there are no particular issues:</P><DIV CLASS="lstlisting"><B>module</B> Test {
  <B>local</B> <B>interface</B> Example {
    <B>string</B> hello(<B>in</B> <B>string</B> arg);
  };
};</DIV><P>The IDL compiler generates an abstract base class
<TT>Test::Example</TT>. The application defines a class derived from it
that implements the abstract <TT>hello()</TT> member function. Instances of
that class can then be used where the IDL specifies interface
<TT>Example</TT>.</P><P>Note that, by default, local interface implementations have no
reference counting behaviour. If the local object should be deleted
when the last reference is released, the application must implement
the <TT>_add_ref()</TT> and <TT>_remove_ref()</TT> virtual member functions
within the implementation class. Make sure that the implementations
are thread safe.</P><!--TOC subsection Inheritance from unconstrained interfaces-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc153">13.8.2</A>&#XA0;&#XA0;Inheritance from unconstrained interfaces</H3><!--SEC END --><P>Local interfaces can inherit from unconstrained (i.e. non-local)
interfaces:</P><DIV CLASS="lstlisting"><B>module</B> Test {
  <B>interface</B> One {
    <B>void</B> problem(<B>inout</B> <B>string</B> arg);
  };
  <B>local</B> <B>interface</B> Two : One {
  };

  <B>interface</B> Receiver {
    <B>void</B> setOne(<B>in</B> One a);
  };
};</DIV><P>IDL like this leads to two issues to do with omniORB&#X2019;s C++ mapping
implementation.</P><P>First, an instance of local interface <TT>Two</TT> should be suitable to
pass as the argument to the <TT>setOne()</TT> method of a <TT>Receiver</TT>
object (as long as the object is in the same address space as the
caller). Therefore, the <TT>Two</TT> abstract base class has to inherit
from the internal class omniORB uses to map object references of type
<TT>One</TT>. For performance reasons, the class that implements
<TT>One</TT> object references normally has non-virtual member
functions. That means that the application-supplied <TT>problem()</TT>
member function for the implementation of local interface <TT>Two</TT>
will not override the base class&#X2019;s version. To overcome this, the IDL
for the base unconstrained interface must be compiled with the
-Wbvirtual_objref switch to omniidl. That makes the member functions
of the mapping of <TT>One</TT> into virtual functions, so they can be
overridden.</P><P>The second problem is that, in some cases, omniORB uses a different
mapping for object reference member functions than the mapping used in
servant classes. For example, in the <TT>problem()</TT> operation, it uses
an internal type for the inout string argument that avoids memory
issues if the application uses a String_var in the argument. This
means that the abstract member function declared in the <TT>Two</TT>
class (and implemented by the application) has a different signature
to the member function in the base class. The application-supplied
class will therefore not properly override the base class method. In
all likelihood, the C++ compiler will also complain that the two
member functions are ambiguous. The solution to this problem is to use
the implementation mapping in the base object reference class, rather
than the normal object reference mapping, using the -Wbimpl_mapping
switch to omniidl. The consequence of this is that some uses of _var
types for inout arguments that are normally acceptable in omniORB now
lead to memory problems.</P><P>In summary, to use local interfaces derived from normal unconstrained
interfaces, you should compile all your IDL with the omniidl flags:</P><BLOCKQUOTE CLASS="quote">
<TT>-Wbvirtual_objref -Wbimpl_mapping</TT>
</BLOCKQUOTE><!--TOC subsection Valuetypes supporting local interfaces-->
<H3 CLASS="subsection"><!--SEC ANCHOR --><A NAME="htoc154">13.8.3</A>&#XA0;&#XA0;Valuetypes supporting local interfaces</H3><!--SEC END --><P>According to the IDL specification, it should be possible to declare a
valuetype that supports a local interface:</P><DIV CLASS="lstlisting"><B>local</B> <B>interface</B> I {
  <B>void</B> my_operation();
};
<B>valuetype</B> V <B>supports</B> I {
  <B>public</B> <B>string</B> s;
};</DIV><P>omniidl accepts the IDL, but unfortunately the resulting C++ code does
not compile. The C++ mapping specification has a problem in that both
the <TT>CORBA::LocalObject</TT> and <TT>CORBA::ValueBase</TT>
classes have <TT>add_ref()</TT> and <TT>remove_ref()</TT> member functions
defined. The classes generated for the valuetype inherit from both
these base classes, and therefore have an ambiguity. Until the C++
mapping resolves this conflict, valuetypes supporting local interfaces
cannot be used in omniORB.</P><!--TOC chapter References-->
<H1 CLASS="chapter"><!--SEC ANCHOR -->References</H1><!--SEC END --><DL CLASS="thebibliography"><DT CLASS="dt-thebibliography">
<A NAME="rfc2396"><FONT COLOR=purple>[BLFIM98]</FONT></A></DT><DD CLASS="dd-thebibliography">
T. Berners-Lee, R. Fielding, U.C. Irvine, and L. Masinter.
<EM>U</EM><EM>niform </EM><EM>R</EM><EM>esource </EM><EM>I</EM><EM>dentifiers (</EM><EM>URI</EM><EM>): Generic Syntax</EM>.
RFC 2396, August 1998.</DD><DT CLASS="dt-thebibliography"><A NAME="henning1999"><FONT COLOR=purple>[HV99]</FONT></A></DT><DD CLASS="dd-thebibliography">
Michi Henning and Steve Vinoski.
<EM>Advanced </EM><EM>CORBA</EM><EM> Programming with </EM><EM>C++</EM>.
Addison-Wesley professional computing series, 1999.</DD><DT CLASS="dt-thebibliography"><A NAME="corbaservices"><FONT COLOR=purple>[OMG98]</FONT></A></DT><DD CLASS="dd-thebibliography">
Object Management Group.
<EM>CORBAServices</EM><EM>: Common Object Services Specification</EM>, December
1998.</DD><DT CLASS="dt-thebibliography"><A NAME="inschapters"><FONT COLOR=purple>[OMG00]</FONT></A></DT><DD CLASS="dd-thebibliography">
Object Management Group.
<EM>Interoperable Naming Service revised chapters</EM>, August 2000.
From <A HREF="http://www.omg.org/cgi-bin/doc?ptc/00-08-07"><TT>http://www.omg.org/cgi-bin/doc?ptc/00-08-07</TT></A>.</DD><DT CLASS="dt-thebibliography"><A NAME="corba26-spec"><FONT COLOR=purple>[OMG01]</FONT></A></DT><DD CLASS="dd-thebibliography">
Object Management Group.
<EM>The </EM><EM>C</EM><EM>ommon </EM><EM>O</EM><EM>bject </EM><EM>R</EM><EM>equest </EM><EM>B</EM><EM>roker: </EM><EM>A</EM><EM>rchitecture and
Specification</EM>, 2.6 edition, December 2001.
From <A HREF="http://www.omg.org/cgi-bin/doc?formal/01-12-01"><TT>http://www.omg.org/cgi-bin/doc?formal/01-12-01</TT></A>.</DD><DT CLASS="dt-thebibliography"><A NAME="cxxmapping"><FONT COLOR=purple>[OMG03]</FONT></A></DT><DD CLASS="dd-thebibliography">
Object Management Group.
<EM>C++ Language Mapping</EM>, 1.1 edition, 2003.
From <A HREF="http://www.omg.org/cgi-bin/doc?formal/03-06-03"><TT>http://www.omg.org/cgi-bin/doc?formal/03-06-03</TT></A>.</DD><DT CLASS="dt-thebibliography"><A NAME="tjr96a"><FONT COLOR=purple>[Ric96]</FONT></A></DT><DD CLASS="dd-thebibliography">
Tristan Richardson.
<EM>The </EM><EM>OMNI</EM><EM> Thread Abstraction</EM>.
AT&amp;T Laboratories Cambridge, October 1996.</DD></DL><!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://hevea.inria.fr/index.html"><EM>H</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>V</EM><EM><FONT SIZE=2><sup>E</sup></FONT></EM><EM>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY>
</HTML>