<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>The OMNI Naming Service</TITLE>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<STYLE type="text/css">
.toc{list-style:none;}
.title{margin:auto;text-align:center}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
DIV TABLE{margin-left:inherit;margin-right:inherit;}
PRE{text-align:left;margin-left:0ex;margin-right:auto;}
BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
.part{margin:auto;text-align:center}
</STYLE>
</HEAD>
<BODY >
<!--HEVEA command line is: hevea omniNames -->
<!--HTMLHEAD-->
<!--ENDHTML-->
<!--PREFIX <ARG ></ARG>-->
<!--CUT DEF section 1 -->
<BR>
<TABLE CLASS="title">
<TR><TD>
<H1 CLASS="titlemain">The OMNI Naming Service</H1>
<H3 CLASS="titlerest">14 February 2008</H3></TD>
</TR></TABLE><BR>
<!--TOC section Introduction-->
<H2 CLASS="section"><A NAME="htoc1">1</A> Introduction</H2><!--SEC END -->
The OMNI Naming Service (<EM>omniNames</EM>) is an omniORB
implementation of the OMG's COS Naming Service Specification. It
offers a way for a client to turn a human-readable name into an object
reference, on which the client can subsequently invoke operations in
the normal way. See the OMG specification for full details of the
functionality provided by the Naming Service.<BR>
<BR>
The Naming Service stores a set of bindings of names to objects.
These bindings can be arranged as an arbitrary directed graph,
although they are often arranged in a tree hierarchy. Each node in
the graph is a <EM>naming context</EM>. There is a “root” context at
which name lookups usually start. This is the object returned by the
call to <CODE>CORBA::ORB::resolve_initial_references("NameService").</CODE><BR>
<BR>
<!--TOC section `Log' file-->
<H2 CLASS="section"><A NAME="htoc2">2</A> `Log' file</H2><!--SEC END -->
The Naming Service is often part of the bootstrapping process of other
CORBA programs. For this reason, if an instance of omniNames crashes
(or the machine on which it runs is rebooted), it is important that
certain aspects of its operation persist upon restarting. Firstly the
root context of the Naming Service should always be accessible through
the same object reference. This helps the ORB to implement the
<CODE>resolve_initial_references</CODE> call by allowing the object
reference to be stored in a configuration file, for example.
Secondly, the naming graph with all its bindings should persist
between invocations.<BR>
<BR>
To achieve this, omniNames generates a redo log file, to which it
writes out an entry every time a change is made to the naming graph.
The directory in which this log file is written can be specified with
the <CODE>OMNINAMES_LOGDIR</CODE> environment variable. When omniNames is
restarted it uses the log file so that it can regenerate the naming
graph.<BR>
<BR>
Periodically the log file is checkpointed, removing unnecessary
entries from the log file. The idle time between checkpoints can be
set with the <CODE>OMNINAMES_ITBC</CODE> environment variable. It defaults
to 15 minutes.<BR>
<BR>
<!--TOC section Starting omniNames and setting omniORB.cfg-->
<H2 CLASS="section"><A NAME="htoc3">3</A> Starting omniNames and setting omniORB.cfg</H2><!--SEC END -->
When starting omniNames for the first time, you can either let it
start with the default TCP port of 2809, or you can specify the port
number on which it should listen. This is written to the log file so
that on subsequent invocations it will listen on the same port number
and thus can be accessible through the same object reference. When
omniNames starts up successfully it writes the stringified object
reference for its root context on standard error.<BR>
<BR>
At startup, omniORB tries to read the configuration file
<CODE>omniORB.cfg</CODE> to obtain the object reference to the root context
of the Naming Service. This object reference is returned by
<CODE>resolve_initial_references("NameService")</CODE>. There are a number
of methods of specifying the root naming context in
<CODE>omniORB.cfg</CODE>—see the omniORB manual for details.<BR>
<BR>
<!--TOC section Command line parameters-->
<H2 CLASS="section"><A NAME="htoc4">4</A> Command line parameters</H2><!--SEC END -->
omniNames accepts the following command line parameters.<BR>
<TABLE CELLSPACING=2 CELLPADDING=0>
<TR><TD VALIGN=top ALIGN=left NOWRAP> </TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-help</TT></TD>
<TD VALIGN=top ALIGN=left>Output usage information.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-start </TT><I>[port]</I></TD>
<TD VALIGN=top ALIGN=left>Start omniNames for the first time, listening on
<I>port</I>.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-always</TT></TD>
<TD VALIGN=top ALIGN=left>In conjunction with <TT>-start</TT>, always start up
omniNames, even if its log file already exists.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-logdir </TT><I>directory</I></TD>
<TD VALIGN=top ALIGN=left>Specifies the directory for the redo log file, overriding the
default.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-errlog </TT><I>filename</I></TD>
<TD VALIGN=top ALIGN=left>Causes output that would normally be sent to stderr to go to the
specified file instead.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-nohostname</TT></TD>
<TD VALIGN=top ALIGN=left>Normally, omniNames includes the host name in the name of the redo
log file. This option disables that, meaning the log file can be
used on a different host, or if the host name
changes.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-ignoreport</TT></TD>
<TD VALIGN=top ALIGN=left>omniNames normally adds its own endpoint, based on the port
specification (given with <TT>-start</TT> or stored in the log
file). This option causes it to ignore the port. It should be used
in conjunction with specific <TT>-ORBendPoint</TT> options to
ensure object references are stable.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-install </TT><I>[port]</I></TD>
<TD VALIGN=top ALIGN=left>On Windows, install omniNames service. See below.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-manual</TT></TD>
<TD VALIGN=top ALIGN=left>On Windows, specify that the service should be started
manually. See below.</TD>
</TR>
<TR><TD VALIGN=top ALIGN=left NOWRAP><TT>-remove</TT></TD>
<TD VALIGN=top ALIGN=left>On Windows, uninstall omniNames service. See below.</TD>
</TR></TABLE><BR>
<!--TOC section Windows service-->
<H2 CLASS="section"><A NAME="htoc5">5</A> Windows service</H2><!--SEC END -->
omniNames can be run as a Windows service.<BR>
<BR>
To install the service, run with the <TT>-install</TT> command line
option, with a port to override the default 2809 if necessary. The
command line should include any other parameters of relevance, such as
the log directory and error log file. It is particularly important to
specify an error log file, since the service runs in an environment
where stderr goes nowhere. Similarly, if omniORB tracing is requested
with the various <TT>-ORBtrace</TT> options, <TT>-ORBtraceFile</TT>
should be specified, otherwise the trace messages vanish.<BR>
<BR>
The service is normally configured to start at system startup time.
Specifying <TT>-manual</TT> configures it for manual startup.
Regardless of that setting, the service is not automatically started
at the time it is installed. It should be started manually with the
service control manager if it is to run before the next system
restart.<BR>
<BR>
Once installed, the service can be uninstalled by running omniNames
with the <TT>-remove</TT> option.<BR>
<BR>
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY>
</HTML>
