Sybtcl

INSTALLATION

For installation on win and mac platforms, see the relevant README
files in the ./win and ./mac directories.  The rest of this document
is focused on Un*x/Linux and similar environments.

Sybtcl by default builds as a shared library, or you can build it as a 
statically linked executable, with or without the fine Extended Tcl (TclX)
extension.

Sybtcl 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 wish 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 Sybtcl.

Un-tar the Sybtcl distribution in a sibling directory to tcl8.3, tk8.3,
and (optionally) tclX8.2 (or the most current versions of each distribution).

If you are working in a TEA-compatible environment (Tcl 8.2.x or newer on
Unix or under cygwin32), you should be able to do ./configure and make in
the sybtcl top-level directory.  This will build sybtcl as a stub-
enabled shared library.  See below for details on items that can be 
changed with './configure'.

If you are using an older version of Tcl or desire some variant from the
above build, you should cd to the 'unix' directory first, then run
'./configure'.  Configure recognizes the following options:

  --prefix=DIR         where to install man, bin, and lib
  --exec-prefix=DIR    where to install bin and lib, if different than --prefix
		       the paths you specify should be the same as the paths
		       you specified when you configured Tcl and Tk.  Sybtcl's
		       configure script uses the tclConfig.sh file that
		       was installed by Tcl in these locations.


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

  --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
                       Sybase distribution includes a shared library object,
                       e.g $SYBASE/lib/libsybdb.so (architecture appropriate
                       shared library extension).

                     * NOTE 2: It is highly recommended that you have 
		       configured Tcl with '--enable-shared'.  The configure
		       and Makefile for Sybtcl 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
		       Sybase 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), chatr(1) or 
		       dlopen(3) for details and the correct flag for 
		       your cpu/os.  

  --enable-ctlib       build Sybtcl using Sybase's CT-Lib.  This option
                       is normally NOT RECOMMENDED.  Sybtcl is written to
                       use Sybase's DB-Lib.  --enable-ctlib is designed for
		       systems that do not have DB-Lib available.
		       See the ./ctcompat directory for more information,
		       README.ctcompat.  ALSO NOTE- not all tests will
		       pass when using the ctcompat lib.  As of Sybtcl-3.0,
		       certain background event processing tests are likely
		       to behave differently.


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

  --with-sybase-directory=DIR   where to find the Sybase home directory,
				 include/sybdb.h  lib/libsybdb.a  



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 SYBASE is used to find the Sybase libraries, or
specify the Sybase home using --with-sybase-directory=.
 
If configure cannot find the paths to Tcl, Tk, TclX, or Sybase, 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 Sybtcl, adding flags specific to your 
environment to help find the shared libraries at runtime, such as -R on 
Solaris with SunPro cc.

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 the Sybase library and bundles the objects 
into libSybtcl.a along with sybtcl.o.  

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

"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.

Note on pkgIndex.tcl:  The Makefile builds a pkgIndex.tcl file, and installs
it into a versioned Sybtcl directory.  This scheme works for Tcl 8.0 and 
later.  

Optionally, you can "make install-tools" to copy the wisqlite program to
a directory, and change the #! interpreter line to reflect the Makefile
values.  Also installed are sybmon and sp_who.

"make clean" will delete the .o files, executables, formatted man page,
and configure cache files.  "make really-clean" cleans up the Makefile,
libtmp, config.status, and other junk.

You can add Sybtcl to other Tcl/Tk interpreters.  Add a call to
"Sybtcl_Init(interp)" to your tclAppInit.c or tkAppInit.c module, and link
with libSybtcl.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/devel/tcl-my-fancy-3.0.tar.gz

Try out the sample Sybtcl 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> sybconnect userid passwd   ** use a valid userid and passwd **
	tcl> sybsql sybtcl0 sp_who
	tcl> sybnext sybtcl0
	tcl> sybnext sybtcl0
	tcl> sybcols sybtcl0
	tcl> parray sybmsg


ADDITIONAL APPS

De Clark has built some wonder applications using Sybtcl, including the
feature-rich full version of Wisql.  Visit her site at:

    http://www.ucolick.org/~de/Tcl/

and visit the UCO Lick Tcl/Tk source code link to view and download all
these applications.


TEST SUITE

Beginning with Sybtcl 3.0, a test suite is included.  Type 'make tests'
to begin running the test suite.  You must supply an id, password, server
name, and database in which the test suite can build a small (30 row)
test table and stored procedure.  The test suite will also insert 
image and text columns of up to 1.5 mb.  All tables and stored procedures
created during the test suite are cleaned up at exit.

The database in which you perform test must have the option 
'select into/bulkcopy' set to true, otherwise the text/image tests
may fill your log device.  To set the option, have your DBA execute:
	use master
	go
	sp_dboption your_db_name, 'select into/bulkcopy', true	
	go
	use your_db_name
	go
	checkpoint
	go

DOCS

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

Tom Phelps' rman program is used to generate HTML from the man page.
See his TkMan and RosettaMan packages.

Man pages built as text, Postscript, and HTML are provided.


Tom Poindexter
tpoindex@nyx.net
