		     @(#)README	1.17	10/30/95

			   sybperl 2.0
	
	  This is sybperl, the Sybase extensions for Perl5.

       Copyright (c) 1991,1992,1993,1994,1995  Michael Peppler
			 All rights reserved.
			 
  This program is free software; you can redistribute it and/or modify
  it under the same terms as Perl itself.

  You should have received a copy of the Perl license along with Perl;
  see the file README in Perl distribution.
 
  You should have received a copy of the GNU General Public License
  along with Perl; see the file Copying.  If not, write to the Free
  Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

  You should have received a copy of the Artistic License along with
  Perl; see the file Artistic.

---------------------------------------------------------------------

Please read the UPGRADE file if your previous version of sybperl was
1.0xx.

This version requires Perl5.001. The 'official' unofficial patches 1a
through 1m are recommended (sybperl may fail to build cleanly without
these patches).
You can get a pre-patched version of Perl5.001m from most Perl source
archives (for example:
ftp://ftp.delphi.com/pub/mirrors/packages/perl/ftp.perl.com/src).

There are three modules in this distribution: Sybase::DBlib,
Sybase::Sybperl and Sybase::CTlib.

Sybase::DBlib implements the Perl 5 version of the DB-Library
API. This differs slightly from the Perl 4 version. Note that this is
not a full implementation of the DB-Library API.
The Sybase::Sybperl module implements the sybperl 1.0xx API, and is
built on top of Sybase::DBlib.

All of the sybperl 1.0xx API has been implemented, and there are some
extras (such as the two-phase commit routines).

Sybase::CTlib implements a subset of the newer Client Library API,
and should still be considered 'beta' software, although it is rapidly
becoming my favorite API for Perl/Sybase programing. Client Library is
included with Sybase's OpenClient libraries as of System 10.

---------------------------------------------------------------------

Installation:

Before you start, you have to consider the following issues:

a) Is Perl 5.001 (or later) already installed at your site?

   If Perl 5.001 is the default production version of Perl at your
   site, then i recommend that you unpack the sybperl distribution
   outside of the Perl source tree. The sybperl build process will
   normally be able to find the pieces it needs this is the case, and
   it will be easier for you to manage upgrades to Perl and/or to the
   add-on extensions that you may have if they are kept separate.

   If Perl 5.001 is not yet the default version of Perl, then you
   should unpack the sybperl distribution in the ext/ directory of the
   Perl 5.001 source tree.

b) Do you want the Sybase modules to be dynamically loadable?

   Most Unix systems come with the capability of loading object code
   into an already executing program dynamically, usually via some
   sort of special library (on SunOS, for example, it's libdl.a).

   The advantage of dynamic loading is that you do not need to install
   a new Perl binary to provide new functionality, and the size of the
   binary does not grow as you add this functionality. The cost is a
   small performance penalty on startup.

   Static loading might be more advantageous to those specific modules
   which you know you will be using very often (however, I use dynamic
   loading here at ITF, although nearly all our Perl scripts use the
   Sybase modules).

   Note that if you are using HP-UX, you can only use dynamic loading
   if you have the add-on (extra cost) C compiler (or GNU gcc) and if
   you have the System 10 shared libraries (libsybdb.sl vs libsybdb.a)
   as HP-UX can't load an object dynamically which has not been
   compiled with the PIC (position independant code) flag.


Once you have answered these two questions, you can proceed:

   1) Unpack the package.
      See comments under a) above.
      
      Note that even if you don't want to install Perl 5.001 as a
      production version right now, you can still install it in some
      other place, and access that version by setting your PATH
      variable accordingly (I have a production version Perl5.001m
      under /usr/local/{bin,lib} and a debug version of Perl5.001m
      under /f2/{bin, lib} and change my path when I need to test
      things with debugging turned on).
      
   2) Edit CONFIG
      See comments under b) above regarding dynamic vs static loading.
      
      
      NOTE: I have discovered what I think is a bug in Perl 5.001m
      which shows up when logically testing an array where all the
      elements are 'undef'. This bug can show up when you retrieve
      rows using dbsqlexec() or ct_fetch() using a while loop: if you
      retrieve a row where all the column values are NULL then the
      while loop exits. The short-term workaround (which I admit is
      pretty crude) consist in adding an additional non-null element
      to the results array when all the column values are NULL. This
      workaround is enabled by defining UNDEF_BUG (which is enabled by
      default in the CONFIG file).
      This bug does NOT show up if you retrieve the columns using
      associative arrays instead of normal arrays.

   3) Type: perl Makefile.PL
      If you are building against a vanilla (unpatched) Perl5.001
      release you will get the following warning:
	  'dist is not a known MakeMaker parameter name.
      This can safely be ignored.
      
   4) Type: make
      Again, if you are building against a vanilla Perl5.001 release
      you will get a couple of redefinition warnings:
	  Subroutine mkbootstrap redefined at Makefile.PL line 4
	  Subroutine mksymlists redefined at Makefile.PL line 4
      This can be ignored.

   6) Edit PWD
      Enter the user id and password that you want to use to run the
      tests. It's probably a good idea to reset this file to its
      original state once you're done, unless you really don't have
      any security concerns!
      
   6) Type: make test
      If you decided to use static loading then a new perl binary will
      be generated at this point.
      
   7) If everything went OK, type: make install
      Note that the man page does not get installed automatically. To
      install the documentation, cd to the pod directory, and read the
      README file there.
      Also note that even if you've asked for static linking and a
      perl binary has been built in the sybperl source directory, no
      perl binary gets installed (see step 8).

   8) If the LINKTYPE is static type:

	 make inst_perl MAP_TARGET=perl

      to install the new Perl binary. This step is not required when
      using dynamic linking as the existing Perl binary will load the
      new code dynamically when required.


In case of problems:
====================

First, read the FAQ file in the sybperl distribution.

Second, fire off an e-mail to me (mpeppler@itf.ch) or to the Sybperl
mailing list (sybperl-list@itf.ch) with a *full* description of what
doesn't work, including version numbers of Perl and sybperl, the
hardware and OS version, and the Sybase Open Client version you are
using.


The regression tests don't attempt to test *everything*, but they do
test all of the basic functions, and should work cleanly.

There are quite a few small example scripts in eg/ which illustrate
the use of both the DBlib and CTlib modules.

Documentation (in the pod/ directory) has grown to something which I
hope is better, though I agree that it could still be improved quite a
bit.

There is a mailing list for discussing sybperl related questions
(sybperl-list@itf.ch). Send a message to sybperl-list-request@itf.ch
with the word 'subscribe' in the body to subscribe to the list.



Reporting Bugs:
===============

I have set up a bug tracking database at ITF, to which bugs can be
submitted via e-mail. If you have a comment, bug report or feature
request you would like to make please use the template in the SPR file
in this directory.

When submitting bugs, or any sort of problem report, please make sure
you include full version information for Sybperl, Perl, Sybase and
also what hardware/OS configuration you are on. The exact Sybperl
versions can be extracted by running the 'Version' script in this
directory. Perl's configuration can be summarized with the 'myconfig'
script in the Perl source directory.


Comments, criticism, et.al. VERY welcome!

Michael Peppler - mpeppler@itf.ch	Phone: +4122 818 3021
ITF Management SA			Fax:   +4122 312 1325

