# $Id: README,v 1.7 2002/01/10 04:44:41 bfoddy Exp $

PHP-ENDUROX


IMPORTANT:  This project is work in progress, so the
building and installing process is not very automated yet.
Please read this document carefully.  Afterall, the standard
configure, make, make install steps just don't exist yet.



PLEASE...PLEASE 
Report any and all success and failures back to me.  I want to hear
how things are going.  This is the first version so 
I expect bugs and problems so I won't be offended.


These steps should provide the basis for a build on Linux
or Solaris.  Other UNIXs should be similar enough.
Windows ... I can say it is being worked on, if you can't wait
write me for the latest status.

NOTE:  The Makefile is set to build a workstation client,
requiring a WSH listener.  If you want to build a direct
client, it should work by changing the libraries, but I've
not tried that yet.

What is included?
This module so far has only been tested on Endurox 6.5, but
should work with other versions.

Reference the php_endurox.api document for a complete list
of endurox function calls included.  Its the core basic
functions a client would need.  There are many still not
done yet.  

No XML buffer functions either (a 7.1 feature).



PRE-BUILDING  (IMPORTANT, please READ carefully).

Before you can build PHP-Endurox, you must decide if you 
want to build it as a DL module or directly into PHP.
A DL module is a dynamic module that is loaded by PHP
each and every hit, and unloaded at the end of the hit.
It has the distinct advantage of being easier to load into
a existing PHP install because PHP itself is not rebuilt.
The make process for a DL module is a little more straight
forward, but more manual in nature.  The DL method is
documented in README.dl.

The second method to build PHP-Endurox is to directly 
build it as a permanent module inside PHP.  Built this way
you don't need to DL any external files, and performance
will be faster as PHP doesn't need to do any runtime 
calls to dlopen.  This method also has the distinct 
advantage of being able to debug a core file or running
program with most standard debuggers.  Building in this 
manor is more automated and simplier, but requires more 
tools before you can begin.  PHP uses the GNU libtool,
autoconf, automake, and m4 tools to construct its config
file.  To build PHP-Endurox as a permanent extension, you
need to rebuild these config files.  So these GNU packages
are required:

GNU m4 1.4  (http://www.gnu.org/directory/m4.html)
GNU autoconf 2.13  (http://www.gnu.org/directory/autoconf.html)
GNU automake 1.4  (http://www.gnu.org/directory/automake.html)
GNU libtool 1.4  (http://www.gnu.org/directory/libtool.html)

Similar or newer versions should also work.  Many Linux
distributions should already have these tools.  Most Solaris
or other commercial UNIXs probably don't have these installed.
You may want to use a mirror site like gnu.sunsite.utk.edu
to download as the main site is usually quite busy.  The
build of these packages is painless.
NOTE:  These can be installed in a local user directory.

The over time the DL build option will be depreciated
so if possible try the direct method.

Which version of PHP?
Since PHP itself is a moving target its hard to keep a 
document up-to-date on which version to use.  General advise,
use the latest released version.  PHP sometimes has API changes
between different releases so our code must make corresponding
changes.  One such change was between 4.0.4 and 4.0.5.  The 
latest version of PHP-Endurox has been modified for the 4.0.5
changes.  If you must use 4.0.4 you will need to undo these
changes by applying a patch file provided in
misc/php_endurox_arrayubf.c._4.0.5-4.0.4.patch.

4.0.6 changes:  The config.m4 file required modification for
PHP 4.0.6.  Primarily, many of the AC_ macros were redefined
as PHP_ macros.  If you intend to use this release of older
versions of PHP, you will need to change them back.

4.1.0 changes:  The PHP API again changed in 4.1.0.  This time
the changes were able to be #if able in the source code so
the code should be backward compatable with older versions.


Which version of ATR Baltic Endurox?
This program has been successfully built on Endurox versions
from 6.5 up to 8.0.  However some of these version changes
required a link change to Endurox clients; different libraries,
etc.  Until we get our build process automated enough to detect
which version of Endurox its being linked against, you may need
to slightly alter the linking process to match the provided 
libraries in Endurox.  Generally, php-endurox must perform the
same linking as would be described in a 
buildclient -v command.  The linking currently in this release
should work with Endurox 6.5 without change.  I know 8.0 requires
alterations; I'm unsure about 7.1.  If you need help, please
post messages on the support forumns and we will do our best.

This version does NOT support any new features in 7.1 or 8.0
but will work with these versions to the 6.5 feature list.


Building as a DL module is described in README.dl.


===========================================================================
Using the direct external PHP method...

BUILDING.
1.  Obtain and extract the PHP4 source code for the version
	loaded in your web server in a clean directory (php-4.1.1)
	If its old, maybe this is a good time to upgrade and
	get the latest at www.php.net.  I've been using 4.1.1.
	Versions between 4.1.0 and 4.0.4p1 have worked but you
	may encounter API changes that need to be undone.
	Nothing older than 4.0.4p1 has been tested.
	
2.  Create a new directory in the php source of
	php-4.1.x/ext/endurox and copy the contents of the
	php-endurox distribution into this directory.
	
3.	From the php-4.1.x directory, run
	./buildconf
	This will rebuild the configure script to include the
	new php-endurox module.

4.	Configure PHP4 according to the instructions for
	that package (./configure {options})
	Include a new option of "--with-endurox=[DIR]"
	with the configure.  DIR should be the location of
	the Endurox package (usually $NDRXDIR).  To check if
	this step completed successfully, there should now
	be a Makefile in ext/endurox (not to be conbused with
	Makefile.in).
	
5.	Type "make".  If the previous steps worked correctly
	it will automatically build PHP with the new PHP-Endurox
	module included.  You may watch for the endurox compile
	steps to be sure.
		
6.	Following the normal steps of PHP, "make install".


INSTALLING / TESTING

1.	Create a file ndrxph_phpinfo.php in this directory with the contents of
	<?php
		phpinfo ();
	?>
	NOTE:  DO NOT put a dl ("php-endurox.so") statement in this script.
	Php-endurox is already loaded.
	
	
2.	Run this script.  If everything is successful, you should see a
	section ATR Baltic Endurox Module with some of the more common environment
	variables for Endurox set (NDRXDIR and WSNADDR).
	If the section is there, congrats you probably
	built the module correctly.  If some of the environment variables
	(like WSNADDR) aren't set correctly, now is a good time to
	make sure your web server has these variables set.  Remember your
	web server is now a Endurox client; all the normal rules 
	still apply.
	
3.	You are ready to go.  See the php_endurox.api for a list of functions
	currently available and their arguments.

==========================================================================
==========================================================================


Questions or problems, leave me notes on the web site tools.
Brian