Revision: $Id: README,v 1.1 1999/02/06 03:58:23 tbyrd Exp $ 

LICENSE AGREEMENT 
=================

omniProperties is copyright by Ted Byrd.  It is free software; you can
redistribute it and/or modify it under the terms of the GNU Library General
Public License as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This application is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public License
for more details.

You should have received a copy of the GNU Library General Public License
along with this package; if not, write to:

Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA  02111-1307
USA


INTRODUCTION
============

This is the first public release of omniProperties.  This package provides an
implementation of the COSS Property Service and a simple client used to access
and test it.

For more information regarding the Property Service see the OMG CORBAServices
specification.  If you do not have a copy of the specification, you may obtain
it from http://www.omg.org/corba/sectrans.html.

omniProperties was developed and tested with omniORB 2.7.0 on these platforms:

   Windows NT Workstation 4.0 SP3/Visual C++ 5.0 SP3
   Red Hat Linux 5.1/egcs


INSTALLING AND BUILDING
=======================

omniProperties is designed to integrate into the omniORB2 development
environment.  Extract the archive into your omniORB directory.  The files
are installed into the appl directory.  You will need to modify the dir.mk
file in appl to include the omniProperties directory in the make.  You may
also build omniProperties by performing the following:

cd <omniORB_root>/src/appl/omniProperties
make

or

cd <omniORB_root>/src/appl/omniProperties
make export

When complete the following executables are produced:

omniProperties    A default COSS Property Service implementation
propclt           The property service client


IMPORTANT NOTE:  This implementation relies heavily on STL, C++ templates, and
exceptions.  If your compiler doesn't support them, you won't be able to
compile omniProperties.  You may also encounter porting problems due to the
STL.  I used Visual C++ 5.0 for the initial development, and I think their
implementation is whack.  That or I'm just a stupid STL newbee, which is
entirely possible. :)  The results ported to Linux nicely though.


RUNNING THE SERVICE
===================

Once properly built and installed, you are ready to run the service.  Follow
these steps:

1. Start the naming service

   The property service registers the factory's name with the naming service.
   Please refer to the omniORB2 and omniNames documentation if you don't know
   how to to run the omniNames naming service.

2. Start the property service

   The default implementation of the property service enables clients to
   create instances of CosPropertyService::PropertySetDef objects.  This
   factory registers itself with the naming service using a default name and
   kind of PropertySetDefFactory and PropertySetDefFactory, respecively.  If
   you wish to you run the service using another name, start it with the
   following options:

   Usage: omniProperties [-N name] [-K kind] [-h]

   [-N name]  specify factory name
   [-K kind]  specify factory kind
   [-h]       display usage message

   Once started, omniProperties will block indefinately waiting for requests
   from clients.

3. Test the service

   The supplied propclt utility is a simple front end to the property service.
   With it you may create and destroy property sets, add, update, and remove
   properties from a set, find the value of a property in a set, change the
   mode of a property in a set, list the contents of a set, and import and
   export the contents of a property set to a file.

   It is limited in that it may only insert and extract string data from the
   property set.  Though partial support is provided for reading shorts and
   longs as well.  Improving this is something I'll leave as an exercise to
   the reader.

   Usage: propclt command [options]

   Where 'command' is one of the following:

   create     Create a new property set
   destroy    Destroy an existing property set
   add        Add a property to a set
   remove     Remove a property from a set
   update     Update a property in a set (same as 'add')
   find       Find a property in a set
   list       List all properties in a set
   mode       Set property mode
   import     Import properties from a file
   export     Export properties to a file
   help       Display this usage message

   And 'options' are one or more of the following:

   [-N name]  Factory name for create and destroy (def: PropertySetDefFactory)
   [-K kind]  Factory kind for create and destroy (def: PropertySetDefFactory)
   [-s name]  PropertySet name for all operations (def: PropertySetDef)
   [-k kind]  PropertySet kind for all operations (def: PropertySetDef)
   [-n name]  Property name for add, remove, update, mode, and find
   [-v value] Property value for add and update
   [-m mode]  Property mode: normal, read_only, fixed_normal, or fixed_readonly
   [-f file]  File name for import and export


   To test the service, use the client to perform the following commands:

   a. Create a property set

      % propclt create

   b. Import the sample property set

      % propclt import -f import.dat

   c. List the contents of the property set

      % propclt list

   d. Add a new property

      % propclt add -n new -v foo

   e. Delete a property

      % propclt delete -n name

   f. Update a property

      % propclt update -n name -v "Bill Smith"

   g. Change the mode of a property

      % propclt mode -n new -m fixed_readonly

   h. Delete the property set

      % propclt destroy


CONTACTING THE AUTHOR
=====================

If you have any comments or suggestions, please send email.  I would also
like to know if anyone finds any bugs (I'm sure there are still a few hiding
in there), especially if you have a fix! I have very limited time to support
omniProperties, so feature requests will have to wait until I need them. :)

This is my first "real" omniORB application, as well as my first STL based
application in a while.  Please let me know if you find anything that I could
be doing better, smarter, faster, or easier!

Enjoy!

Ted Byrd
tbyrd@idiom.com
