Next: The Basic Object Up: No Title Previous: IDL to C++

# The omniORB2 API

In this chapter, we introduce the omniORB2 API. The purpose of this API is to provide access points to omniORB2 specific functionalities that are not covered by the CORBA specification. Obviously, if you use this API in your application, that part of your code is not going to be portable to run unchanged on other vendors' ORBs. To make it easier to identify omniORB2 dependent code, this API is defined under the name space ``omniORB''.

# ORB and BOA initialisation options

`CORBA::ORB_init` accepts the following command-line arguments:

`-ORBid ``omniORB2''`
  The identifier supplied must be ``omniORB2''.
`-ORBtraceLevel <level>`
  See section 4.2.
`-ORBserverName <string>`
  See section 4.3.
`-ORBtcAliasExpand <0 or 1>`
  See section 9.2.
`-ORBgiopMaxMsgSize <size in bytes>`
  See section 4.5.
`-ORBInitialHost <string>`
  See section 4.6.
`-ORBInitialPort <1-65535>`
  See section 4.6.
`-ORBdiiThrowsSysExceptions <0 or 1>`
  See section 11.4.
`-ORBinConScanPeriod <0-65535>`
  See section 7.3.
`-ORBoutConScanPeriod <0-65535>`
  See section 7.3.
`-ORBverifyObjectExistsAndType <0 or 1>`
  See section 4.7.
`-ORBlcdMode`
  See secion 4.7
`-ORBabortOnInternalError <0 or 1>`
  See section 4.8.

`BOA_init` accepts the following command-line arguments:

`-BOAid ``omniORB2_BOA''`
  The identifier supplied must be ``omniORB2_BOA''.
`-BOAiiop_port <port number>`
  This option tells the BOA which TCP/IP port to use to accept IIOP calls. If this option is not specified, the BOA will use an arbitrary port assigned by the operating system.
`-BOAno_bootstrap_agent`
  See section 4.6.
`-BOAiiop_name_port <hostname[:port number]>`
  This options tells the BOA the hostname and optionally the port number to use. See below for details.

By default, the BOA can work out the IP address of the host machine. This address is recorded in the object references of the local objects. However, when the host has multiple network interfaces and multiple IP addresses, it may be desirable for the application to control what address the BOA should use. This can be done by defining the environment variable `OMNIORB_USEHOSTNAME` to contain the preferred host name or IP address in dot-numeric form. Alternatively, the same can be acheived using the `-BOAiiop_name_port` option.

As defined in the CORBA specification, any command-line arguments understood by the ORB/BOA will be removed from `argv` when the initialisation functions return. Therefore, an application is not required to handle any command-line arguments it does not understand.

# Run-time Tracing and Diagnostic Messages

OmniORB2 uses the C++ iostream `cerr` to output any tracing and diagnostic messages. Some or all of these messages can be turned-on/off by setting the variable `omniORB::traceLevel`. The type definition of the variable is:

    CORBA::ULong omniORB::traceLevel = 1;  // The default value is 1

At the moment, the following trace levels are defined:

level 0
  turn off all tracing and informational messages
level 1
  informational messages only
level 2
  the above plus configuration information
level 5
  the above plus notifications when server threads are created or communication endpoints are shutdown
level 10-20
  the above plus execution traces
level 25
  the above plus hex dump of all data sent and received by the ORB via its network connections.

The variable can be changed by assignment inside your applications. It can also be changed by specifying the command-line option: `-ORBtraceLevel <level>`. For instance:

    $ eg2_impl -ORBtraceLevel 5

# Server Name

Applications can optionally specified a name to identify the server process. At the moment, this name is only used by the host-based access control module. See section 7.5 for details.

The name is stored in the variable `omniORB::serverName`.

    CORBA::String_var omniORB::serverName;

The variable can be changed by assignment inside your applications. It can also be changed by specifying the command-line option: `-ORBserverName <string>`.

# Object Keys

OmniORB2 uses a data type `omniORB::objectKey` to uniquely identify each object implementation. This is an opaque data type and can only be manipulated by the following functions:

    void omniORB::generateNewKey(omniORB::objectKey &k);

`omniORB::generateNewKey` returns a new `objectKey`. The return value is guaranteed to be unique among the keys generated during this program run. On the platforms that have a realtime clock and unique process identifiers, a stronger assertion can be made, i.e. the keys are guaranteed to be unique among all keys ever generated on the same machine.

    const unsigned int omniORB::hash_table_size;
    int omniORB::hash(omniORB::objectKey& k);

`omniORB::hash` returns the hash value of an `objectKey`. The value returned by this function is always between 0 and `omniORB:hash_table_size - 1` inclusively.

    omniORB::objectKey omniORB::nullkey();

`omniORB::nullkey` always returns the same `objectKey` value. This key is guaranteed to hash to 0.

    int operator==(const omniORB::objectKey &k1,const omniORB::objectKey &k2);
    int operator!=(const omniORB::objectKey &k1,const omniORB::objectKey &k2);

`ObjectKeys` can be tested for equality using the overloaded `operator==` and `operator!=`.

    omniORB::seqOctets*
    omniORB::keyToOctetSequence(const omniORB::objectKey &k1);

    omniORB::objectKey
    omniORB::octetSequenceToKey(const omniORB::seqOctets& seq);

`omniORB::keyToOctetSequence` takes an `objectKey` and returns its externalised representation in the form of a sequence of octets. The same sequence can be converted back to an `objectKey` using `omniORB::octetSequenceToKey`. If the supplied sequence is not an `objectKey`, `omniORB::octetSequenceToKey` raises a `CORBA::MARSHAL` exception.

# GIOP Message Size

omniORB2 sets a limit on the GIOP message size that can be sent or received. The value can be obtained by calling:

    size_t omniORB::MaxMessageSize();

and can be changed by:

    void omniORB::MaxMessageSize(size_t newvalue);

or by the command-line option `-ORBgiopMaxMsgSize`.

The exact value is somewhat arbitrary. The reason such a limit exists is to provide some way to protect the server side from resource exhaustion. Think about the case when the server receives a rogue GIOP(IIOP) request message that contains a sequence length field set to 2**31. With a reasonable message size limit, the server can reject this rogue message straight away.

# Initial Object Reference Bootstrapping

Starting from 2.6.0, a new mechanism is available for the ORB runtime to obtain the initial object references to CORBA services. Previously, it is necessary to write the IOR string of these services in the configuration file (section 1.2). Now the object references can be obtained from a bootstrap service. The bootstrap service is a special object with the object key 'INIT' and the following interface.:

         // IDL
         module CORBA {
            interface InitialReferences {
                Object get(in ORB::ObjectId id);
                // returns the initial object reference of the service
                // identified by <id>. For example the id for the COSS
                // Naming service is "NameService".

                ORB::ObjectIdList list();
                // returns the list of service id that this agent knows of
                // their initial object reference.
            };
         };

By default, all omniORB2 servers, i.e. those applications with the BOA initialised, contains an instance of this object and is able to responds to remote invocations. To prevent the ORB from instantiating this object, the command-line option `-BOAno_bootstrap_agent` should be specified.

In particular, the Naming Service omniNames is able to respond to a query through this interface and returns the object reference of its root context. In effect, the bootstrap agent provides a level of indirection. All omniORB2 clients still have to be supplied with the address of the bootstrap agent. However the information is much easier to specify than a stringified IOR! Another advantage of this approach is that it is completely compatiable with JavaIDL. This makes it possible for a client written in JavaIDL to share with a omniORB2 server the same Naming Service.

The address of the bootstrap agent is given by the `ORBInitialHost` and `ORBInitialPort` parameter in the omniORB configuration file (section 1.2). The parameters can also be specified as command-line options (section 4.1). `ORBInitialHost` is the host name and `ORBInitialPort` is the TCP/IP port number. The parameter `ORBInitialPort` is optional. If it is not specified, port number 900 will be used.

During initialisation, the ORB reads the parameters in the omniORB configuration file. If the parameter `NAMESERVICE` is specified, the stringified IOR would be used as the object reference of the root naming context. If the parameter is absent and the parameter `ORBInitialHost` is present, the ORB would contact the bootstrap agent at the address specified to obtain the root naming context when the application calls `resolve_initial_reference()`. If neither the `NAMESERVICE` nor `ORBInitialHost` is present, a call to `resolve_initial_reference()` returns a nil object. Finally, the command line argument `-ORBInitialHost` overrides any parameters in the configuration file. The ORB would always contact the bootstrap agent at the address specified to obtain the root naming context.

Now we are ready to describe a simple way to set up omniNames.

1. Start omniNames for the first time on a machine (e.g. wobble):

   `$ omniNames -start 1234`

2. Add to omniORB.cfg:

   `ORBInitialHost wobble`

   `ORBInitialPort 1234`

3. All omniORB2 applications will now be able to contact omniNames.

Alternatively, the command line options can be used, for example:

`$ eg3_impl -ORBInitialHost wobble -ORBInitialPort 1234 &`

`$ eg3_clt -ORBInitialHost wobble -ORBInitialPort 1234`

# GIOP Lowest Common Denominator Mode

Sometimes, to cope with bugs in another ORB, it is necessary to disable various GIOP and IIOP features in order to achieve interoperability. If the command line option `-ORBlcdMode` or the function `omniORB::enableLcdMode()` is called, the ORB enters the so-called ``lowest common denominator mode''. It bends over backwards to cope with bugs in the ORB at the other end. This is purely a transitional measure. The long term solution is to report the bugs to the other vendors and ask them to fix them expediently.

By default, omniORB2 uses GIOP LOCATE_REQUEST message to verify the existence of an object prior to the first invocation. If another vendor's ORB is known not to be able to handle this GIOP message, set the variable `omniORB::verifyObjectExistsAndType` to 0 would disable this feature, and hence achieve interoperability. The option can also be set via the command line option `-ORBverifyObjectExistsAndType`.

# Trapping omniORB2 Internal Errors

    class fatalException {
    public:
        const char *file() const;
        int line() const;
        const char *errmsg() const;
    };

When omniORB2 detects an internal inconsistency that is most likely to be caused by a bug in the runtime, it raises the exception `omniORB::fatalException`. When this exception is raised, it is not sensible to proceed with any operation that involves the ORB's runtime. It is best to exit the program immediately. The exception structure carries by `omniORB::fatalException` contains the exact location (the file name and the line number) where the exception is raised. You are strongly encourage to file a bug report and point out the location.

It may help to cause a core-dump and look at the stack trace to locate where the exception was thrown. This can be done by setting the variable `omniORB::abortOnInternalError` to 1. The variable can also be set via the command line option `-ORBabortOnInternalError`.

Next: The Basic Object Up: No Title Previous: IDL to C++