<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.06">
<TITLE>
omniORB configuration and API
</TITLE>
</HEAD>
<BODY >
<A HREF="omniORBpy003.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="omniORBpy005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>
<H1><A NAME="htoc38">Chapter 4</A> omniORB configuration and API</H1>
<A NAME="chap:config"></A>
omniORB 4.0, and thus omniORBpy 2, has a wide range of parameters that
can be configured. They can be set in the configuration file / Windows
registry, as environment variables, or on the command line. A few
parameters can be configured at run time. This chapter lists all the
configuration parameters, and how they are used.<BR>
<BR>
<A NAME="toc13"></A>
<H2><A NAME="htoc39">4.1</A> Setting parameters</H2>
When <TT>CORBA::ORB_init()</TT> is called, the value for each configuration
parameter is searched for in the following order:
<OL type=1><LI>Command line arguments
<LI>Environment variables
<LI>Configuration file / Windows registry
<LI>Built-in defaults</OL>
<H3><A NAME="htoc40">4.1.1</A> Command line arguments</H3>
<A NAME="sec:ORBargs"></A>
Command line arguments take the form
`<TT>-ORB</TT><I>parameter</I>', and usually expect another
argument. An example is `<TT>-ORBtraceLevel 10</TT>'.<BR>
<BR>
<H3><A NAME="htoc41">4.1.2</A> Environment variables</H3>
Environment variables consist of the parameter name prefixed with
`<TT>ORB</TT>'. Using bash, for example
<PRE>
export ORBtraceLevel=10
</PRE>
<H3><A NAME="htoc42">4.1.3</A> Configuration file</H3>
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
<PRE>
traceLevel = 10
</PRE>
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:
<PRE>
InitRef = NameService=corbaname::host1.example.com
= InterfaceRepository=corbaloc::host2.example.com:1234/IfR
</PRE>
<HR SIZE=2><DL COMPACT=compact><DT><DD>
Note how command line arguments and environment variables prefix
parameter names with `-ORB' and `ORB' respectively, but the
configuration file and the extra argument to <TT>ORB_init()</TT> do not use
a prefix.
</DL><HR SIZE=2><BR>
<BR>
<H3><A NAME="htoc43">4.1.4</A> Windows registry</H3>
On Windows, configuration parameters can be stored in the registry,
under the key
<CODE>HKEY_LOCAL_MACHINE\SOFTWARE\omniORB</CODE>.<BR>
<BR>
The file <TT>sample.reg</TT> shows the settings that can be made. It can
be edited and then imported into regedit.<BR>
<BR>
<A NAME="toc14"></A>
<H2><A NAME="htoc44">4.2</A> Tracing options</H2>
The following options control debugging trace output.<BR>
<BR>
<TT>traceLevel</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
omniORB can output tracing and diagnostic messages to the standard
error stream. The following levels are defined:<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD VALIGN=top ALIGN=left NOWRAP> </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><BR>
The trace level is cumulative, so at level 40, all trace
messages are output.<BR>
<BR>
<TT>traceInvocations</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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>.<BR>
<BR>
<TT>traceThreadId</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<H3><A NAME="htoc45">4.2.1</A> Tracing API</H3>
The three tracing parameters can be inspected or modified at runtime
with the <TT>traceLevel()</TT>, <TT>traceInvocations()</TT> and <TT>traceThreadId()</TT>
functions in the <TT>omniORB</TT> module. Calling one of the functions
with no arguments returns the current value; calling it with a single
integer argument sets the value.<BR>
<BR>
<A NAME="toc15"></A>
<H2><A NAME="htoc46">4.3</A> Miscellaneous global options</H2>
These options control miscellaneous features that affect the whole ORB
runtime.<BR>
<BR>
<TT>dumpConfiguration</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
If set true, the ORB dumps the values of all configuration parameters
at start-up.<BR>
<BR>
<TT>scanGranularity</TT> <I>default</I> =
<TT>5</TT><BR>
<BR>
<BR>
As explained in chapter <A HREF="omniORBpy007.html#chap:connections">749Connection and Thread Managementchapter.7</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.<BR>
<BR>
<TT>nativeCharCodeSet</TT> <I>default</I> =
<TT>ISO-8859-1</TT><BR>
<BR>
<BR>
The native code set the application is using for <TT>char</TT> and
<TT>string</TT>. See chapter <A HREF="omniORBpy008.html#chap:codesets">859Code set conversionchapter.8</A>.<BR>
<BR>
<TT>omniORB_27_CompatibleAnyExtraction</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
In omniORB 2.7 and earlier, the Any extraction operators for strings
and object references returned a copy/duplicate of the value stored in
the Any, meaning the caller had to release the extracted value. The
C++ mapping was clarified to state that the Any retains ownership of
the returned value, so the caller does not need to release it. To aid
the transition for ancient programs from omniORB 2.7 or earlier,
setting this flag to true selects the old copying behaviour.<BR>
<BR>
<TT>abortOnInternalError</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<A NAME="toc16"></A>
<H2><A NAME="htoc47">4.4</A> Client side options</H2>
These options control aspects of client-side behaviour.<BR>
<BR>
<TT>InitRef</TT> <I>default</I> =
<TT><I>none</I></TT><BR>
<BR>
<BR>
Specify the objects available from
<TT>ORB::resolve_initial_references()</TT>. The arguments take the form
<<I>key</I>>=<<I>uri</I>>, where the <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 <A HREF="omniORBpy006.html#chap:ins">641Interoperable Naming Servicechapter.6</A>.<BR>
<BR>
<TT>DefaultInitRef</TT> <I>default</I> =
<TT><I>none</I></TT><BR>
<BR>
<BR>
Specify the default URI prefix for
<TT>resolve_initial_references()</TT>, as explained in
chapter <A HREF="omniORBpy006.html#chap:ins">641Interoperable Naming Servicechapter.6</A>.<BR>
<BR>
<TT>clientTransportRule</TT> <I>default</I> =
<TT>* unix,tcp,ssl</TT><BR>
<BR>
<BR>
Used to specify the way the client contacts a server, depending on the
server's address. See section <A HREF="omniORBpy007.html#sec:clientRule">7.7.155Client transport rulessubsection.7.7.1</A> for details.<BR>
<BR>
<TT>clientCallTimeOutPeriod</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
Call timeout in milliseconds for the client side. If a call takes
longer than the specified number of milliseconds, the ORB closes the
connection and raises a <TT>COMM_FAILURE</TT> exception. A value
of zero means no timeout; calls can block for ever. See
section <A HREF="omniORBpy007.html#sec:timeoutAPI">7.3.151Client side timeoutssubsection.7.3.1</A> for more information about timeouts.<BR>
<BR>
<B>Note</B>: omniORB 3 had timeouts specified in seconds; omniORB
4.0 uses milliseconds for timeouts.<BR>
<BR>
<TT>supportPerThreadTimeOut</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>outConScanPeriod</TT> <I>default</I> =
<TT>120</TT><BR>
<BR>
<BR>
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 <A HREF="omniORBpy007.html#sec:connShutdown">7.553Idle connection shutdownsection.7.5</A>.<BR>
<BR>
<TT>maxGIOPConnectionPerServer</TT> <I>default</I> =
<TT>5</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>oneCallPerConnection</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>offerBiDirectionalGIOP</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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 <A HREF="omniORBpy007.html#sec:bidir">7.856Bidirectional GIOPsection.7.8</A>.<BR>
<BR>
<TT>diiThrowsSysExceptions</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>verifyObjectExistsAndType</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
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'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.<BR>
<BR>
<TT>giopTargetAddressMode</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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>.<BR>
<BR>
<TT>bootstrapAgentHostname</TT> <I>default</I> =
<TT><I>none</I></TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>bootstrapAgentPort</TT> <I>default</I> =
<TT>900</TT><BR>
<BR>
<BR>
The port number for the obsolete Sun bootstrap agent.<BR>
<BR>
<TT>principal</TT> <I>default</I> =
<TT><I>none</I></TT><BR>
<BR>
<BR>
GIOP 1.0 and 1.1 have a request header field named `principal', 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.<BR>
<BR>
<A NAME="toc17"></A>
<H2><A NAME="htoc48">4.5</A> Server side options</H2>
These parameters affect server-side operations.<BR>
<BR>
<TT>endPoint </TT> <I>default</I> = <TT>giop:tcp::</TT><BR>
<TT>endPointNoListen</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 <A HREF="omniORBpy007.html#chap:connections">749Connection and Thread Managementchapter.7</A> for details.<BR>
<BR>
<TT>serverTransportRule</TT> <I>default</I> =
<TT>* unix,tcp,ssl</TT><BR>
<BR>
<BR>
Configure the rules about whether a server should accept an incoming
connection from a client. See section <A HREF="omniORBpy007.html#sec:serverRule">??</A> for
details.<BR>
<BR>
<TT>serverCallTimeOutPeriod</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>inConScanPeriod</TT> <I>default</I> =
<TT>180</TT><BR>
<BR>
<BR>
Idle timeout in seconds for incoming. If a connection has been idle
for this amount of time, the ORB closes it. See
section <A HREF="omniORBpy007.html#sec:connShutdown">7.553Idle connection shutdownsection.7.5</A>.<BR>
<BR>
<TT>threadPerConnectionPolicy</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>maxServerThreadPerConnection</TT> <I>default</I> =
<TT>100</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>maxServerThreadPoolSize</TT> <I>default</I> =
<TT>100</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>threadPerConnectionUpperLimit</TT> <I>default</I> =
<TT>10000</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>threadPerConnectionLowerLimit</TT> <I>default</I> =
<TT>9000</TT><BR>
<BR>
<BR>
If thread pooling was started because the number of connections hit
the upper limit, this parameter determines when thread per connection
should start again.<BR>
<BR>
<TT>threadPoolWatchConnection</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
If true, threads from the pool temporarily behave a bit like thread
per connection after dispatching a call. See
section <A HREF="omniORBpy007.html#sec:watchConn">7.4.252Thread pool modesubsection.7.4.2</A> for details.<BR>
<BR>
<TT>acceptBiDirectionalGIOP</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
Determines whether a server will ever accept clients' offers of
bidirectional GIOP connections. See section <A HREF="omniORBpy007.html#sec:bidir">7.856Bidirectional GIOPsection.7.8</A>.<BR>
<BR>
<TT>unixTransportDirectory</TT> <I>default</I> =
<TT>/tmp/omni-%u</TT><BR>
<BR>
<BR>
(Unix platforms only). Selects the location used to store Unix domain
sockets. The `<TT>%u</TT>' is expanded to the user name.<BR>
<BR>
<TT>unixTransportPermission</TT> <I>default</I> =
<TT>0777</TT><BR>
<BR>
<BR>
(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.<BR>
<BR>
<TT>supportCurrent</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
omniORB 4.0 supports the <TT>PortableServer::Current</TT> interface that
provides thread context information to a servant. 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.<BR>
<BR>
<TT>objectTableSize</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>poaHoldRequestTimeout</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>supportBootstrapAgent</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
If set true, servers support the Sun bootstrap agent protocol.<BR>
<BR>
<A NAME="toc18"></A>
<H2><A NAME="htoc49">4.6</A> GIOP and interoperability options</H2>
These options control omniORB's use of GIOP, and cover some areas
where omniORB can work around buggy behaviour by other ORBs.<BR>
<BR>
<TT>maxGIOPVerson</TT> <I>default</I> =
<TT>1.2</TT><BR>
<BR>
<BR>
Choose the maximum GIOP version the ORB should support. Valid values
are 1.0, 1.1 and 1.2.<BR>
<BR>
<TT>giopMaxMsgSize</TT> <I>default</I> =
<TT>2097152</TT><BR>
<BR>
<BR>
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 >= 8192.<BR>
<BR>
<TT>strictIIOP</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
If true, be strict about interpretation of the IIOP specification; if
false, permit some buggy behaviour to pass.<BR>
<BR>
<TT>lcdMode</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
If true, select `Lowest Common Denominator' mode. This disables
various IIOP and GIOP features that are known to cause problems with
some ORBs.<BR>
<BR>
<TT>tcAliasExpand</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
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.<BR>
<BR>
<TT>useTypeCodeIndirections</TT> <I>default</I> =
<TT>1</TT><BR>
<BR>
<BR>
TypeCode Indirections reduce the size of marshalled TypeCodes, and are
essential for recursive types, but some ORBs do not support them.
Setting this flag to false prevents the use of indirections (and,
therefore, recursive TypeCodes).<BR>
<BR>
<TT>acceptMisalignedTcIndirections</TT> <I>default</I> =
<TT>0</TT><BR>
<BR>
<BR>
If true, try to fix a mis-aligned indirection in a typecode. This is
used to work around a bug in some versions of Visibroker's Java ORB.<BR>
<BR>
<A NAME="toc19"></A>
<H2><A NAME="htoc50">4.7</A> System Exception Handlers</H2>
<A NAME="sec:exHandlers"></A>
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.<BR>
<BR>
omniORBpy 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.<BR>
<BR>
<H3><A NAME="htoc51">4.7.1</A> Minor codes</H3>
A new feature in omniORB 4.0 is extensive use of exception minor codes
to indicate the specific circumstances surrounding a system exception.
The C++ 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.<BR>
<BR>
Applications can use minor codes to adjust their behaviour according
to the condition. You can receive a string format of a minor code by
calling the <TT>omniORB.minorCodeToString()</TT> function, passing an
exception object as its argument.<BR>
<BR>
<H3><A NAME="htoc52">4.7.2</A> CORBA::TRANSIENT handlers</H3>
<TT>TRANSIENT</TT> exceptions can occur in many circumstances. One
circumstance is as follows:
<OL type=1><LI>The client invokes on an object reference.
<LI>The object replies with a <TT>LOCATION_FORWARD</TT> message.
<LI>The client caches the new location and retries to the new location.
<LI>Time passes...
<LI>The client tries to invoke on the object again, using the
cached, forwarded location.
<LI>The attempt to contact the object fails.
<LI>The ORB runtime resets the location cache and throws a
<TT>TRANSIENT</TT> exception with minor code
<TT>TRANSIENT_FailedOnForwarded</TT>.</OL>
In this situation, the default <TT>TRANSIENT</TT> exception handler
retries the call, using the object'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.<BR>
<BR>
In all other circumstances, the default <TT>TRANSIENT</TT> handler just
passes the exception on to the caller.<BR>
<BR>
You can override the default behaviour by installing your own
exception handler. The function to call has signature:
<PRE>
omniORB.installTransientExceptionHandler(cookie, function [, object])
</PRE>
The arguments are a cookie, which is any Python object, a call-back
function, and optionally an object reference. If the object reference
is present, the exception handler is installed for just that object;
otherwise the handler is installed for all objects with no handler of
their own.<BR>
<BR>
The call-back function must have the signature
<PRE>
function(cookie, retries, exc) -> boolean
</PRE>
When a <TT>TRANSIENT</TT> exception occurs, the function is called,
passing the cookie object, a count of how many times the operation has
been retried, and the TRANSIENT exception object itself. If the
function returns true, the operation is retried; if it returns false,
the TRANSIENT exception is raised in the application.<BR>
<BR>
<H3><A NAME="htoc53">4.7.3</A> CORBA.COMM_FAILURE and CORBA.SystemException</H3>
There are two other functions for registering exception handlers: one
for <TT>CORBA.COMM_FAILURE</TT>, and one for all other
exceptions. For both these cases, the default is for there to be no
handler, so exceptions are propagated to the application.
<PRE>
omniORB.installCommFailureExceptionHandler(cookie, function [, object])
omniORB.installSystemExceptionHandler(cookie, function [, object])
</PRE>
In both cases, the call-back function has the same signature
as for <TT>TRANSIENT</TT> handlers.<BR>
<BR>
<A NAME="toc20"></A>
<H2><A NAME="htoc54">4.8</A> Location forwarding</H2>
<A NAME="sec:locationForward"></A>
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.<BR>
<BR>
<A NAME="toc21"></A>
<H2><A NAME="htoc55">4.9</A> Dynamic importing of IDL</H2>
<A NAME="sec:importIDL"></A>
omniORBpy is usually used with pre-generated stubs. Since Python is a
dynamic language, however, it is possible to compile and import new
stubs at run-time.<BR>
<BR>
Dynamic importing is achieved with <TT>omniORB.importIDL()</TT> and
<TT>omniORB.importIDLString()</TT>. Their signatures are:
<PRE>
importIDL(filename [, args ]) -> tuple
importIDLString(string [, args ]) -> tuple
</PRE>
The first function compiles and imports the specified file; the second
takes a string containing the IDL definitions. The functions work by
forking omniidl and importing its output; they both take an optional
argument containing a list of strings which are used as arguments for
omniidl. For example, the following command runs omniidl with an
include path set:
<PRE>
m = omniORB.importIDL("test.idl", ["-I/my/include/path"])
</PRE>
Instead of specifying omniidl arguments on each import, you
can set the arguments to be used for all calls using the
<TT>omniORB.omniidlArguments()</TT> function.<BR>
<BR>
Both import functions return a tuple containing the names of the
Python modules which have been imported. The modules themselves can be
accessed through <TT>sys.modules</TT>. For example:
<PRE>
// test.idl
const string s = "Hello";
module M1 {
module M2 {
const long l = 42;
};
};
module M3 {
const short s = 5;
};
</PRE>
From Python:
<PRE>
>>> import sys, omniORB
>>> omniORB.importIDL("test.idl")
('M1', 'M1.M2', 'M3', '_GlobalIDL')
>>> sys.modules["M1.M2"].l
42
>>> sys.modules["M3"].s
5
>>> sys.modules["_GlobalIDL"].s
'Hello'
</PRE>
<A NAME="toc22"></A>
<H2><A NAME="htoc56">4.10</A> C++ API</H2>
omniORBpy has a C++ API that can be used by programs that embed Python
in C++, or by C++ extension modules to Python. The API has functions
to convert object references between their Python representation and
their C++ representation. For extensions to omniORBpy itself, it has a
mechanism for adding pseudo object types to omniORBpy.<BR>
<BR>
The definitions used by the C++ API are in the <TT>omniORBpy.h</TT>
header. An example of its use is in <TT>examples/embed/</TT>.<BR>
<BR>
The API is accessed through a singleton structure containing function
pointers. A pointer to the API struct is stored as a <TT>PyCObject</TT>
in the <TT>_omnipy</TT> module with the name <TT>API</TT>. It can be
accessed with code like:
<PRE>
PyObject* omnipy = PyImport_ImportModule((char*)"_omnipy");
PyObject* pyapi = PyObject_GetAttrString(omnipy, (char*)"API");
omniORBpyAPI* api = (omniORBpyAPI*)PyCObject_AsVoidPtr(pyapi);
Py_DECREF(pyapi);
</PRE>
The structure has this definition:
<PRE>
struct omniORBpyAPI {
PyObject* (*cxxObjRefToPyObjRef)(const CORBA::Object_ptr cxx_obj,
CORBA::Boolean hold_lock);
// Convert a C++ object reference to a Python object reference.
// If <hold_lock> is true, caller holds the Python interpreter lock.
CORBA::Object_ptr (*pyObjRefToCxxObjRef)(PyObject* py_obj,
CORBA::Boolean hold_lock);
// Convert a Python object reference to a C++ object reference.
// Raises BAD_PARAM if the Python object is not an object reference.
// If <hold_lock> is true, caller holds the Python interpreter lock.
</PRE>
<HR>
<A HREF="omniORBpy003.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="omniORBpy005.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
distrib
>
Mandriva
>
10.2
>
i586
>
media
>
contrib
>
by-pkgid
>
6e619d98ab27dc37261afe9e8317cae2
>
files
>
14
