Subject: new Postgres95 module
From: Vivek Khera <[email-masked]>
Date: 21 Oct 1996 15:23:12 GMT
Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc

I got tired of writing C-like code in my Perl programs using the Pg package,
so I wrote a new and improved interface that is more Perl-like.  It is loosely
based on the way the MsqlPerl module works, so it should make for easy porting
of those programs (which is also one of the reasons I wrote this...)

Below is the documentation for the module as generated by pod2text.

To fetch your very own copy, get the file

  ftp://ftp.kciLink.com/pub/PostgresPerl-1.1.tar.gz

unpack it, then run "perl Makefile.PL; make".

To test it, set the environment variable PGHOST to the host of the server
running postgres (if other than the machine which you are on) and then "make
test".  Then all that's necessary is a make install and you've got yourself a
nice perl interface to Postgres95!  It does, however, require Perl 5.003
(though 5.002 *might* work -- I don't know).

Please let me know of any problems with the code or any improvements you may
have or like to have.

Once the portability issues are ironed out (if there are any) I'd like to
donate this to the Postgres95 project for inclusion in the next release.

								v.

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

NAME
    Postgres - Perl interface to the Postgres95 SQL database engine

SYNOPSIS
     use Postgres;

     $conn = db_connect($database,$host,$port)
       or die "could not connect -- $Postgres::error";

     print "Connected Database: ", $conn->db();
     print "Connected Host: ", $conn->host();
     print "Connection Options: ", $conn->options();
     print "Connected Port: ", $conn->port();
     print "Connected tty: ", $conn->tty();
     print "Connection Error Message: ", $conn->errorMessage();

    This method is identical to PQreset(conn)

     $conn->reset();

    This method executes an SQL statement or query.

     $query = $conn->execute($sql_statement)
       or die "Error -- $Postgres::error";

    Retrieve the values from a SELECT query.

     @array = $query->fetchrow();

    Get information from the results of the last query.

     $val = $query->cmdStatus();
     $val = $query->oidStatus();

    Calling the following functions on a result handle that is not from a
    SELECT is undefined.

     $val = $query->ntuples();
     $val = $query->nfields();
     $val = $query->fname($column_index);
     $val = $query->fnumber($column_name);
     $val = $query->ftype($column_index);
     $val = $query->fsize($column_index);

    These functions are provided for completeness but are not intented to be
    used. The fetchrow() method will return `undef' for a field which is
    null.

     $val = $query->getvalue($tuple_index,$column_index);
     $val = $query->getlength($tuple_index,$column_index);
     $val = $query->getisnull($tuple_index,$column_index);

DESCRIPTION
    This package is designed as close as possible to its C API counterpart.
    The C Programmer Guide that comes with Postgres describes most things
    you need.

    The following functions are currently not implemented: PQputline(),
    PQgetline(), PQendcopy(), PQtrace(), PQendtrace(), and the asynchronous
    notification. I do not believe that binary cursors will work, either.

    Once you db_connect() to a database, you can then issue commands to the
    execute() method. If either of them returns an error from the underlying
    API, the value returned will be `undef' and the variable
    `$Postgres::error' will contain the error message from the database. The
    `$port' parameter to db_connect() is optional and will use the default
    port if not specified. All environment variables used by the PQsetdb()
    function are honored.

    The method fetchrow() returns an array of the values from the next row
    fetched from the server. It returns an empty list when there is no more
    data available. Fields which have a NULL value return `undef' as their
    value in the array. Calling fetchrow() or the other tuple-related
    functions on a statement handle which is not from a SELECT statement has
    undefined behavior, and may well crash your program. Other functions
    work identically to their similarly-named C API functions.

  No finish or clear statements

    Whenever the scalar that holds the statement or connection handle loses
    its value, the underlying data structures will be freed and appropriate
    connections closed. This can be accomplished by performing one of these
    actions:

    undef the handle
    use the handle for another purpose
    let the handle run out of scope
    exit the program.

  Error messages

    A global variable `$Postgres::error' always holds the last error
    message. It is never reset except on the next error. The only time it
    holds a valid message is after execute() or db_connect() returns
    `undef'.

PREREQUISITES
    You need to have the Postgres95 database server installed and configured
    on your system to use this module.

    Be sure to set the proper directory locations in the `Makefile.PL' file
    for your installation.

AUTHOR
    Vivek Khera ([email-masked]'). Many ideas were taken from the MsqlPerl
    module.

-- 
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
Vivek Khera, Ph.D.                        Khera Communications, Inc.
Internet: [email-masked]               Rockville, MD       +1-301-258-8292
PGP/MIME spoken here                      http://www.kciLink.com/home/khera/