		  SYBPERL Frequently Asked Questions

		  @(#)FAQ	1.7	1/3/96

NOTE: This FAQ is still very much under construction!!!

Contents:
1)   Sybperl? What is that?
1.1) What is Sybperl?
1.2) Where can I get Sybperl?
1.3) Can I get Sybperl for Windows/NT?
1.4) Can I get Sybperl for OS 'foo'?
1.5) Is there a version of Sybperl for Perl 5?

2)   Building & Installing
2.1) Where is uperl.o?
2.2) make test doesn't work
2.3) How to get Dynamic Linking under HP-UX?
2.4) How do I set PERL_SRC?
2.5) I've moved the Sybase libraries, and Sybperl won't run...
2.6) Sybperl won't run as a CGI script

3)   Sybperl 1.x vs Sybperl 2.x
3.1) Are Sybperl 1.x scripts compatible with 2.x?
3.2) Is Sybperl 2.x stable enough to use, or should I use 1.x for
     production code?
     
4)   Documentation
4.1) Is there any good sybperl documentation?
4.2) Is there a sybperl FAQ?
4.3) Is there a sybperl mailing list?

5)   Improving sybperl
5.1) Reporting bugs
5.2) Feature requests



1)   Sybperl? What is that?

1.1) What is Sybperl?

   Matthew Healy wrote this in a recent comp.databases.sybase post:
   
   Perl is an interpreted programming language discussed in
   comp.lang.perl.* newsgroups; though it's interpreted, the
   interpreter has an internal compiler built-in, so medium-size
   programs still run quite efficiently.

   It has become very popular among people who database and/or system
   administration type work for several reasons:

   o Very powerful and flexible string-manipulation facilities;
     anything you can do with awk, grep, sed, etc. can be done in
     Perl -- and it even comes with utilities that convert scripts
     in those languages into Perl!

   o No arbitrary limits on the size of any object; you can slurp
     up an entire file into a string variable if you have enough
     RAM.

   o An incredibly useful feature called associative arrays, which
     often gives you a quick and easy way of doing things that
     would otherwise require going back to your data structures
     textbooks.

   o Versions are available for nearly every platform you've ever
     heard of.

   o It's FREE!

   Sybperl is a package of extensions to Perl that basically add the
   Sybase db_library API calls to the Perl language; the combination
   is an extremely powerful scripting tool for Sybase DBA's and
   programmers because it adds the existing strengths of Perl to the
   Sybase API.

   So, when would you use it?  Anytime the combination of shell
   scripts with isql is too limited but writing a C program is
   overkill.

   In particular, since Perl has become the language of choice for
   many WWW gurus, Sybperl has become the tool of choice for
   integrating Sybase databases with the Web.  And there are now some
   toolkits written in Sybperl that make it even simpler; my favorite
   among those is WDB.

   Here are some URLs to check out:

   http://www.sybase.com/WWW/sybase_www_faq.html
   http://www.sybase.com/WWW/
   http://www.sybase.com/WWW/sybase_www_tools.html
   http://www.sybase.com/WWW/Sybperl/index.html
   http://arch-http.hq.eso.org/bfrasmus/wdb/wdb.html
   http://arch-http.hq.eso.org/bfrasmus/wdb/distribution/install.html
   ftp://ftp.demon.co.uk/pub/perl/db/perl4/sybperl/
   ftp://ftp.demon.co.uk/pub/perl/db/mod/Sybase/
   ftp://ftp.cis.ufl.edu/pub/perl/
   ftp://ftp.perl.com/

1.2) Where can I get Sybperl?

   Sybperl is available from CPAN (the Comprehensive Perl Archive Network)

   The CPAN master is at
       ftp://ftp.funet.fi/pub/languages/perl/CPAN

   and Sybperl is archived in
       "CPAN"/authors/id/MEWP/sybperl-2.0.tar.gz

   CPAN is mirrored widely, please select the CPAN site nearest you to
   keep the networks happy. At the moment the registered CPAN sites are:

	Africa

	ftp://ftp.is.co.za/programming/perl/CPAN/

	Australasia

	ftp://coombs.anu.edu.au/pub/perl/
	ftp://ftp.mame.mu.oz.au/pub/perl/CPAN/

	Europe

	ftp://ftp.funet.fi/pub/languages/perl/CPAN/
	ftp://ftp.sunet.se/pub/lang/perl/CPAN/
	ftp://ftp.cs.ruu.nl/pub/PERL/CPAN/
	ftp://ftp.demon.co.uk/pub/mirrors/perl/CPAN/
	ftp://ftp.pasteur.fr/pub/computing/unix/perl/CPAN/
	ftp://ftp.rz.ruhr-uni-bochum.de/pub/programming/languages/perl/CPAN/
	ftp://ftp.switch.ch/mirror/CPAN/
	ftp://orpheu.ci.uminho.pt/pub/lang/perl/

	North America

	ftp://ftp.cis.ufl.edu/pub/perl/CPAN/
	ftp://uiarchive.cso.uiuc.edu/pub/lang/perl/CPAN/
	ftp://ftp.delphi.com/pub/mirrors/packages/perl/CPAN/
	ftp://ftp.sedl.org/pub/mirrors/CPAN/
	ftp://ftp.sterling.com/programming/languages/perl/
   
   Version 2.x is also available on Sybase's Web page:
   http://www.sybase.com/WWW/Sybperl/index.html. I try to make sure
   that the Sybase Web page is up to date, but I don't control it...

1.3) Can I get Sybperl for Windows/NT?

   Perl is available for Windows/NT from
   ftp://ntperl.hip.com. However, certain key components that are used
   to add modules to Perl are missing in the current version, which
   makes things difficult for us Sybperl users.

   However, I *know* that it is possible to get Sybperl to work under
   Windows/NT (I would venture to guess that most of the work is in
   creating appropriate Makefiles).

   Contact me if you are interested in attempting this.
   
1.4) Can I get Sybperl for OS 'foo'?

   Perl is primarily a Unix tool, and Sybperl was developped under
   SunOS. However, Perl has been ported to numerous other OSes
   (MS-DOS, Windows/NT, OS/2, VMS), and Sybperl should theortically be
   portable to these OSes as well, in particular with Perl 5's better
   extension mechanism.

   I am always ready to provide any help I can to anyone wishing to
   port Sybperl to any particular OS/platform.

1.5) Is there a version of Sybperl for Perl 5?

   Yes. Sybperl 2.x works only with Perl 5.
   
   Sybperl 1.x does *not* work with Perl 5, as the Perl extension mechanism
   was changed with Perl 5.

   
2) Building Sybperl

2.1) Where is uperl.o (1.x)?

   uperl.o is the object file that sybperl 1.x needs to be linked with
   to give it access to all the Perl routines. uperl.o is normally
   created when you build perl 4.036, but if you have run make clean
   since building, you can recreate it by running 'make uperl.o'.

   If you have Perl 5.x you need sybperl 2.x.

2.2) make test doesn't work

   a) The 'interfaces' file is not visible.
      The Sybase libraries need access to a file that contain
      information on how to connect to the server. This file is
      normally located at the root of the Sybase installation
      directory, and the Sybase libraries and programs normally use
      the SYBASE environement variable to find this directory (ie
      sybperl will try to find $SYBASE/interfaces in order to run).

   b) The userid/password combination is invalid.
      Edit the PWD file to add a valid userid/password combination for
      accessing your database server.

   c) The $SYBASE environment variable is incorrectly set. The
      Sybase::CTlib modules needs access to it's 'locale' information
      in the $SYBASE/locales directory.
   
2.3) How to get Dynamic Linking under HP-UX?

   The bundled C compiler that comes with HP-UX apparently can't
   produce position independant code, which is needed to build a
   dynamically loadable library under HP-UX. The solution there is to
   use the add-on ANSI-C compiler or GCC.

   In addition, you can't build a dynamically loadable module of
   DBlibrary v. 4.x, because it is a statically linked library, and
   was not compiled using the position independent code flag.

   So the end result is: to get a dynamically loadable version you
   need the Sybase System 10 OpenClient libraries, and a C compiler
   that is capable of producing position independent code.

2.4) How do I set PERL_SRC?

   This problem sometimes appears when building sybperl with a copy of
   Perl that has not been installed (ie from the source tree):
   
   You've run

   prompt> perl Makefile.PL
   prompt> make

   and the output looked something like this:

   sybperl-2b3% make
   Rebuilding CTlib/Makefile ...
   /home/mpeppler/PERL/perl5.001/miniperl -I//home/mpeppler/PERL/perl5.001/lib \
   -e "use ExtUtils::MakeMaker; MM->runsubdirpl(qw(CTlib))" \
        INST_LIB=/home/mpeppler/PERL/perl5.001/lib INST_ARCHLIB=/home/mpeppler/PERL/perl5.001/lib \
        INST_EXE=./blib LINKTYPE=dynamic LIBPERL_A=libperl.a 
	Unable to locate Perl source. Try setting PERL_SRC in Makefile.PL or on command line.
	make: *** [CTlib/Makefile] Error 2

   To do this, you need to add a parameter to the WriteMakefile() call
   in each of the Makefile.PLs (toplevel, DBlib/Makefile.PL,
   CTlib/Makefile.PL and Sybperl/Makefile.PL). The parameter should
   look like this
   WriteMakefile(DISTNAME => "sybperl",
                 .... other parameters,
		 PERL_SRC => "/home/mpeppler/src/perl5.001",
		 ...);
   obviously replacing "/home/mpeppler/src/perl5.001" with the
   appropriate directory on your system.


2.5) I've moved the Sybase libraries, and Sybperl won't run...

   The sybperl make process hard-codes the path to the Sybase shared
   libraries (libsybdb.so and friends) into the binaries (either the
   dynamically loadable modules, or the Perl executable). This is done
   so that Perl can find the libraries it needs even if the
   LD_LIBRARY_PATH environment variable which is normally used to
   specify special library directories is not set (as when running a
   script from cron, for example).

   This technique obviously fails when the paths to the Sybase
   libraries are changed (through an upgrade, or when moving the
   binaries to another machine with a different configuration).

   The solution is to:

       - Set LD_LIBRARY_PATH to include the Sybase library directories
       or
       - Link the Sybase libraries to a standard directory (such as
       /usr/lib or /usr/local/lib) which will be searched by default.

2.6) Sybperl won't run as a CGI script

   Typical symptoms: your script runs from the command line, but fails
   when run as a CGI script.

   The problem is (probably) that you normally have LD_LIBRARY_PATH
   set when running Sybperl scripts, but the HTTP deamon does not
   normally set this environment variable when executing child
   processes. It is not possible to set the LD_LIBRARY_PATH
   environment variable in the script itself (the variable needs to be
   set before the execution starts), so you may need to write a small
   shell wrapper that sets this environment variable and then execs
   your script.

   Alternatively, link the Sybase shared libraries to one of the
   'default' directories (such as /usr/lib').

   
3)   Sybperl 1.x vs Sybperl 2.x

3.1) Are sybperl 1.x scripts compatible with 2.x?

   Yes. With these exceptions:

   @var means different things to Perl and to Transact-SQL. If you use
   @var as SQL code (typically: "declare @var int exec my_proc @var
   out") you need to escape the @ (as in \@var).

   If you were in the habit of making calls to the sybperl 1.x subs
   without parens (ie &dbnextrow; instead of &dbnextrow()) then there
   are certain situations where the dbnextrow implementation in
   sybperl 2.x may try to use an invalid DBPROCESS pointer. This
   problem does not exist if your scripts always pass explicit
   DBPROCESS parameters.

   Here at ITF I've linked /usr/local/bin/perl to
   /usr/local/bin/sybperl and all my old sybperl scripts work,
   provided that they had a "require 'sybperl.pl';" at the top.

3.2) Is sybperl 2.x stable enough to use, or should I use 1.x for
   production code?

   Sybperl 2.x is composed of three modules: Sybase::DBlib,
   Sybase::CTlib and Sybase::Sybperl. The DBlib and Sybperl modules
   are stable, and I recommend their use in production code (as I've
   been doing here for over a year now).

   The Sybase::CTlib module is in "beta", and the API may be slightly
   modified in the future. In addition to that, I've noticed a
   performance problem with the CTlib module which appears to make it
   quite a bit slower than the DBlib module for equivalent code. This
   is something that I still need to investigate.

   The advantage (if one can call it that) of staying with sybperl 1.x
   is that the code is frozen - both for sybperl itself and for
   perl. This means that any bugs that you code around will not come
   back to bite you as you upgrade from one release to the other.

   
4)  Documentation
   
4.1) Is there any good sybperl documentation?

   There is a Sybperl man page (in the current release it comes out to
   13 PostScript pages), but that is definitely *not* sufficient in
   itself.

   You need *Perl* documentation (there are over 370 pages of
   documentation in the standard Perl 5 release...).
   There are several good Perl books (in particular 'Programming
   Perl', Larry Wall & Randal Schwartz, O'Reilly and 'Learning Perl',
   Randal Schwartz, O'Reilly)

   And you need *Sybase* documentation, in particular the Sybase
   OpenClient/C manual (I've got mine online via the Sybooks CD-ROM)
   and the Sybase Transact-SQL manual.

4.2) Is there a sybperl FAQ?

   Yes - you're reading it :-)
   But, more importantly, you should get the Perl FAQ, which is posted
   monthly in comp.lang.perl.announce, and which can be ftp'd from
   ftp://ftp.cis.ufl.edu/pub/perl/doc/FAQ.

   And you need the Sybase FAQ, too.

4.3) Is there a sybperl mailing list?

   Yes. The lists address is sybperl-l@trln.lib.unc.edu (it was moved
   recently from sybperl-list@itf.ch due to the high cost of
   supporting the list for my company).

   Send a message to sybperl-l-REQUEST@trln.lib.unc.edu with

	add "your name" <your@email.address>

   to subscribe.

   
5) Improving sybperl...

5.1) Reporting bugs

   I have a simple bug tracking database here at ITF. You can submit
   bugs for sybperl either to myself, or directly into the bug
   database by sending an e-mail message to bugtrack@itf.ch with the
   following additional fields:

   bug-category: sybperl
   bug-priority: high [or medium, or low]
   bug-type: bug [or feature, or change (for behavior change) or
						      other]
   bug-summary: One line description

   The remainder of the message can be used to describe the bug or
   feature request in detail, with examples, etc.
   
   
5.2) Feature requests

   If you have any suggestions regarding how sybperl can be improved,
   please send them to me - I am always happy to try to add features
   :-)

   
Michael
--
Michael Peppler, ITF Management SA, Fontaine 13, CH-1204 Geneva
mpeppler@itf.ch - Tel (4122) 818 3021 - Fax (4122) 312 1325
GCS d+(-) s++: a C++ US++++$ P+++$ E++ W? N++ !w tv- b+++ G e+++ h---
r+++ y?

