# Chapter 4 omniORB configuration and API

omniORB 4.0 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 `CORBA::ORB_init()`. A few parameters can be configured at run time. This chapter lists all the configuration parameters, and how they are used.

## 4.1 Setting parameters

When `CORBA::ORB_init()` is called, the value for each configuration parameter is searched for in the following order:

1. Command line arguments
2. `ORB_init()` options
3. Environment variables
4. Configuration file / Windows registry
5. Built-in defaults

### 4.1.1 Command line arguments

Command line arguments take the form ``-ORB` parameter', and usually expect another argument. An example is ``-ORBtraceLevel 10`'.

### 4.1.2 ORB_init() parameter

`ORB_init()`'s extra argument accepts an array of two-dimensional arrays of strings, like this:

    const char* options[][2] = { { "traceLevel", "1" }, { 0, 0 } };
    orb = CORBA::ORB_init(argc,argv,"omniORB4",options);

### 4.1.3 Environment variables

Environment variables consist of the parameter name prefixed with ``ORB`'. Using bash, for example

    export ORBtraceLevel=10

### 4.1.4 Configuration file

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

  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 `ORB_init()` do not use a prefix.

### 4.1.5 Windows registry

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.

## 4.2 Tracing options

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`.
`traceThreadId` default = `0`
If `traceThreadId` 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.

### 4.2.1 Tracing API

The four tracing parameters can be modified at runtime by assigning to the following variables

    namespace omniORB {
      CORBA::ULong   traceLevel;
      CORBA::Boolean traceExceptions;
      CORBA::Boolean traceInvocations;
      CORBA::Boolean traceThreadId;
    };

Log messages can be sent somewhere other than stderr by registering a logging function which is called with the text of each log message:

    namespace omniORB {
      typedef void (*logFunction)(const char*);
      void setLogFunction(logFunction f);
    };

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.

## 4.3 Miscellaneous global options

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 873Connection and Thread Managementchapter.8, 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 983Code set conversionchapter.9.
`nativeWCharCodeSet` default = `UTF-16`
The native code set the application is using for `wchar` and `wstring`. See chapter 983Code set conversionchapter.9.
`omniORB_27_CompatibleAnyExtraction` default = `0`
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.
`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.

## 4.4 Client side options

These options control aspects of client-side behaviour.
`InitRef` default = `none`
Specify the 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 663Interoperable Naming Servicechapter.6.
`DefaultInitRef` default = `none`
Specify the default URI prefix for `resolve_initial_references()`, as explained in chapter 663Interoperable Naming Servicechapter.6.
`clientTransportRule` default = `* unix,tcp,ssl`
Used to specify the way the client contacts a server, depending on the server's address. See section 8.7.179Client transport rulessubsection.8.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 and raises a `TRANSIENT` exception. A value of zero means no timeout; calls can block for ever. See section 8.3.175Client side timeoutssubsection.8.3.1 for more information about timeouts.
Note: omniORB 3 had timeouts specified in seconds; omniORB 4.0 uses milliseconds for 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.
`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 8.577Idle connection shutdownsection.8.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 calls on a single connection.
`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 8.881Bidirectional GIOPsection.8.8.
`diiThrowsSysExceptions` default = `0`
If this is true, DII functions throw system exceptions; if it is false, system exceptions that occur are passed through the `Environment` object.
`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`.
`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.

## 4.5 Server side options

These parameters affect server-side operations.
`endPoint` default = `giop:tcp::`
`endPointNoListen`
`endPointNoPublish`
`endPointPublishAllIFs`
These options determine the end-points the ORB should listen on, and the details that should be published in IORs. See chapter 873Connection and Thread Managementchapter.8 for details.
`serverTransportRule` default = `* unix,tcp,ssl`
Configure the rules about whether a server should accept an incoming connection from a client. See section ?? 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. If a connection has been idle for this amount of time, the ORB closes it. See section 8.577Idle connection shutdownsection.8.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`
If true, threads from the pool temporarily behave a bit like thread per connection after dispatching a call. See section 8.4.276Thread pool modesubsection.8.4.2 for details.
`acceptBiDirectionalGIOP` default = `0`
Determines whether a server will ever accept clients' offers of bidirectional GIOP connections. See section 8.881Bidirectional GIOPsection.8.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 4.0 supports the `PortableServer::Current` 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.
`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 `TRANSIENT` exception. Zero means no timeout.
`supportBootstrapAgent` default = `0`
If set true, servers support the Sun bootstrap agent protocol.

### 4.5.1 Main thread selection

There is one server-side parameter that must be set with an API function, rather than a normal configuration parameter:

    namespace omniORB {
      void setMainThread();
    };

POAs with the `MAIN_THREAD` policy dispatch calls on the `main' thread. By default, omniORB assumes that the thread that initialised the omnithread library is the `main' thread. To choose a different thread, call this function from the desired `main' thread. The calling thread must have an `omni_thread` associated with it (i.e. it must have been created by omnithread, or `omni_thread::create_dummy()` must have been called). If it does not, the function throws `CORBA::INITIALIZE`.
Note that calls are only actually dispatched to the `main' thread if `ORB::run()` or `ORB::perform_work()` is called from that thread.

## 4.6 GIOP and interoperability options

These options control omniORB's use of GIOP, and cover some areas where omniORB can work around buggy behaviour by other ORBs.
`maxGIOPVerson` 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. 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 `tcAliasExpand` is set to 1. 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 ORBs do not support them. Setting this flag to false prevents the use of indirections (and, therefore, 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 versions of Visibroker's Java ORB.

## 4.7 System Exception Handlers

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.
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 `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.

### 4.7.1 Minor codes

A new feature in omniORB 4.0 is extensive use of exception minor codes to indicate the specific circumstances surrounding a system exception. The 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. In compilers with namespace support, the minor code constants appear in namespace `omni`; otherwise they are in the global scope.
Applications can use minor codes to adjust their behaviour according to the condition, e.g.

    try {
      ...
    }
    catch (CORBA::TRANSIENT& ex) {
      if (ex.minor() == omni::TRANSIENT_ConnectFailed) {
        // retry with a different object reference...
      }
      else {
        // print an error message...
      }
    }

### 4.7.2 CORBA::TRANSIENT handlers

`TRANSIENT` exceptions can occur in many circumstances. One circumstance is as follows:

1. The client invokes on an object reference.
2. The object replies with a `LOCATION_FORWARD` message.
3. The client caches the new location and retries to the new location.
4. Time passes...
5. The client tries to invoke on the object again, using the cached, forwarded location.
6. The attempt to contact the object fails.
7. The ORB runtime resets the location cache and throws a `TRANSIENT` exception with minor code `TRANSIENT_FailedOnForwarded`.

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.
Applications can override the default behaviour by installing their own exception handler. The API to do so is summarised below:

    namespace omniORB {

      typedef CORBA::Boolean (*transientExceptionHandler_t)(void* cookie,
                                                      CORBA::ULong n_retries,
                                                      const CORBA::TRANSIENT& ex);

      void installTransientExceptionHandler(void* cookie,
                                            transientExceptionHandler_t fn);

      void installTransientExceptionHandler(CORBA::Object_ptr obj,
                                            void* cookie,
                                            transientExceptionHandler_t fn);
    }

The overloaded function `installTransientExceptionHandler()` can be used to install the exception handlers for `CORBA::TRANSIENT`. 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 `cookie` is an opaque pointer which will be passed on by the ORB when it calls the exception handler.
An exception handler will be called by proxy objects with three arguments. The `cookie` is the opaque pointer registered by `installTransientExceptionHandler()`. The argument `n_retries` is the number of times the proxy has called this handler for the same invocation. The argument `ex` is the value of the exception caught. The exception handler is expected to do whatever is appropriate and returns a boolean value. If the return value is TRUE(1), the proxy object retries the operation. If the return value is FALSE(0), the `CORBA::TRANSIENT` exception is propagated into the application code.
The following sample code installs a simple exception handler for all objects and for a specific object:

    CORBA::Boolean my_transient_handler1 (void* cookie,
                                          CORBA::ULong retries,
                                          const CORBA::TRANSIENT& ex)
    {
       cerr << "transient handler 1 called." << endl;
       return 1;           // retry immediately.
    }

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

    static Echo_ptr myobj;

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

       omniORB::installTransientExceptionHandler(myobj,0,my_transient_handler2);
       // The proxy object of myobj will call my_transient_handler2 from now on.
    }

### 4.7.3 CORBA::COMM_FAILURE

If the ORB has successfully contacted an object 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.
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:

    class omniORB {
    public:

    typedef CORBA::Boolean (*commFailureExceptionHandler_t)(void* cookie,
                                                    CORBA::ULong n_retries,
                                                    const CORBA::COMM_FAILURE& ex);

    static void installCommFailureExceptionHandler(void* cookie,
                                                 commFailureExceptionHandler_t fn);

    static void installCommFailureExceptionHandler(CORBA::Object_ptr obj,
                                                 void* cookie,
                                                 commFailureExceptionHandler_t
                                                 fn);
    }

The functions are equivalent to their counterparts for `CORBA::TRANSIENT`.

### 4.7.4 CORBA::SystemException

If a system exception other than `CORBA::TRANISENT` or `CORBA::COMM_FAILURE` 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:

    class omniORB {
    public:

    typedef CORBA::Boolean (*systemExceptionHandler_t)(void* cookie,
                                                CORBA::ULong n_retries,
                                                const CORBA::SystemException& ex);

    static void installSystemExceptionHandler(void* cookie,
                                              systemExceptionHandler_t fn);

    static void installSystemExceptionHandler(CORBA::Object_ptr obj,
                                              void* cookie,
                                              systemExceptionHandler_t fn);
    }

The functions are equivalent to their counterparts for `CORBA::TRANSIENT`.

## 4.8 Location forwarding

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_FORWARD`s 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.

    namespace omniORB {
      class LOCATION_FORWARD {
      public:
        LOCATION_FORWARD(CORBA::Object_ptr objref);
      };
    };

The exception object consumes the object reference it is passed.