Oratcl

INSTALLATION ON UNIX

For installation on win and mac platforms, see the ./win and ./mac directories.

Oratcl can be added to standard Tcl's tclsh and wish, or to Extended Tcl's
tcl and wishx.  

Change to the ./unix directory to run configure and make.

Oratcl supports building a shared library by default that can be
loaded using Tcl's 'package require' or 'load' commands.
Static libraries and executables can be built by configuring 
with --disable-shared.

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.6, tk4.2,
and tclX7.6.0, or tcl8.0, tk8.0, tclX8.0.0 (or the most current versions of 
each distribution.)

Still using Tcl 7.4?  see ./unix/conf-tcl-74/*

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


  --prefix=DIR         where to install in bin/ and man/ (default=/usr/local)
  --exec-prefix=DIR    where to install in bin/  (default=/usr/local/bin)
                       the paths you specify should be the same as the paths
                       you specified when you configured Tcl and Tk.  Oratcl's
                       configure script uses the tclConfig.sh file that
                       was installed by Tcl in these locations.


  package options:     --with-tk --with-tclx --disable-shared

  --with-tk            build static executable with Tk.
                       use "--without-tk" if you don't have Tk installed,
		       default is "--with-tk".  This is only recognized if
		       you also have specified "--disable-shared"

  --with-tclx          build static executable with Extended Tcl (TclX).
                       use "--without-tclx" if you don't have TclX installed, 
                       default is "--without-tclx".  This is only recognized if
		       you also have specified "--disable-shared"

  --disable-shared     disable building shared library, build static libraries
		       and executables instead.
		       The default is to build a shared library.  

		       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.

		     * NOTE: --enable-shared can only be specified if your
		       Oracle distribution includes a shared library object,
		       e.g $ORACLE_HOME/lib/liboracle.so or libclntsh.so
		       (architecture appropriate shared library extension).

                       On some systems, it may be possible to build the
		       Oracle shared library if if doesn't already exist.
		       Under Solaris 2.4 there is a makefile:
			 $ORACLE_HOME/rdbms/lib/clntsh.mk
		       All it does is to call the shell script:
			 $ORACLE_HOME/rdbms/lib/mkclntsh.sh
		       which builds the Oracle shared library. 
		       (thanks to Larry W. Virden for this info)

                     * NOTE 2: It is highly recommended that you have
                       configured Tcl with '--enable-shared'.  The configure
                       and Makefile for Oratcl uses information in tclConfig.sh
                       for searching for dynamic libraries at run time.  This
                       information is only included in tclConfig.sh if Tcl
                       was configured with --enabled-shared.  Otherwise, it
                       may be necessary that you include the path to your
                       Oracle libraries in the environment variable used for
                       searching for dynamic libraries, typically
                       LD_LIBRARY_PATH or LPATH, depending on your cpu/os.
                       See the man pages for ld(1), ldd(1), or dlopen(3) for 
                       details and the correct flag for your cpu/os.
 

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

  --with-oracle-directory=DIR    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.


You should specify the same "--prefix=DIR" and "--exec-prefix=DIR" as when you
built Tcl, Tk, and TclX.

The configure script tries to find Tcl, Tk, and TclX installation files in the
same directory path as specified with --prefix= (default /usr/local). Configure
expects to find $prefix/lib/tclConfig.sh, tkConfig.sh, and tclxConfig.sh; 
$prefix/include/ for tcl/tk/tclx include files; $prefix/lib/ for 
tcl/tk/tclx libraries.  

The environment variable ORACLE_HOME is used to find the Oracle libraries, or
specify the Oracle home using --with-oracle-directory=DIR

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.
Also check the value of the 'OTHER_LD_SEARCH_FLAGS' if you are building
the dynamic library version of Oratcl.

After configure runs, examine 'Makefile', or just 'make' and see what happens.
 
If you specified '--enable-shared' (the default)  while running configure, a 
shared library will be built.  Otherwise, if you specified '--disable-shared',
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 install" will copy the resulting executables, library and man page into
the specified directories.  If you specified '--enable-shared' (the default), a
pkgIndex.tcl file is built or modified.

Note on pkgIndex.tcl:  The Makefile builds a pkgIndex.tcl file, and installs
it into a versioned Sybtcl directory.  This scheme works for Tcl 7.6 and 
later.  If you are using Tcl 7.5, you will have to manually install this
file into your Tcl library directory (e.g. /usr/local/lib/tcl7.5)

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

"make clean" will delete the .o files, executables, formatted man page, and
configure cache files.

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
