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 initialization options

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

-ORBid ``omniORB2''

The identifier supplied must be ``omniORB2''.

-ORBtraceLevel <level>

This option is described in section 3.2.

-ORBstrictIIOP <1 or 0>

This option when set instructs the runtime to treat any incoming IIOP message as an error if it has a header message size that is larger than the actual body size. By default, this option is not set to allow omniORB2 to interoperate with some ill-behaved IIOP implementations.

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.

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

the above plus execution traces

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

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.

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.