#-------------------------------------------------------
#
# $Id: README,v 1.4 1995/07/01 20:39:02 li00357 Exp li00357 $
#
#-------------------------------------------------------

DESCRIPTION:
------------

This is version 1.1 of pg95perl5.

Pg95perl5 is an interface between Larry Wall's language perl version 5 and the
database Postgres95. This has been done by using the Perl 5 application program-
ming interface for C extensions which calls the Postgres programmer's interface
LIBQ.

Pg95perl5 is based on the pgperl package from Igor Metz and Robert Withrow.
Because the perl interface changed, this interface has been rewritten
following the guidelines from the perlapi manpage. Also the test script
has been adapted to SQL, which has replaced the query language POSTQUEL.


CHANGES:
--------

1.1:

Bug fix in PQgetline.


FILES:
------

The pg95perl5 distribution contains the following files:

 o Makefile.PL
 o Pg.pm
 o Pg.xs
 o README
 o testlibpq.out
 o testlibpq.pl
 o typemap


REQUIREMENTS:
-------------

  - perl5.001e
  - Postgres95


PLATFORMS:
----------

  pg95perl5 has been developed using Linux 1.2.8-ELF with dynamic loading
  for the perl extensions. It also works using static loading.
  Let me know, if there are any problems with other platforms.


NOTE:
-----

Please send comments and bug reports to <emergl@mail.bawue.de>

or to

Edmund Mergl
Im Haldenhau 9
D 70565 Stuttgart
fax: +49=711-742857


INSTALLATION:
-------------

Using dynamic loading for perl extensions, the preferred method is to unpack
the tar file outside the perl source tree. This assumes, that you already
have installed perl5.001 ( patchlevel e or higher ).

Make sure, that the locations of the postgres include-files and the libpq-
library in Makefile.PL are correct. If you have only a static version of
libpq change in Makefile.PL libpq.so.1 into libpq.a.  Then
 
   perl Makefile.PL
   make
   make install


If you choose static loading, the contents of this package is assumed to be
in the subdirectory ext/Pg in the perl source tree.

Build perl5 as described in the README of perl:
 - when running Configure, add Pg to the list of static extensions.
 - run make depend, make, make install.


TESTING:
--------

Run testlibpq.pl, which has been taken from the original pgperl distribution.
The file testlibpq.out contains the results of running testlibpq.pl, so
your results should look something like this...


GUIDELINES:
-----------

The file testlibpq.pl should be read to see, how this interface can be used.
Also take a look on Pg.pm which contains one additional user-function.

All the interface-functions are documented in the LIBPQ-section of the Postgres
Reference Manual. There are two exceptions, where the parameters of a function
have been changed:

        original C-function                    pg95perl5 interface
        -------------------                    -------------------

void PQpnames(char **pnames, int rule_p)   @pnames = PQpnames($rule_p)

int  PQgetline(char *string, int length)  ($ret, $string) = PQgetline($length)

This has been done, because perl allows only scalars to be returned as
argument.


TODO:
-----

The LIBPQ-interface of Postgres has some internal global variables which can
be accessed by the programmer. Because the section 'Magic' in the perlguts
manpage is still under construction, in this release of pg95perl5, these global
variables can only be accessed using a functional interface.
Example: in your perl script instead of using:       print $PQhost;
                                        use  :       print PQhost();

In a future release of pg95perl5 this will be fixed.


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

   Edmund Mergl                                       June 10, 1995

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