This is an instant-mix package (just add Perl) to create Oraperl,
a version of Perl which is capable of accessing Oracle databases,
and Coraperl, a version of Oraperl which also includes Curses.
To use it, you must have the Oracle Pro*C product and a version of
Perl which supports Usersubs (v3.0.27 or later).

Unshar it somewhere convenient, and edit Makefile. You may need
to change the definitions below:

	ORACLE_HOME	your Oracle installation directory
	SRC		your Perl source directory (with the usub directory)
	OTHERLIBS	\ 
	CLIBS		 |
	OCILIB		 +- copy these from $ORACLE_HOME/c/demo/proc.mk
	NETLIBS		 |  (or whatever you use to link OCI programs)
	ORALIBS		/
	ALL_ORA_LIBS	summary of Oracle libraries.
			This is the one that the Makefile actually uses
	GLOBINCS	\ 
	LOCINCS		 +- copy these from $SRC/usub/Makefile
	LIBS		/
	CURSELIB	your curses library, if you're building Coraperl
	DEBUG		-DDEBUGGING, -DPERL_DEBUGGING or leave blank;
			see the file Debugging for an explanation
	DBUG_O		the debugging library, if debugging is required
	CACHE		default fetch cache size, if you want to change it
	BIND		if defined, do not pad empty bind values
	STRTOUL		\
	MALLOC_PTR_TYPE	 +- system dependent - see Makefile for details
	STR_2MORTAL	/
	TESTDATA	database, username and password for testing Oraperl

As well as oraperl, you can also type "make coraperl" to create a version
of Oraperl which incorporates curses. You must first compile curseperl (in
$(SRC)/usub), and leave the curses.o file there. You may need Perl v4.0.19
or later for this to work, as that was the first version to support System V
curses. Typing "make all" will make both oraperl and coraperl.

After building oraperl, type "make test" to run some rudimentary tests.
These are anything but exhaustive, but if anything goes wrong, you need
to check it. At present, the tests are just hacked from a couple of the
example scripts; if you have some better tests, please send them to me.

After testing oraperl (and optionally building coraperl) type "make install"
to install the binaries and the manual pages. They will be put in the same
directories as you specified for Perl, so the config.sh script must still
exist in your Perl source directory. The sample script example/sql will
also be installed, as it is a useful program in its own right.

I've only tested this on an Encore Multimax 520 running UMAX V (Sys Vr3.2),
using whichever version of Perl was current at the time that I completed
each release (covers the range 3.0.34 to 4.0.36, excluding 4.0.33) with
Oracle version 6, as I don't have access to any other system with Pro*C.
However, other people have compiled and used it on a range of different
systems including Amdahl, Convex, Cray, NeXT, Pyramid, Sun and Ultrix,
using Oracle versions 5 and 6. I'd appreciate any comments, bug-reports,
improvements, etc.

In addition to this README, the package contains the following files:

Source Code:
	Makefile	building instructions
	colons.c	counts substitution variables in a statement
	debug.c		translates numeric debugging codes to string
	getcursor.c	functions to deal with the cursor pool
	oracle.mus	function interface description
	orafns.c	oracle interface functions
	orafns.h	common declarations
	patchlevel.h	Oraperl version number and patch level
	strtoul.c	for systems which don't have strtoul(3)
	usersub.c	initialisation routine

Fred Fish' Debugging library (in the dbug/ directory):
	Makefile	makefile for the debugging library
	Readme		readme for the debugging library
	dbug.c		library code
	dbug.h		debugging header
	dbug.p		documentation for the debugging library
	dbug.qr		quick reference list
	fact.c		sample program (taken from the manual)

Examples (in the examples/ directory):
	Readme		introduction to the examples
	bind.pl		use of ora_bind and ora_fetch for table lookup
	ckdebug.pl	tests to see if debugging is available
	commit.pl	using commit and rollback
	ex.pl		simple example of Oraperl functions
	japh		just another perl hacker, in Oraperl
	mkdb.pl		more extensive example, using curses if available
			you can run this with either Oraperl or Coraperl
	oradump.pl	dump an Oracle table into a set of insert statements
	sql		execute an SQL statement from the command line
			(this one is worth installing)
	tabinfo.pl	display the structure of a database table

Documentation (in the doc/ directory):
	oraperl.ref	quick reference - glue it into the perl reference guide
	oraperl.1	manual page

Testing information (in the testdir/ directory)
	Readme		 test information
	Standard-Results correct results for a test run
	commit.pl	 test script
	japh.pl		 test script
	mkdb.pl		 test script

Miscellaneous:
	Changes		Summary of changes to Oraperl
	Debugging	Details of the built-in debugging routines
	Hints		notes concerning problems which have arisen in the past
	Long		information about LONG and LONGRAW support
	Makefile	builds (c)oraperl and documentation, cleans up
	Row_cache	describes the speed improvements due to caching
	install.pl	Perl script to install Oraperl
	oraperl.ph	definitions of Oraperl error and debugging codes

Many thanks to Larry for Perl.

	Kevin Stock
	kstock@encore.com


		 IMPORTANT NOTICE - Warranty and Copyright

Oraperl is not a product of either Encore Computer Corporation or Oracle
Corporation or any of their subsidiaries. There is no warranty, and no
official support is available.

It is Copyright 1991, 1992, 1993 Kevin Stock, but may be freely distributed
under the same terms as Perl itself, that is, under the terms of either
the GNU Public License or the Artistic License.
