webtama e-pets Files

    Please read the file 'COPYING.LIB' for license information, and please
    let me know how the tools work for you. The more I hear from people
    who use this code the more I'm encouraged to write. 
   
    This release of the webtama server includes configure and autoconf
	support. This eliminates the requirement to customize the Makefile
	for each specific platform.

	Building this platform requires libubiqx Version 1.1 with gdbm support
	    ** Note this version currently only available from MrCompiler.com
	The gdbm software package from the Free Software Fouondation
	The flex software package from the Free Software Fouondation
	The bison software package from the Free Software Fouondation

    In addition linking requires the GNU Version 2.9.1 linker with
	--whole-archive support.

	This package creates a client/server application that maintains a
	database of e-pets called webtamas. These webtamas are simple creatures
	which must be fed and petted regularly or they will die of starvation or
	lonliness. Users connect to the server via telnet and a client process
	is forked. The user logs in ( password encryption is supported ) and
	they may manage their tamas including creating new ones or caring for
	existing ones. The user commands are: CREATE, FEED, PET, STATUS and
	KILL. A prototype user client stub is provided for future development.

	If a tama is not fed it begins to lose weight until ultimately it will
	die of starvation. Feeding the tama resets the clock. Similarly if it
	is not petted regularly it will die of lonliness.

	If a tama is fed intermintantly enough it will still die of neglect.

	A tama may also be intentionally killed using the KILL command. A tama
	may only be killed by its owner or the admin user.

	A dead tama is purged from the system some time after death. After
	purging the tama is expunged from the system and cannot be resurrected.
	
	An interesting quirk. If the user pets a dead tama ( warnings are issued )
	the tama is not purged and remains a candidate for resurrection by the
	admin. The only feedback a user gets is that the tama continues to be
	marked 'Resting Peacefully' instead of disappearing as most corpses do.

	This was an intentional philosophical decision. The role of tama
	creator leads to some interesting discussions on the fundamental role
	of god in making certain decisions.

	Quick Start:

	./configure --with-ubiqx
	Your system must have the ubiqx library installed.

	The default installation directories are /usr/local/bin for the
	binaries and /usr/local/etc/webtama for the data files. These may be
	controlled using the --prefix-mumble options of configure.

	NOTE: In addition to the standard configure options this release
	includes --with-parser-debug to enable flex/bison debug flags and
	set the YYDEBUG compile flag. It also supports --with-gdbm which
	will add support for linking additional gdbm functionality into
	application programs

	then type:

	make all

	This will build the tamad and tama_ctl binary. While the run time model
	has 3 active server types ( the connection server, one or more client
	servers and a centralized database seve ) these are all forked from
	a single executable.

	Once the build is complete you can start the server with:

    mkdir /usr/local/etc/webtama # created by 'make install'
	# modify the permissions and ownership of the data directory
	chmod 664 /usr/local/etc/webtama # created by 'make install'
	# run the tamad server
	bin/tamad 

	NOTE: To reinitialize the server simply delete all files in the webtama
	data directory

	bin/tamad and bin/tama_ctl ( user management ) both support -h

	After starting a copy of the server you can connect to using

	telnet localhost 9111

	The default user name is admin and the default password is 'password'

	Commands are upper case only. type HELP for a list.

	webtama quick start:

	webtama> CREATE filbert
	webtama> STATUS filbert
	webtama> PET filbert
	webtama> FEED filbert
	webtama> KILL filbert
	webtama> STATUS filbert
	webtama> LIST ALL
	webtama> LIST
	webtama> BYE

	To install the binaries use 'make install'. The data files will be
	created dynamically by the server at runtime.

	NOTE: by default this build will link with the libubiqxDB
	dynamic link library. This requires that you have either the
	lib/ubiqx subdirectory or the ubiqx install directory (default
	/usr/local/lib/ubiqx) listed in your LD_LIBRARY_PATH environment
	variable at runtime.

	Users may be added and deleted with the tama_ctl binary, the user
	records are not directly manipulated by the online server.

	To add a user type:
	bin/tama_ctl -a {username} {password} {email address}

	To change a user password or email use:
	bin/tama_ctl -a {username} {password} {email address}

	NOTE: The password must be supplied to change the email.

	NOTE: shell special characters such as @ and ! may require an
	escape character for example foo\@bar.com

	The tamad servers creates several databaes files. These are located in
	${prefix}/etc/webtamas. The files are:

	tamas - Contains the database of current tamas 
	numbers - maintains serially assigned ID numbers and user tama counts
	users - contains information about each user
	races - contains information about races

	The database engine maintains a number of local relations, the numbers
	database contains serial id assignment information for the tamas and
	user databases. Additionally it contains the tama counts for each of
	the users. This is validated during the db server maintenance cycle.

	Additionally there is a relationship between the tamas and the users
	that identify ownership and a relation between the tamas and the races
	database.

	The files and their associated databases are managed collectively by
	the db_server using the ubiqx database infrastructure and are referred
	to collectively as the tama database or tamaDB.

	tamas are indexed by tamaID and ownerID
	users are indexed by alpha user name ( user names must be unique )
	races are indexed by race ID

	The numbers database is polymorphic and supports two types of keys. For
	serially assigned identifiers such as race or tama id the index key is
	an enumerated value that indicates the serial data type, for the tama
	counts the key is an enumerated value for tama count plus a second
	field with the user ID for which the count is maintained.

	The database indexing scheme was chosen to illustrate both types of
	persistant store indexing types ( numeric and character arrays ).