Chapter 3
OrbixWeb Configuration

3.1 The OrbixWeb Configuration File

3.1.1 Configuration File Entries

3.1.2 Format of Orbix.cfg

3.1.3 Error Messages for System Exceptions

3.1.4 Location of the Implementation Repository Store

3.1.5 Location of the Interface Repository Store

3.1.6 OrbixWeb Daemon Port

3.1.7 OrbixWeb Daemon IIOP Port

3.1.8 Server Ports

3.1.9 The Name of the Local Internet Domain

3.1.10 Retry Attempts

3.1.11 Unregistered Persistent Servers

3.2 Class Configure

3.2.1 Communications Protocol for Binding

3.2.2 Buffer Size for Parameter Marshalling

3.2.3 Server's Well-known Port for IIOP

3.2.4 Management of Server's Well-known Port for IIOP

3.2.5 Name of the Local Internet Domain

3.2.6 Naming Service Host Name

3.2.7 Object Table Size

3.2.8 Orbix Object Instantiation

3.2.9 OrbixWeb Daemon Port

3.2.10 OrbixWeb Daemon IIOP Port

3.2.11 Configure.java: Source Code

3.3 The Daemon Switches

3.4 Configuring the Locator

3.4.1 Configuring the Locator by Editing the Configuration Files

3.4.2 Configuring the Locator Using Utility Commands

3.4.3 Configuring the Locator Using IDL Operations

• The OrbixWeb configuration file Orbix.cfg. This file contains a set of variable values which configure the operation of the OrbixWeb daemon process and, to a lesser extent, the IDL compiler.
  
• The OrbixWeb Java class Configure. This class is used in the configuration of OrbixWeb applications during initial compilation.
  
• The command-line switches to the OrbixWeb daemon.
  
• How to configure the OrbixWeb default locator's mapping from server names to host names.
  

By default, the OrbixWeb configuration file is installed in the OrbixWeb installation directory. In order to allow the OrbixWeb daemon and the IDL compiler to locate this file, the IT_CONFIG_PATH environment variable should be set.

If the IT_CONFIG_PATH variable value is a directory, the directory should contain the file named Orbix.cfg. If the IT_CONFIG_PATH environment variable is the full pathname of a file, that file will be used as the configuration file.

Note that on Windows NT, IT_CONFIG_PATH must be a system, rather than a user environment variable. On UNIX, if Orbix.cfg is installed in the /etc directory, it will be automatically located and no IT_CONFIG_PATH setting is required.

3.1.1 Configuration File Entries

The following variables may be set in the Orbix.cfg file.

The individual entries are explained in more detail in subsequent subsections.

3.1.2 Format of Orbix.cfg

 <entry name>   <entry value>

 orbixd -v

3.1.3 Error Messages for System Exceptions

 <error number>: <error message text>

This standard file can be edited for a particular installation if required; for example by translating all of the text into French or German, or by providing more verbose explanations of errors than those provided in the standard OrbixWeb daemon release.

Rather than changing the master file distributed with OrbixWeb, an alternative file can be specified using the IT_ERRORS entry in the OrbixWeb configuration file, or on a per user basis by setting the value of the IT_ERRORS environment variable to a file which contains the list of system error messages. If the IT_ERRORS environment variable is not defined, then the OrbixWeb daemon will output the error messages in the file named by the IT_ERRORS entry in the system configuration file.

Within the IT_ERRORS file, comments can be inserted using "//", and `\' can be used as a continuation character if the message needs to extend past the end of line.

Note that the IT_ERRORS file is only referenced by the OrbixWeb daemon process. Alterations to this file will not affect the error messages displayed by the IDL compiler, or the contents of OrbixWeb system exception descriptions.

To alter the content of these error messages, the programmer should edit or replace the OrbixWeb class ErrorMsgs, the source code of which is supplied with each OrbixWeb installation. The format of error messages defined in this class is similar to that in the OrbixWeb error messages file, where each error is an element of a Java switch statement, contained in the static method lookup_message() as follows:

 // Java
 // In file ErrorMsgs.java.
 
 package IE.Iona.Orbix2.CORBA;
 
 public class ErrorMsgs {
 	...
 
 	static String lookup_message (int minor_code) {
 		switch (minor_code) {
 			case <error number>: 
 				return <error message text>;
 		}
 
 		return null;
 	}
 }

Occasionally it might be useful for a group of programmers to have their own Implementation Repository store (this might be done when running a separate daemon with a different daemon port). Programmers can specify a different location by setting the IT_CONFIG_PATH to refer to a configuration file that specifies a different location for the IT_IMP_REP_PATH entry or by setting the IT_IMP_REP_PATH environment variable.

3.1.5 Location of the Interface Repository Store

For further details of the Interface Repository, see Chapter 20, "Interface Repository" of the OrbixWeb Programming Guide.

3.1.6 OrbixWeb Daemon Port

The daemon waits for incoming connections that use the Orbix protocol on an internet port, and by default this port number is given by the IT_DAEMON_PORT entry in the OrbixWeb configuration file, Orbix.cfg. On UNIX, if there is an entry for orbixd in the /etc/services system configuration file, then this entry is used in preference to the one in Orbix.cfg.

On occasion, when experimenting with the system, a group of programmers may wish to install further daemons on a specific machine to keep their work separate from other applications. These programmers must specify a different port for this daemon, by setting the environment variable IT_DAEMON_PORT or by using a different system configuration file Orbix.cfg (as given by the IT_CONFIG_PATH environment variable).

The order of searching for the port numbers is:

• The environment variable IT_DAEMON_PORT.
  
• On UNIX, the orbixd entry in /etc/services.
  
• The IT_DAEMON_PORT entry in the OrbixWeb configuration file.
  

If using the Orbix protocol, it is important that OrbixWeb client programmers correctly configure the port number on which the client attempts to contact an OrbixWeb daemon process, as described in section 3.2.9.

3.1.7 OrbixWeb Daemon IIOP Port

If a client is configured to use IIOP as its default communications protocol and then attempts to bind to a server object, it is important that the client's daemon IIOP port number is set to the daemon's IIOP port. Details of client configuration values are given in section 3.2.10.

3.1.8 Server Ports

The first server port assigned is IT_DAEMON_SERVER_BASE plus 1; and the last assigned is IT_DAEMON_SERVER_BASE plus IT_DAEMON_SERVER_RANGE. That is, the range is:

IT_DAEMON_SERVER_BASE + 1 to

IT_DAEMON_SERVER_BASE + IT_DAEMON_SERVER_RANGE

If no free port is found, an IMP_LIMIT system exception is raised to the client application attempting an invocation to the (new) server.

IT_DAEMON_SERVER_BASE and IT_DAEMON_SERVER_RANGE can be set using their entries in the system configuration file, or by setting the corresponding environment variables. IT_DAEMON_SERVER_BASE must be set; IT_DAEMON_SERVER_RANGE has a default value if not set.

3.1.9 The Name of the Local Internet Domain

An example is:

 IT_LOCAL_DOMAIN iona.com

3.1.10 Retry Attempts

The IT_CONNECT_ATTEMPTS configuration entry may be used to control the maximum number of retries. Note that the maximum number of retries may also be set by calling the method maxConnectRetries() on the _CORBA.Orbix object.

The order for determining the number of retries is:

• The value set by maxConnectRetries(). The IT_CONNECT_ATTEMPTS value will only be used if this is set to 0.
  
• The environment variable IT_CONNECT_ATTEMPTS.
  
• The IT_CONNECT_ATTEMPTS entry in the OrbixWeb configuration file.
  

3.1.11 Unregistered Persistent Servers

The daemon will allow clients to invoke on the persistent server while it is available. Note, however, that no access control is enforced and there is no record of the server in the Implementation Repository.

The OrbixWeb daemon would normally obtain information on which communications protocol and data encoder should be used from the Implementation Repository entry for the server. An alternative means of finding this information must be provided when a server is unregistered.

The default low-level communications protocol is given by the IT_DEFAULT_COMMS entry in the system configuration file.

The default data encoder is given by the IT_DEFAULT_CODE entry.

The order of searching for communications and encoding information for a persistent server is thus:

1. The Implementation Repository.

2. The environment variables IT_DEFAULT_COMMS and IT_DEFAULT_CODE.


3. The IT_DEFAULT_COMMS and IT_DEFAULT_CODE entries in the OrbixWeb configuration file.

3.2.1 Communications Protocol for Binding

3.2.2 Buffer Size for Parameter Marshalling

If data greater than the buffer size is sent to an operation parameter, overheads of buffer reallocation and copying will be incurred. Therefore, programmers who know in advance an approximate upper limit on the size of operation parameters may wish to resize the buffer in order to reduce these overheads.

The default buffer size is 8192

3.2.3 Server's Well-known Port for IIOP

This value has no effect if _CORBA.IT_IIOP_USE_LOCATOR is set to true.

The significance of this setting is discussed in detail in Chapter 9, "ORB Interoperability" of the OrbixWeb Programming Guide.

3.2.4 Management of Server's Well-known Port for IIOP

See Chapter 9, "ORB Interoperability" of the OrbixWeb Programming Guide for further details.

3.2.5 Name of the Local Internet Domain

3.2.6 Naming Service Host Name

3.2.7 Object Table Size

The variable _CORBA.IT_OBJECT_TABLE_SIZE allows the size of the object table to be configured for each application. The default size is 100.

Programmers who wish to resize the object table during execution of an application can do so by invoking the method reSizeObjectTable() (defined in class ORB) on the _CORBA.Orbix object.

3.2.8 Orbix Object Instantiation

Type BOA extends type ORB, and introduces functionality necessary for the implementation of OrbixWeb servers. However, client programmers are free to instantiate the _CORBA.Orbix object as either type. This is an advantage, as type ORB requires the dynamic loading of a significantly reduced set of Java classes.

By default, the _CORBA.Orbix object is instantiated as type BOA. The syntax of this instantiation is illustrated in section 3.2.11.

3.2.9 OrbixWeb Daemon Port

The variable _CORBA.IT_ORBIXD_PORT in class Configure allows an OrbixWeb programmer to configure the OrbixWeb daemon port value for each application. If this port value does not match the IT_DAEMON_PORT value specified in the daemon configuration file, Orbix protocol invocations which involve communications with the daemon process will raise a COMM_FAILURE system exception.

Alternative approaches to configuring the OrbixWeb daemon port in an OrbixWeb application are illustrated in Chapter 16, "Configuring OrbixWeb through its API" of the OrbixWeb Programming Guide.

The default Orbix protocol port is 1570, which is the standard registered port number assigned to orbixd.

3.2.10 OrbixWeb Daemon IIOP Port

The variable _CORBA.IT_ORBIXD_IIOP_PORT in class Configure allows an OrbixWeb programmer to configure the OrbixWeb daemon IIOP port value for each application. If this port value does not match the IT_DAEMON_IIOP_PORT value specified in the daemon configuration file, IIOP invocations which involve communications with the daemon process will raise a COMM_FAILURE system exception.

Alternative approaches to configuring the OrbixWeb daemon port in an OrbixWeb application are illustrated in Chapter 16, "Configuring OrbixWeb through its API" of the OrbixWeb Programming Guide.

The default daemon IIOP port is 1571.

3.2.11 Configure.java: Source Code

 // Configure Class
 // In file Configure.java.
 
 package IE.Iona.Orbix2;
 
 public class Configure {
 	private Configure() {}
 
 	static public void loadStatics () {
 		// Communications protocol for use 
 		// in binding.
 		_CORBA.IT_BIND_USING_IIOP = true;
 
 		// Initial allocation size for marshalling 
 		// buffers.
 		_CORBA.IT_BUFFER_SIZE = 8192;
 
 		// Server listen port for IIOP protocol.
 		_CORBA.IT_IIOP_LISTEN_PORT = 0;
 
 		// Local internet domain name.
 		_CORBA.IT_LOCAL_DOMAIN = "...";
 
 		// Naming Service host name.
 		_CORBA.IT_NS_HOSTNAME = 
 			_CORBA.Orbix.myHost ();
 
 		// Internal object table size.
 		_CORBA.IT_OBJECT_TABLE_SIZE = 100;
 
 		// Orbix object instantiation -
 		// programmers need not be aware of
 		// constructor parameter values.
 		_CORBA.Orbix = new IE.Iona.Orbix2.BOA
 			(acceptConnections, iiopListenPort);
 		// The alternative instantiation:
 		// _CORBA.Orbix = new IE.Iona.Orbix2.ORB ();
 
 		// Default port when communicating with 
 		// orbixd using Orbix protocol.
 		_CORBA.IT_ORBIXD_PORT = 1570;
 
 
 		// Default port when communicating with 
 		// orbixd using IIOP.
 		_CORBA.IT_ORBIXD_IIOP_PORT = 1571;
 	};
 }

In order to update any of the variables described above, this class definition can simply be edited appropriately. The resulting Java source code should be compiled and the resulting bytecode output (IE/Iona/Orbix2/Configure.class) made available to the client at runtime, in preference to the default class.

If several clients wish to load different versions of class Configure at runtime, then programmers should be careful to ensure that each client locates the required version, for example by using different CLASSPATH environment settings for each. If only a single version of class Configure is required for all clients, then the programmer may chose to overwrite the default Configure.class file in the OrbixWeb classes directory.

3.3 The Daemon Switches

3.4 Configuring the Locator

The default locator uses specific location files to search for a particular server. These files are:

The directory containing the files Orbix.hosts and Orbix.hostgroups is searched for in the following order:

1. Using the environment variable IT_LOCATOR_PATH.


2. The IT_LOCATOR_PATH entry in the OrbixWeb configuration file.


3. On UNIX, the /etc directory; that is /etc/Orbix.hosts and
/etc/Orbix.hostgroups.

Note that when the locator is automatically called by _bind(), OrbixWeb iterates through the returned list of hosts trying each in turn to find a host which is currently available to run the server. The locator functionality is described in detail in Chapter 24, "Locators" of the OrbixWeb Programming Guide.

Using OrbixWeb, the two configuration files can be maintained by simply editing them as normal files.

3.4.1 Configuring the Locator by Editing the Configuration Files

Each line of this file contains the fields:

 <server name>:<list hosts>:<list host groups>

Only one entry is allowed in this file for any given server name.

Example entries are:

 bank:alpha,beta,gamma:
 spreadsheet:alpha,beta:financial
 mail::all

One possible use of this is to have the IT_daemon entries for a set of machines arranged in a circle–so that all of the machines will be searched. For example, the entry for this on host alpha could be:

 IT_daemon:beta:

 IT_daemon:alpha:

Hosts can be gathered into groups to ease their management: in particular, group names can be specified as the last field of an entry in the locator's table. Groups are defined in the hostgroups definition file (see Table 3.2).

Each line of this file must have the format

 <group name>:<list hosts>:

An example file is:

 financial:gamma,delta:
 all:alpha,beta,gamma,delta:

serverhosts

• List the hosts that support a specified server.
  
• Modify that list by adding or deleting hosts.
  

 serverhosts servername [-h <hostname>] [-v]
 	[-r <hostlist>]  [-a <hostlist>] [-l]

The options are as follows:

The -h switch is used to specify the host of the OrbixWeb daemon to send the request to; it defaults to the local host.

If more than one of the switches -r, -a and -l is specified, they are executed in the order

-r -a -l

• List the host groups that support a specified server.
  
• Modify that list by adding or deleting groups.
  

 servergroups servername [-h <hostname>] [-v]
 	[-r <grouplist>]  [-a <grouplist>] [-l]

The options are as follows:

The -h switch is used to specify the host of the OrbixWeb daemon to send the request to; it defaults to the local host.

If more than one of the switches -r, -a and -l is specified, they are executed in the order

-r -a -l

• List the hosts in a specified group.
  
• Modify that list by adding or deleting hosts.
  

 grouphosts groupname [-h <hostname>] [-v]
 	[-r <hostlist>]  [-a <hostlist>] [-l]

The options are as follows:

The -h switch is used to specify the host of the OrbixWeb daemon to send the request to; it defaults to the local host.

If more than one of the switches -r, -a and -l is specified, they are executed in the order:

-r -a -l