@(#)README 1.21 1/31/96 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. Please read the CHANGES file if you are upgrading from a previous version of sybperl 2.x. This version requires Perl 5.001m, and works fine with 5.002. 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.001m (or later) already installed at your site? If Perl 5.001m (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 the Perl 5.001m (or later) is not yet the default version of Perl, then you should unpack the sybperl distribution in the ext/ directory of the Perl 5.001m (or 5.002) 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.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.) 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 rto 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! 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. 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 (mpeppler@itf.ch) or to the Sybperl mailing list (sybperl-l@trln.lib.unc.edu) 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 (sybperl-l@trln.lib.unc.edu). Send a message to sybperl-l-request@trln.lib.unc.edu with 'subscribe your name' 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 1322