Path: news.cs.hut.fi!news.csc.fi!news.eunet.fi!EU.net!newsfeed.internetmci.com!uunet!news-in2.uu.net!news.structured.net!crusty.teleport.com!nntp0.teleport.com!usenet From: Vivek Khera Newsgroups: comp.lang.perl.announce,comp.lang.perl.misc Subject: new Postgres95 module Followup-To: comp.lang.perl.misc Date: 21 Oct 1996 15:23:12 GMT Organization: Khera Communications, Inc., Rockville, MD Lines: 153 Approved: merlyn@stonehenge.com (comp.lang.perl.announce) Message-ID: <54g4h0$gfi@nadine.teleport.com> NNTP-Posting-Host: gadget.cscaper.com X-Disclaimer: The "Approved" header verifies header information for article transmission and does not imply approval of content. Xref: news.cs.hut.fi comp.lang.perl.announce:460 comp.lang.perl.misc:50618 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 (`vivek@khera.org'). Many ideas were taken from the MsqlPerl module. -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Vivek Khera, Ph.D. Khera Communications, Inc. Internet: khera@kciLink.com Rockville, MD +1-301-258-8292 PGP/MIME spoken here http://www.kciLink.com/home/khera/ .