Oratcl

INSTALLATION

Oratcl can be added to standard Tcl's tclsh and wish, or to Extended Tcl's
tcl and wishx.  I recommend using Extended Tcl, as the sample programs
require Extended Tcl.

Alternatively, Oratcl supports building a shared library that can be
loaded using Tcl's 'package require' or 'load' commands.

First, I would recommend that you start from a working Tcl/TclX/Tk base.
Compile all the code, run the 'test' targets, try out the tcl and wishx
interpreters.  Install tcl and wishx into public directories (e.g.
/usr/local/bin) and the Tcl, TclX, and Tk library code (e.g., /usr/local/lib)
Also try out the widget demos from the Tk package.  Everything works? Good,
now you can start on Oratcl.

Un-tar the Oratcl distribution in a sibling directory to tcl7.5, tk4.1,
and tclX7.5.0 (or the most current versions of each distribution.)

Oratcl uses GNU Autoconf to build a Makefile.  Run "./configure" in the
oratcl directory.  Configure recognizes the following options:


  --prefix=<path>      where to install in bin/ and man/ (default=/usr/local)
  --exec-prefix=<path> where to install in bin/  (default=/usr/local/bin)


  package options:     tk tclx enable-shared

  --without-tk         use "--without-tk" if you don't have Tk installed,
		       default is "--with-tk"
  --without-tclx       use "--without-tclx" if you don't have TclX installed, 
                       default is "--with-tclx"

  --enable-shared      enable building shared library, if your cpu/os allows
		       shared libraries.  The default is to build static
		       libraries and executables.
		       if you use "--enable-shared", configure sets
		       "--without-tk" and "--without-tclx", since the shared
		       library can be loaded into tclsh, tcl, wish, and/or 
		       wishx as needed.


  the following maybe specified, but configure tries to find the
  paths on its own if not specified:

  --with-oracle-directory=<path> where to find the Oracle home directory,
                                 for rdbms/lib/libocic.a or lib/libocic.a
  --with-oracle-version=<x>      use a specific Oracle version, "6" or "7", 
				 configure will try to determine the version
				 based on libocic.


The configure script tries to find Tcl, Tk, and TclX distributions in
sibling directories to where you unpacked Oratcl.  The environment variable
ORACLE_HOME is used to find the Oracle libraries.

If configure cannot find the paths to Tcl, Tk, TclX, or Oracle, configure
will halt with a message.  

Manual editing of the Makefile may be necessary if configure reports a warning.

After configure runs, examine 'Makefile', or just 'make' and see what happens.
 
If you specified '--enable-shared' while running configure, a shared
library will be built.  Otherwise, a static library will be built and
executables created.  If a static library is built, the Makefile gathers
up all of the Oracle libraries and bundles the objects into libOratcl.a along
with oratcl.o.

The default executables are `tcl' and `wishx', or `tclsh' and `wish' if
--without-tclx is specified.  If different executable names are desired,
you should edit the Makefile.

"make" will copy the AppInit files from Tcl or TclX and add a call to Oratcl's 
initialization function via a sed(1) script.  The oratcl.c and AppInit c 
files will them be compiled, and executables produced.

"make tests" will run a small script to make sure the resulting 
interpreter can access the database.

"make install" will copy the resulting executables, library and man page into
the specified directories.  If you specified '--enable-shared', a
pkgIndex.tcl file is built or modified in the tcl library directory.

Optionally, you can "make install-wosql" to copy the wosql program to
a directory, and change the #! interpreter line to reflect the Makefile
values.   Wosql requires TclX.

"make clean" will delete the .o files, executables, formatted man page,
and reset tclflags.mk to a firsttime: target.

You can add Oratcl to other Tcl/Tk interpreters.  Add a call to
"Oratcl_Init(interp)" to your tclAppInit.c or tkAppInit.c module, and link
with libOratcl.a.  If you are linking several extensions you may consider
using Tcl-my-fancy, a small package I wrote to aid this task.  See
ftp://ftp.neosoft.com/pub/tcl/NEW/tcl-my-fancy-2.0.tar.gz

Try out the sample Oratcl scripts.  It's also fun to start the tcl
interpreter, and just type in code on the fly.  Try benign SQL commands
at first, say:
	$ ./tcl
	tcl> oralogon scott/tiger       ** use a vaild connect string **
	tcl> oraopen oratcl0
	tcl> orasql oratcl0.0 {select * from emp}
	tcl> orafetch oratcl0.0
	tcl> orafetch oratcl0.0
	tcl> oracols oratcl0.0
	tcl> parray oramsg

Oratcl seems to fit in to the rest of Tcl/Extended Tcl/Tk without
name conflicts;  it does add a large chunk of Oracle libraries to
the tcl and wishx binaries on my machine.

The man page was written using -man macros.  Use your favorite nroff/troff
formatter, e.g. 
	nroff -man oratcl.man > oratcl.nr
	troff -Talw -man oratcl.man | alw > oratcl.ps
	psroff -Tdtps -t -man oratcl.man > oratcl.ps
	whatever


Tom Poindexter
tpoindex@nyx.net
