CORBA API

CORBA Programming Reference

CORBA::ORB_init

Synopsis

Initializes operations for an ORB.

C++ Binding

static CORBA::ORB_ptr ORB_init(int& argc, char** argv,
                               const char* orb_identifier = 0);

Arguments

argc

The number of strings in argv.

argv

This argument is defined as an unbound array of strings (char **) and the number of strings in the array is passed in the argc parameter.

orb_identifier

If the orb_identifier parameter is supplied, "BEA_IIOP" explicitly specifies a remote client and "BEA_TOBJ" explicitly specifies a native client, as defined in the section Tobj_Bootstrap.

Description

This member function initializes operations for an ORB and returns a pointer to the ORB. When your program is done with the ORB, use the CORBA::release member function to free the resources allocated for the ORB pointer returned from CORBA::ORB_ptr ORB_init.

The ORB returned has been initialized with two pieces of information to determine how it will operate: client type (remote or native) and server port number. The client type can be specified in the orb_identifier argument, in the argv argument, or in the system registry. The server port number can be specified in the argv argument.

The arguments argc and argv are typically the same parameters that were passed to the main program. As specified by C++, these parameters contain string tokens from the command line that started the client. The two ORB options can be specified on the command line, each using a pair of tokens, as shown in examples below.

Client Type

The ORB_init function determines the client type of the ORB by the following steps.

If the orb_identifier argument is present, ORB_init determines the client type, either native or remote, if the string is "BEA_IIOP" or "BEA_TOBJ", respectively. If an orb_identifier string is present, all -ORBid parameters in the argv are ignored (removed).

If orb_identifier is not present or is explicitly zero, ORB_init looks at the entries in argc/argv. If argv contains an entry with "-ORBid", the next entry should be either "BEA_IIOP" or "BEA_TOBJ", again specifying remote or native. This pair of entries occurs if the command line contains either "-ORBid BEA_IIOP" or "-ORBid BEA_TOBJ".

If no client type is specified in argc/argv, ORB_init uses the default client type from the system registry (BEA_IIOP or BEA_TOBJ). The system registry was initialized at the time BEA Tuxedo was installed.

Server Port

In the case of a BEA Tuxedo remote joint client/server, in order to support IIOP, by definition, the object references created for the server part must contain a host and port. For transient object references, any port is sufficient and can be obtained by the ORB dynamically, but this is not sufficient for persistent object references. Persistent references must be served on the same port after the ORB restarts, that is, the ORB must be prepared to accept requests on the same port with which it created the object reference. Thus, there must be some way to configure the ORB to use a particular port.

Typically, a system administrator assigns the port number for the client from the "user" range of port numbers rather from the dynamic range. This keeps the joint client/servers from using conflicting ports.

To determine port number, ORB_init searches the argv parameter for the token "-ORBport" and a following numeric token. For example, if the client executable is named sherry, the command line might specify that the server port should be 937 as follows:

sherry -ORBport 937

ARGV Parameter Considerations

For C++, the order of consumption of argv parameters may be significant to an application. To ensure that applications are not required to handle argv parameters they do not recognize, the ORB initialization function must be called before the remainder of the parameters are consumed. Therefore, after the ORB_init call, the argv and argc parameters have been modified to remove the ORB understood arguments. It is important to note that the ORB_init function can only reorder or remove references to parameters from the argv list. This restriction is made to avoid potential memory management problems caused by trying to free parts of the argv list or extending the argv list of parameters. This is why argv is passed as a char** and not as a char**&.

Note: Use the CORBA::release member function to free the resources allocated for the pointer returned from CORBA::ORB_init.

Return Value

A pointer to a CORBA::ORB.

Exceptions

None.