$Id: README 94566 2011-10-05 09:34:42Z johnnyw $

This directory contains a test for the ACE_Name_Server library.  This
test program also illustrates how to use the ACE Service_Config
mechanism, which enables the client code to be dynamically linked into
the process at installation-time or run-time.

The client test is an application that allows the user to vary the
test parameters through the following menu driven interface:

         Name Service Main Menu
         ----------------------
  *** Using Process Local Database ***

<P> Use Process Local Database
<N> Use Node Local Database
<H> Set Remote Name server <host> and <port>

<B> Bind <key> <value> [<type>]
<U> Unbind <key>
<R> Rebind <key> <value> [<type>]
<F> Find <key>
<J> Lookup keys matching <pattern>
<K> Lookup values matching <pattern>
<L> Lookup types matching <pattern>
<C> Complete lookup keys matching <pattern>
<D> Complete lookup values matching <pattern>
<E> Complete lookup types matching <pattern>

<Q> or ^C (exit)

Initially, the user can select the type of database -- process local,
node local, or net local -- from the menu.

<P> uses the process local database (i.e., the database is called the
    same name as the process and stored in /tmp).
<N> uses the node local database (which defaults to /tmp/localnames).
<H> uses the net local database by specifying host and port number (by
    default this is stored in a file called /tmp/globalnames on the server).

The user can then create new bindings, delete existing bindings, or
rebind bindings:

<B> Bind <key> <value> [<type>]
	             -- binds the key to the value and adds the
			binding to the database. Note that type
			information is optional.
<U> Unbind <key>     -- unbind a binding whose key is <key>
<R> Rebind <key> <value> [<type>]
	             -- rebind <key> to <value>. Once again <type> is optional.
<F> Find <key>	     -- find the binding associated with key <key>
<Q> or ^C (exit)     -- exit gracefully, saving the contents of the
                        Name Server in persistent shared memory.

In addition, the user can do pattern matching for keys, values, and
types. Note that pattern matching is supported using regular expressions.

<J> Lookup keys matching <pattern>
		     -- find all keys that match <pattern>
<K> Lookup values matching <pattern>
		     -- find all values that match <pattern>
<L> Lookup types matching <pattern>
		     -- find all types that match <pattern>

<C> Complete lookup keys matching <pattern>
		     -- find all bindings whose keys match <pattern>
<D> Complete lookup values matching <pattern>
		     -- find all bindings whose values match <pattern>
<E> Complete lookup types matching <pattern>
		     -- find all bindings whose types match <pattern>

-------------------------
Running the tests:

The test program uses a DLL supported by the svc.conf file, which
allows them to configure the client-side dynamically.  The client test
program accomplishes this by making use of a Singleton proxy object
(Name_Service) to provide an interface to the client-side.

The test programs rely on svc.conf to provide the necessary parameters
for dynamically linking the Name Service library and then
executing. In the absence of svc.conf, the test programs would use
static binding.

client:

The client test can be started without any parameters. However, if the
user wants to use the net local database, the hostname and the port
number of the server containing the net local database can be given at
"command line" in the svc.conf file, e.g.:

dynamic ACE_Naming_Context Service_Object * libACE.so:_make_ACE_Naming_Context ()
						"main -h tango.cs -p 7891"
dynamic Name_Server_test Service_Object * .shobj/Client_Test.so:_make_Client_Test () ""

The above example starts the client test application and sets up a
connection to port 7891 to a Name Server running on tango.cs, which
has the net local database.  The Client_Test directive must come after
ACE_Naming_Context since it relies on the ACE_Naming_Context having
been dynamically linked.

Note that you can also use environment variables in the "command
line", as follows:

dynamic ACE_Naming_Context Service_Object * libACE.so:_make_ACE_Naming_Context ()
						"main -s $DB -p $PORT -h tango"
dynamic Name_Server_test Service_Object * .shobj/Client_Test.so:_make_Client_Test () ""

In this example, $DB and $PORT are environment variables that are
automatically interpreted and substituted by ACE.  In addition, note
how you can give a relative name for the libACE_svcs.so and ACE will
locate this for you automatically by reading your LD search path.

server:

The name server is needed only in the case where the net local
database needs to be accessed.  The server test needs to run on the
machine that contains the net local database.  To execute the server
test, the user has to specify the port number at which the server will
be listening in the svc.conf file.  An implementation of a name
service for ACE is available in the $ACE_ROOT/netsvcs/{lib,servers}
directories.  Please see the README files there for an explanation of
how to run the server.


