@(#)README 1.24    01/19/97

                          sybperl 2.0

         This is sybperl, the Sybase extensions for Perl5.

             Copyright (c) 1991-1997,  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.

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

** NOTE: This version requires Perl 5.002 **


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

Please read the CHANGES file if you are upgrading from a previous
version of sybperl 2.x.

There are four modules in this distribution: Sybase::DBlib,
Sybase::BCP, 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.
Sybase::BCP is a simplified bulk copy API, and requires Sybase::DBlib.
The Sybase::Sybperl module implements the sybperl 1.0xx API, and is
built on top of Sybase::DBlib.

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.002 (or later) already installed at your site?

  If Perl 5.002 (or later) 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 if 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 5.002 (or later) is not yet the default version of Perl, or has
  not been made available via an alternate path, then you should
  unpack the sybperl distribution in the ext/ directory of the Perl
  5.002 source tree. NOTE: this method is not well tested, and you
  may run into problems (unfortunately).

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.so.1.0).

  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.

c) The DO_TIE compile option

  The Sybase::DBlib and Sybase::CTlib modules define a number of
  attributes that are accesible via the database handle:

      $dbh = new Sybase::CTlib $user, $passwd...
      $dbh->{UseDateTime} = CS_TRUE;

  When the DO_TIE compile option is set, these attributes get 'tied'
  into a special package, thus enabling syntax verification, so that
  errors like

      $dbh->{UseDateTIme}

  will be caught.

  The downside is that you won't be able to add your own attributes
  to the $dbh on the fly. You must pre-declare any additional
  attributes you wish to use by passing them as a hash reference in
  the new()/dblogin()/ct_connect() calls (see the documentation and
  the Sybase::BCP module for examples). The DO_TIE option is set via
  the EXTRA_DEFINES option of the CONFIG file, and is enabled by
  default.

d) The -L/usr/local/lib switch and libtcl.{a, so, sl}

  Perl's Configure script adds this switch to the normal link or load
  line used when building extensions. This is fine, but if you have
  installed tcl/tk at your site, there is a strong chance that tcl's
  libtcl.a library has been placed in /usr/local/lib. Sybase's Client
  Library also includes a library called libtcl.{a,so,sl}. If the
  -L/usr/local/lib switch is present on the link command line then
  the wrong version of libtcl will be used, and the Sybase::CTlib
  module will not work. The solution is to either move or rename
  tcl/tk's libtcl.a while you build sybperl, or to remove the
  -L/usr/local/lib flag from Perl's Config.pm file.

Once you have answered these four 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.002 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.002
     under /usr/local/{bin,lib} and a debug version of Perl5.002
     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.
     Some systems require extra libraries to build (Solaris 2.x
     requires -lnsl, for example). You should check your Sybase
     OpenClient Supplement for your OS and add any special libraries
     to the EXTRA_LIBS line. The required information can be found on
     the web at http://cobweb.sybase.com:8000/con10022/tctsg (you'll
     need to dig around a bit, though), or via AnswerBase.

     The DBLIBVS and CTLIBVS variables need to be set correctly for
     the version of OpenClient that is available at your site. Below
     is a table which lists which versions of Open Client were
     shipped with the different Sybase Server releases:

     Sybase version               DBLIBVS   CTLIBVS
     - 4.0                            400         0
     - 4.2 (includes MSSQL 4.2)       420         0
     - 4.8, 4.9.x                     461         0
     - 10.0.x                        1000       100

     You can check for the DB-Library version by looking at the top
     of the sybdb.h include file (it should be located in
     $SYBASE/include/sybdb.h, where $SYBASE is your Sybase
     installation directory.)

     Determine if you need any additional #define's for the
     EXTRA_DEFS line: With Perl 5.001m you needed -DUNDEF_BUG, but
     this bug has been corrected in 5.002, and you can also add
     -DDO_TIE to get the stricter attribute checking behavior (see
     point c. above).

     Uncomment the LINKTYPE line if required (see point b. above).

  3) Type: perl Makefile.PL

  4) Type: make

     If you get errors (such as undefined variables) it may be
     because your DBLIBVS or CTLIBVS does not correspond to the Open
     Client versions that are in fact installed at your site. Check
     them again. In the case of the Sybase::DBlib module, it doesn't
     hurt to build with DBLIBVS set to 400 as this is pretty well
     guarateed to work (provided you have *some* version of
     DB-Library!)

  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!

     The tests are non-destructive (ie only SELECT statements),
     except for Sybase::BCP which creates a temp table (#bcp) to test
     the bulk copy features.

  6) Type: make test
     If you decided to use static loading then a new perl binary will
     be generated at this point.

     If you get undefined symbols when testing CTlib (such as _net_*
     or _intl_getenv not defined), then I'd bet that you have either
     a libtcl.* or libintl.* in /usr/local/lib.  See point d) above.

  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.

  9) Read the manual :-)

     Look for it in the pod/ directory. You can create .man or .html
     versions from the .pod file by using pod2man or pod2html, both
     of which come with Perl.
     The manual may not be perfect yet, but it comes to 16 PostScript
     pages here, which is "respectable", I guess.


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

First, read the FAQ file in the sybperl distribution.

Second, fire off an e-mail to me ([email protected]) or to the Sybperl
mailing list ([email protected]) 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.

There is a mailing list for discussing sybperl related questions
([email protected]). Send a message to
[email protected] with 'subscribe your name'
in the body to subscribe to the list.



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

I have set up a bug tracking database 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 - [email protected]

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.