omniORB, and thus omniORBpy, 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.
When CORBA::ORB_init() is called, the value for each configuration parameter is searched for in the following order:
Command line arguments take the form ‘-ORBparameter’, and usually expect another argument. An example is ‘-ORBtraceLevel 10’.
Environment variables consist of the parameter name prefixed with ‘ORB’. Using bash, for example
The best way to understand the format of the configuration file is to look at the sample.cfg file in the omniORB distribution. Each parameter is set on a single line like
traceLevel = 10
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:
InitRef = NameService=corbaname::host1.example.com
= InterfaceRepository=corbaloc::host2.example.com:1234/IfR
On Windows, configuration parameters can be stored in the registry, under the key HKEY_LOCAL_MACHINE\SOFTWARE\omniORB.
The file sample.reg shows the settings that can be made. It can be edited and then imported into regedit.
The following options control debugging trace output.
traceLevel default = 1
omniORB can output tracing and diagnostic messages to the standard error stream. The following levels are defined:
| level 0 | critical errors only |
| level 1 | informational messages only |
| level 2 | configuration information and warnings |
| level 5 | notifications when server threads are created and communication endpoints are shutdown |
| level 10 | execution and exception traces |
| level 25 | trace each send or receive of a GIOP message |
| level 30 | dump up to 128 bytes of each GIOP message |
| level 40 | dump complete contents of each GIOP message |
The trace level is cumulative, so at level 40, all trace messages are output.
traceExceptions default = 0
If the traceExceptions 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.
traceInvocations default = 0
If the traceInvocations parameter is set true, all local and remote invocations are logged, in addition to any logging that may have been selected with traceLevel.
traceInvocationReturns default = 0
If the traceInvocationReturns parameter is set true, a log message is output as an operation invocation returns. In conjunction with traceInvocations and traceTime (described below), this provides a simple way of timing CORBA calls within your application.
traceThreadId default = 1
If traceThreadId is set true, all trace messages are prefixed with the id of the thread outputting the message. This can be handy for making sense of multi-threaded code, but it adds overhead to the logging so it can be disabled.
traceTime default = 1
If traceTime 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 can be turned off.
traceFile default =
omniORB’s tracing is normally sent to stderr. If traceFile it set, the specified file name is used for trace messages.
The tracing parameters can be inspected or modified at runtime with the following functions in the omniORB module:
Calling one of the functions with no arguments returns the current value; calling it with a single integer argument sets the value.
These options control miscellaneous features that affect the whole ORB runtime.
dumpConfiguration default = 0
If set true, the ORB dumps the values of all configuration parameters at start-up.
scanGranularity default = 5
As explained in chapter 6, 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.
nativeCharCodeSet default = ISO-8859-1
The native code set the application is using for char and string. See chapter 8.
nativeWCharCodeSet default = UTF-16
The native code set the application is using for wchar and wstring. See chapter 8.
defaultCharCodeSet default = none
The default code set used for char and string if the server does not specify it in its IORs. See chapter 8.
defaultWCharCodeSet default = none
The default code set used for wchar and wstring if the server does not specify it in its IORs. See chapter 8.
copyValuesInLocalCalls default = 1
Determines whether valuetype parameters in local calls are copied or not. See chapter 10.
abortOnInternalError default = 0
If this is set true, internal fatal errors will abort immediately, rather than throwing the omniORB::fatalException exception. This can be helpful for tracking down bugs, since it leaves the call stack intact.
abortOnNativeException default = 0
On Windows, ‘native’ exceptions such as segmentation faults and divide by zero appear as C++ exceptions that can be caught with catch (...). Setting this parameter to true causes such exceptions to abort the process instead.
maxSocketSend
maxSocketRecv
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.
The default values are platform specific. It is unlikely that you will need to change the values from the defaults.
The minimum valid limit is 1KB, 1024 bytes.
socketSendBuffer default = -1 or 16384
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.
On Windows, the default value of this parameter is 16384 bytes; on all other platforms the default is -1.
validateUTF8 default = 0
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.
These options control aspects of client-side behaviour.
InitRef default = none
Specify objects available from orb.resolve_initial_references(). The arguments take the form <key>=<uri>, where the key is the name given to resolve_initial_references() and uri is a valid CORBA object reference URI, as detailed in chapter 7.
DefaultInitRef default = none
Specify the default URI prefix for resolve_initial_references(), as explained in chapter 7.
clientTransportRule default = * unix,tcp,ssl
Used to specify the way the client contacts a server, depending on the server’s address. See section 6.7.1 for details.
clientCallTimeOutPeriod default = 0
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 TRANSIENT exception. A value of zero means no timeout; calls can block for ever. See section 6.3.1 for more information about timeouts.
Note: omniORB 3 had timeouts specified in seconds; omniORB 4.0 and later use milliseconds for timeouts.
clientConnectTimeOutPeriod default = 0
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 6.3.1 for more information about timeouts.
supportPerThreadTimeOut default = 0
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.
resetTimeOutOnRetries default = 0
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.
throwTransientOnTimeOut default = 0
omniORB 4.2 supports the CORBA::TIMEOUT exception that is part of the CORBA Messaging specification. By default, that is the exception thrown when timeouts occur. Previous omniORB releases did not have the CORBA::TIMEOUT exception, and instead used CORBA::TRANSIENT. If this parameter is set true, omniORB follows the old behaviour of throwing CORBA::TRANSIENT when a timeout occurs.
outConScanPeriod default = 120
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 6.5.
maxGIOPConnectionPerServer default = 5
The maximum number of concurrent connections the ORB will open to a single 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.
oneCallPerConnection default = 1
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 maxGIOPConnectionPerServer. 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 incoming calls on a single connection.
maxInterleavedCallsPerConnection default = 5
The maximum number of calls that can be interleaved on a connection. If more concurrent calls are made, they are queued.
offerBiDirectionalGIOP default = 0
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 6.8.
verifyObjectExistsAndType default = 1
By default, omniORB uses the GIOP LOCATE_REQUEST 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 _is_a() 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.
giopTargetAddressMode default = 0
GIOP 1.2 supports three addressing modes for contacting objects. This parameter selects the mode that omniORB uses. A value of 0 means GIOP::KeyAddr; 1 means GIOP::ProfileAddr; 2 means GIOP::ReferenceAddr.
immediateAddressSwitch default = 0
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.
resolveNamesForTransportRules default = 1
If true, names in IORs will be resolved when evaluating client transport rules, and remembered from then on; if false, names will not be resolved until connect time. Client transport rules based on IP address will therefore not match, but some platforms can use external knowledge to pick the best address to use if given a name to connect to.
retainAddressOrder default = 1
For IORs with multiple addresses, determines how the address to connect to is chosen. When first establishing a connection, the addresses are ordered according to the client transport rules (after resolving names if resolveNamesForTransportRules is true), and the addresses are tried in priority order until one connects successfully. For as long as there is at least one connection open to the address, new connections continue to use the same address.
After a failure, or after all open connections have been scavenged and closed, this parameter determines the address used to reconnect on the next call. If this parameter is true (the default), the address order and chosen address within the order is remembered; if false, a new connection attempt causes re-evaluation of the order (in case name resolutions change), and the highest priority address is tried first.
bootstrapAgentHostname default = none
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.
bootstrapAgentPort default = 900
The port number for the obsolete Sun bootstrap agent.
principal default = none
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.
These parameters affect server-side operations.
endPoint default = giop:tcp::
endPointNoListen
endPointPublish
endPointNoPublish
endPointPublishAllIFs
These options determine the end-points the ORB should listen on, and
the details that should be published in IORs. See
chapter 6 for details.
serverTransportRule default = * unix,tcp,ssl
Configure the rules about whether a server should accept an incoming connection from a client. See section 6.7.2 for details.
serverCallTimeOutPeriod default = 0
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.
inConScanPeriod default = 180
Idle timeout in seconds for incoming connections. If a connection has been idle for this amount of time, the ORB closes it. See section 6.5.
threadPerConnectionPolicy default = 1
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.
maxServerThreadPerConnection default = 100
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.
maxServerThreadPoolSize default = 100
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.
threadPerConnectionUpperLimit default = 10000
If the threadPerConnectionPolicy 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.
threadPerConnectionLowerLimit default = 9000
If thread pooling was started because the number of connections hit the upper limit, this parameter determines when thread per connection should start again.
threadPoolWatchConnection default = 1
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 less than or equal to 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. See section 6.4.2.
connectionWatchPeriod default = 50000
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.
connectionWatchImmediate default = 0
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 connectionWatchPeriod 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.
Note that this setting has no effect on Windows, since it has no mechanism for signalling the connection watching thread.
acceptBiDirectionalGIOP default = 0
Determines whether a server will ever accept clients’ offers of bidirectional GIOP connections. See section 6.8.
unixTransportDirectory default = /tmp/omni-%u
(Unix platforms only). Selects the location used to store Unix domain sockets. The ‘%u’ is expanded to the user name.
unixTransportPermission default = 0777
(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.
supportCurrent default = 1
omniORB supports the PortableServer::Current 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.
objectTableSize default = 0
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.
poaHoldRequestTimeout default = 0
If a POA is put in the HOLDING state, calls to it will be timed out after the specified number of milliseconds, by raising a CORBA.TIMEOUT exception. Zero means no timeout.
poaUniquePersistentSystemIds default = 1
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.
idleThreadTimeout default = 10
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.
supportBootstrapAgent default = 0
If set true, servers support the Sun bootstrap agent protocol.
These options control omniORB’s use of GIOP, and cover some areas where omniORB can work around buggy behaviour by other ORBs.
maxGIOPVersion default = 1.2
Choose the maximum GIOP version the ORB should support. Valid values are 1.0, 1.1 and 1.2.
giopMaxMsgSize default = 2097152
The largest message, in bytes, that the ORB will send or receive, to avoid resource starvation. If the limit is exceeded, a MARSHAL exception is thrown. The size must be >= 8192.
strictIIOP default = 1
If true, be strict about interpretation of the IIOP specification; if false, permit some buggy behaviour to pass.
lcdMode default = 0
If true, select ‘Lowest Common Denominator’ mode. This disables various IIOP and GIOP features that are known to cause problems with some ORBs.
tcAliasExpand default = 0
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. There is a performance penalty when inserting into an Any if tcAliasExpand is set to 1.
useTypeCodeIndirections default = 1
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, prevents the use of recursive TypeCodes).
acceptMisalignedTcIndirections default = 0
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’s Java ORB.
By default, all system exceptions that are raised during an operation invocation, with the exception of some cases of CORBA.TRANSIENT, 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 CORBA.COMM_FAILURE 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.
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 CORBA.TRANSIENT, CORBA.COMM_FAILURE and CORBA.SystemException. 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.
omniORB makes extensive use of exception minor codes to indicate the specific circumstances surrounding a system exception. The C++ file include/omniORB4/minorCode.h contains definitions of all the minor codes used in omniORB, covering codes allocated in the CORBA specification, and ones specific to omniORB.
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 omniORB.minorCodeToString() function, passing an exception object as its argument.
TRANSIENT exceptions can occur in many circumstances. One circumstance is as follows:
In this situation, the default TRANSIENT exception handler retries the call, using the object’s original location. If the retry results in another LOCATION_FORWARD, to the same or a different location, and that forwarded location fails immediately, the TRANSIENT exception will occur again, and the pattern will repeat. With repeated exceptions, the handler starts adding delays before retries, with exponential back-off.
In all other circumstances, the default TRANSIENT handler just passes the exception on to the caller.
You can override the default behaviour by installing your own exception handler. The function to call has signature:
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.
The call-back function must have the signature
When a TRANSIENT exception occurs, the callback 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 original exception is raised in the application. In the case of a TRANSIENT exception due to a failed location forward, the exception propagated to the application is the original exception that caused the TRANSIENT (e.g. a COMM_FAILURE or OBJECT_NOT_EXIST), rather than the TRANSIENT exception1.
When a call timeout occurs, by default the ORB raises CORBA.TIMEOUT. 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 in the same manner as for TRANSIENT exceptions:
The call-back function has the same signature as for TRANSIENT handlers. There is no default handler, do TIMEOUT exceptions are propagated to application code by default.
omniORB version 4.1 and earlier did not have the CORBA.TIMEOUT exception, and threw CORBA.TRANSIENT instead. If the throwTransientOnTimeOut configuration parameter is set to 1, omniORB 4.2 reverts to this behaviour, and calls the transient exception handler instead of the timeout exception handler.
The timeout exception handler is used when a CORBA call times out. It is not called when an AMI poller operation throws CORBA.TIMEOUT. In that situation, the exception is always propagated to the caller.
There are two other functions for registering exception handlers: one for CORBA.COMM_FAILURE, 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.
If the ORB has successfully contacted a server at some point, and access to it subsequently fails (and the condition for TRANSIENT described above does not occur), the ORB raises a CORBA.COMM_FAILURE exception.
In both cases, the call-back function has the same signature as for TRANSIENT handlers.
Any CORBA operation invocation can return a LOCATION_FORWARD message to the caller, indicating that it should retry the invocation on a new object reference. The standard allows ServantManagers to trigger LOCATION_FORWARDs by raising the PortableServer.ForwardRequest exception, but it does not provide a similar mechanism for normal servants. omniORB provides the omniORB.LOCATION_FORWARD exception for this purpose. It can be thrown by any operation implementation.
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.
Dynamic importing is achieved with omniORB.importIDL() and omniORB.importIDLString(). Their signatures are:
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 output2; 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:
Instead of specifying omniidl arguments on each import, you can set the arguments to be used for all calls using the omniORB.omniidlArguments() function.
Both import functions return a tuple containing the names of the Python modules that have been imported. The modules themselves can be accessed through sys.modules. For example:
From Python:
Note that each time importIDL() or importIDLString() is called, the IDL definitions are compiled and imported into the associated Python declarations. The new declarations overwrite any old ones with the same names. This can cause confusing situations where different modules see different definitions of the same objects. Although the objects appear identical, they are not, and comparisons within applications and within omniORBpy unexpectedly fail. You should not use these functions in more than one module to import the same IDL files.
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.
The definitions used by the C++ API are in the omniORBpy.h header. An example of its use is in examples/embed/.
The API is accessed through a singleton structure containing function pointers. In Python 3.x, a pointer to the API struct is stored in a PyCapsule named _omnipy.API. Access it with code like:
In Python 2.x, a pointer to the API struct is stored as a PyCObject in the _omnipy module with the name API. It can be accessed with code like:
See the structure definition in omniORBpy.h for details of the available functions.