1997-04-29 21:37:10 +02:00
|
|
|
#-------------------------------------------------------
|
|
|
|
#
|
1998-09-27 21:12:35 +02:00
|
|
|
# $Id: Pg.pm,v 1.8 1998/09/27 19:12:22 mergl Exp $
|
1997-04-29 21:37:10 +02:00
|
|
|
#
|
1998-06-01 18:41:27 +02:00
|
|
|
# Copyright (c) 1997, 1998 Edmund Mergl
|
1997-04-29 21:37:10 +02:00
|
|
|
#
|
|
|
|
#-------------------------------------------------------
|
|
|
|
|
|
|
|
package Pg;
|
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
#use strict;
|
1997-04-29 21:37:10 +02:00
|
|
|
use Carp;
|
|
|
|
use vars qw($VERSION @ISA @EXPORT $AUTOLOAD);
|
|
|
|
|
|
|
|
require Exporter;
|
|
|
|
require DynaLoader;
|
|
|
|
require AutoLoader;
|
1997-09-17 22:46:29 +02:00
|
|
|
require 5.002;
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
@ISA = qw(Exporter DynaLoader);
|
|
|
|
|
|
|
|
# Items to export into callers namespace by default.
|
|
|
|
@EXPORT = qw(
|
|
|
|
PQconnectdb
|
1998-09-27 21:12:35 +02:00
|
|
|
PQsetdbLogin
|
1997-04-29 21:37:10 +02:00
|
|
|
PQsetdb
|
1998-09-27 21:12:35 +02:00
|
|
|
PQconndefaults
|
1997-04-29 21:37:10 +02:00
|
|
|
PQfinish
|
|
|
|
PQreset
|
1998-09-27 21:12:35 +02:00
|
|
|
PQrequestCancel
|
1997-04-29 21:37:10 +02:00
|
|
|
PQdb
|
|
|
|
PQuser
|
1998-09-27 21:12:35 +02:00
|
|
|
PQpass
|
1997-04-29 21:37:10 +02:00
|
|
|
PQhost
|
|
|
|
PQport
|
|
|
|
PQtty
|
1998-09-27 21:12:35 +02:00
|
|
|
PQoptions
|
1997-04-29 21:37:10 +02:00
|
|
|
PQstatus
|
|
|
|
PQerrorMessage
|
1998-09-27 21:12:35 +02:00
|
|
|
PQsocket
|
|
|
|
PQbackendPID
|
1997-04-29 21:37:10 +02:00
|
|
|
PQtrace
|
|
|
|
PQuntrace
|
|
|
|
PQexec
|
1998-09-27 21:12:35 +02:00
|
|
|
PQnotifies
|
|
|
|
PQsendQuery
|
|
|
|
PQgetResult
|
|
|
|
PQisBusy
|
|
|
|
PQconsumeInput
|
1997-04-29 21:37:10 +02:00
|
|
|
PQgetline
|
|
|
|
PQputline
|
1998-09-27 21:12:35 +02:00
|
|
|
PQgetlineAsync
|
|
|
|
PQputnbytes
|
|
|
|
PQendcopy
|
|
|
|
PQmakeEmptyPGresult
|
1997-04-29 21:37:10 +02:00
|
|
|
PQresultStatus
|
|
|
|
PQntuples
|
|
|
|
PQnfields
|
1998-09-27 21:12:35 +02:00
|
|
|
PQbinaryTuples
|
1997-04-29 21:37:10 +02:00
|
|
|
PQfname
|
|
|
|
PQfnumber
|
|
|
|
PQftype
|
|
|
|
PQfsize
|
1998-09-27 21:12:35 +02:00
|
|
|
PQfmod
|
1997-04-29 21:37:10 +02:00
|
|
|
PQcmdStatus
|
|
|
|
PQoidStatus
|
1997-09-17 22:46:29 +02:00
|
|
|
PQcmdTuples
|
1997-04-29 21:37:10 +02:00
|
|
|
PQgetvalue
|
|
|
|
PQgetlength
|
|
|
|
PQgetisnull
|
|
|
|
PQclear
|
|
|
|
PQprint
|
1998-09-27 21:12:35 +02:00
|
|
|
PQdisplayTuples
|
|
|
|
PQprintTuples
|
1997-04-29 21:37:10 +02:00
|
|
|
PQlo_open
|
|
|
|
PQlo_close
|
|
|
|
PQlo_read
|
|
|
|
PQlo_write
|
|
|
|
PQlo_lseek
|
|
|
|
PQlo_creat
|
|
|
|
PQlo_tell
|
|
|
|
PQlo_unlink
|
|
|
|
PQlo_import
|
|
|
|
PQlo_export
|
|
|
|
PGRES_CONNECTION_OK
|
|
|
|
PGRES_CONNECTION_BAD
|
|
|
|
PGRES_EMPTY_QUERY
|
|
|
|
PGRES_COMMAND_OK
|
|
|
|
PGRES_TUPLES_OK
|
|
|
|
PGRES_COPY_OUT
|
|
|
|
PGRES_COPY_IN
|
|
|
|
PGRES_BAD_RESPONSE
|
|
|
|
PGRES_NONFATAL_ERROR
|
|
|
|
PGRES_FATAL_ERROR
|
|
|
|
PGRES_INV_SMGRMASK
|
|
|
|
PGRES_INV_ARCHIVE
|
|
|
|
PGRES_INV_WRITE
|
|
|
|
PGRES_INV_READ
|
|
|
|
PGRES_InvalidOid
|
|
|
|
);
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$Pg::VERSION = '1.8.0';
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
sub AUTOLOAD {
|
|
|
|
# This AUTOLOAD is used to 'autoload' constants from the constant()
|
|
|
|
# XS function. If a constant is not found then control is passed
|
|
|
|
# to the AUTOLOAD in AutoLoader.
|
|
|
|
|
|
|
|
my $constname;
|
|
|
|
($constname = $AUTOLOAD) =~ s/.*:://;
|
|
|
|
my $val = constant($constname, @_ ? $_[0] : 0);
|
|
|
|
if ($! != 0) {
|
|
|
|
if ($! =~ /Invalid/) {
|
|
|
|
$AutoLoader::AUTOLOAD = $AUTOLOAD;
|
|
|
|
goto &AutoLoader::AUTOLOAD;
|
|
|
|
}
|
|
|
|
else {
|
|
|
|
croak "Your vendor has not defined Pg macro $constname";
|
|
|
|
}
|
|
|
|
}
|
|
|
|
eval "sub $AUTOLOAD { $val }";
|
|
|
|
goto &$AUTOLOAD;
|
|
|
|
}
|
|
|
|
|
|
|
|
bootstrap Pg $VERSION;
|
|
|
|
|
|
|
|
sub doQuery {
|
|
|
|
|
|
|
|
my $conn = shift;
|
|
|
|
my $query = shift;
|
|
|
|
my $array_ref = shift;
|
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
my ($result, $status, $i, $j);
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
if ($result = $conn->exec($query)) {
|
|
|
|
if (2 == ($status = $result->resultStatus)) {
|
|
|
|
for $i (0..$result->ntuples - 1) {
|
|
|
|
for $j (0..$result->nfields - 1) {
|
|
|
|
$$array_ref[$i][$j] = $result->getvalue($i, $j);
|
|
|
|
}
|
|
|
|
}
|
1997-04-29 21:37:10 +02:00
|
|
|
}
|
|
|
|
}
|
1998-02-20 22:25:47 +01:00
|
|
|
return $status;
|
1997-04-29 21:37:10 +02:00
|
|
|
}
|
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
1;
|
|
|
|
|
|
|
|
__END__
|
|
|
|
|
|
|
|
|
|
|
|
=head1 NAME
|
|
|
|
|
1997-09-17 22:46:29 +02:00
|
|
|
Pg - Perl5 extension for PostgreSQL
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
|
|
|
|
new style:
|
|
|
|
|
|
|
|
use Pg;
|
1998-09-27 21:12:35 +02:00
|
|
|
$conn = Pg::connectdb("dbname=template1");
|
|
|
|
$result = $conn->exec("create database pgtest");
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
old style (depreciated):
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
use Pg;
|
|
|
|
$conn = PQsetdb('', '', '', '', template1);
|
1998-09-27 21:12:35 +02:00
|
|
|
$result = PQexec($conn, "create database pgtest");
|
1997-04-29 21:37:10 +02:00
|
|
|
PQclear($result);
|
|
|
|
PQfinish($conn);
|
|
|
|
|
|
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
|
|
|
|
The Pg module permits you to access all functions of the
|
|
|
|
Libpq interface of PostgreSQL. Libpq is the programmer's
|
|
|
|
interface to PostgreSQL. Pg tries to resemble this
|
|
|
|
interface as close as possible. For examples of how to
|
|
|
|
use this module, look at the file test.pl. For further
|
|
|
|
examples look at the Libpq applications in
|
|
|
|
../src/test/examples and ../src/test/regress.
|
|
|
|
|
|
|
|
You have the choice between the old C-style and a
|
|
|
|
new, more Perl-ish style. The old style has the
|
|
|
|
benefit, that existing Libpq applications can be
|
|
|
|
ported to perl just by prepending every variable
|
|
|
|
with a '$'. The new style uses class packages and
|
|
|
|
might be more familiar for C++-programmers.
|
|
|
|
|
|
|
|
|
|
|
|
=head1 GUIDELINES
|
|
|
|
|
|
|
|
=head2 new style
|
|
|
|
|
|
|
|
The new style uses blessed references as objects.
|
|
|
|
After creating a new connection or result object,
|
|
|
|
the relevant Libpq functions serve as virtual methods.
|
|
|
|
One benefit of the new style: you do not have to care
|
|
|
|
about freeing the connection- and result-structures.
|
|
|
|
Perl calls the destructor whenever the last reference
|
|
|
|
to an object goes away.
|
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
The method fetchrow can be used to fetch the next row from
|
|
|
|
the server: while (@row = $result->fetchrow).
|
|
|
|
Columns which have NULL as value will be set to C<undef>.
|
|
|
|
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
=head2 old style
|
|
|
|
|
|
|
|
All functions and constants are imported into the calling
|
1997-09-17 22:46:29 +02:00
|
|
|
packages name-space. In order to to get a uniform naming,
|
1997-04-29 21:37:10 +02:00
|
|
|
all functions start with 'PQ' (e.g. PQlo_open) and all
|
|
|
|
constants start with 'PGRES_' (e.g. PGRES_CONNECTION_OK).
|
|
|
|
|
|
|
|
There are two functions, which allocate memory, that has
|
|
|
|
to be freed by the user:
|
|
|
|
|
|
|
|
PQsetdb, use PQfinish to free memory.
|
|
|
|
PQexec, use PQclear to free memory.
|
|
|
|
|
|
|
|
Pg.pm contains one convenience function: doQuery. It fills a
|
|
|
|
two-dimensional array with the result of your query. Usage:
|
|
|
|
|
|
|
|
Pg::doQuery($conn, "select attr1, attr2 from tbl", \@ary);
|
|
|
|
|
|
|
|
for $i ( 0 .. $#ary ) {
|
|
|
|
for $j ( 0 .. $#{$ary[$i]} ) {
|
|
|
|
print "$ary[$i][$j]\t";
|
|
|
|
}
|
|
|
|
print "\n";
|
|
|
|
}
|
|
|
|
|
|
|
|
Notice the inner loop !
|
|
|
|
|
|
|
|
|
|
|
|
=head1 CAVEATS
|
|
|
|
|
|
|
|
There are few exceptions, where the perl-functions differs
|
|
|
|
from the C-counterpart: PQprint, PQnotifies and PQconndefaults.
|
|
|
|
These functions deal with structures, which have been
|
|
|
|
implemented in perl using lists or hash.
|
|
|
|
|
|
|
|
|
|
|
|
=head1 FUNCTIONS
|
|
|
|
|
|
|
|
The functions have been divided into three sections:
|
1998-09-27 21:12:35 +02:00
|
|
|
Connection, Result, Large Objects. For details please
|
|
|
|
read L<libpq>.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
|
|
|
|
=head2 1. Connection
|
|
|
|
|
|
|
|
With these functions you can establish and close a connection to a
|
|
|
|
database. In Libpq a connection is represented by a structure called
|
1998-09-27 21:12:35 +02:00
|
|
|
PGconn.
|
|
|
|
|
|
|
|
When opening a connection a given database name is always converted to
|
|
|
|
lower-case, unless it is surrounded by double quotes. All unspecified
|
|
|
|
parameters are replaced by environment variables or by hard coded defaults:
|
|
|
|
|
|
|
|
parameter environment variable hard coded default
|
|
|
|
--------------------------------------------------
|
|
|
|
host PGHOST localhost
|
|
|
|
port PGPORT 5432
|
|
|
|
options PGOPTIONS ""
|
|
|
|
tty PGTTY ""
|
|
|
|
dbname PGDATABASE current userid
|
|
|
|
user PGUSER current userid
|
|
|
|
password PGPASSWORD ""
|
|
|
|
|
|
|
|
Using appropriate methods you can access almost all fields of the
|
|
|
|
returned PGconn structure.
|
|
|
|
|
|
|
|
$conn = Pg::setdbLogin($pghost, $pgport, $pgoptions, $pgtty, $dbname, $login, $pwd)
|
|
|
|
|
|
|
|
Opens a new connection to the backend. The connection identifier $conn
|
|
|
|
( a pointer to the PGconn structure ) must be used in subsequent commands
|
|
|
|
for unique identification. Before using $conn you should call $conn->status
|
|
|
|
to ensure, that the connection was properly made.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$conn = Pg::setdb($pghost, $pgport, $pgoptions, $pgtty, $dbname)
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
The method setdb should be used when username/password authentication is
|
|
|
|
not needed.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-02-20 22:25:47 +01:00
|
|
|
$conn = Pg::connectdb("option1=value option2=value ...")
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Opens a new connection to the backend using connection information in a
|
|
|
|
string. Possible options are: host, port, options, tty, dbname, user, password.
|
|
|
|
The connection identifier $conn (a pointer to the PGconn structure)
|
|
|
|
must be used in subsequent commands for unique identification. Before using
|
|
|
|
$conn you should call $conn->status to ensure, that the connection was
|
|
|
|
properly made.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$Option_ref = Pg::conndefaults()
|
|
|
|
|
|
|
|
while(($key, $val) = each %$Option_ref) {
|
|
|
|
print "$key, $val\n";
|
|
|
|
|
|
|
|
Returns a reference to a hash containing as keys all possible options for
|
|
|
|
connectdb(). The values are the current defaults. This function differs from
|
|
|
|
his C-counterpart, which returns the complete conninfoOption structure.
|
|
|
|
|
|
|
|
PQfinish($conn)
|
|
|
|
|
|
|
|
Old style only !
|
1998-09-27 21:12:35 +02:00
|
|
|
Closes the connection to the backend and frees the connection data structure.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$conn->reset
|
|
|
|
|
|
|
|
Resets the communication port with the backend and tries
|
|
|
|
to establish a new connection.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$ret = $conn->requestCancel
|
|
|
|
|
|
|
|
Abandon processing of the current query. Regardless of the return value of
|
|
|
|
requestCancel, the application must continue with the normal result-reading
|
|
|
|
sequence using getResult. If the current query is part of a transaction,
|
|
|
|
cancellation will abort the whole transaction.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$dbname = $conn->db
|
|
|
|
|
|
|
|
Returns the database name of the connection.
|
|
|
|
|
|
|
|
$pguser = $conn->user
|
|
|
|
|
|
|
|
Returns the Postgres user name of the connection.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$pguser = $conn->pass
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Returns the Postgres password of the connection.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$pghost = $conn->host
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Returns the host name of the connection.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$pgport = $conn->port
|
|
|
|
|
|
|
|
Returns the port of the connection.
|
|
|
|
|
|
|
|
$pgtty = $conn->tty
|
|
|
|
|
|
|
|
Returns the tty of the connection.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$pgoptions = $conn->options
|
|
|
|
|
|
|
|
Returns the options used in the connection.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$status = $conn->status
|
|
|
|
|
|
|
|
Returns the status of the connection. For comparing the status
|
|
|
|
you may use the following constants:
|
|
|
|
|
|
|
|
- PGRES_CONNECTION_OK
|
|
|
|
- PGRES_CONNECTION_BAD
|
|
|
|
|
|
|
|
$errorMessage = $conn->errorMessage
|
|
|
|
|
|
|
|
Returns the last error message associated with this connection.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$fd = $conn->socket
|
|
|
|
|
|
|
|
Obtain the file descriptor number for the backend connection socket.
|
|
|
|
A result of -1 indicates that no backend connection is currently open.
|
|
|
|
|
|
|
|
$pid = $conn->backendPID
|
|
|
|
|
|
|
|
Returns the process-id of the corresponding backend proceess.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$conn->trace(debug_port)
|
|
|
|
|
|
|
|
Messages passed between frontend and backend are echoed to the
|
|
|
|
debug_port file stream.
|
|
|
|
|
|
|
|
$conn->untrace
|
|
|
|
|
|
|
|
Disables tracing.
|
|
|
|
|
|
|
|
$result = $conn->exec($query)
|
|
|
|
|
|
|
|
Submits a query to the backend. The return value is a pointer to
|
|
|
|
the PGresult structure, which contains the complete query-result
|
|
|
|
returned by the backend. In case of failure, the pointer points
|
|
|
|
to an empty structure. In this, the perl implementation differs
|
|
|
|
from the C-implementation. Using the old style, even the empty
|
|
|
|
structure has to be freed using PQfree. Before using $result you
|
|
|
|
should call resultStatus to ensure, that the query was
|
|
|
|
properly executed.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
($table, $pid) = $conn->notifies
|
|
|
|
|
|
|
|
Checks for asynchronous notifications. This functions differs from
|
|
|
|
the C-counterpart which returns a pointer to a new allocated structure,
|
|
|
|
whereas the perl implementation returns a list. $table is the table
|
|
|
|
which has been listened to and $pid is the process id of the backend.
|
|
|
|
|
|
|
|
|
|
|
|
$ret = $conn->sendQuery($string, $query)
|
|
|
|
|
|
|
|
Submit a query to Postgres without waiting for the result(s). After
|
|
|
|
successfully calling PQsendQuery, call PQgetResult one or more times
|
|
|
|
to obtain the query results. PQsendQuery may not be called again until
|
|
|
|
getResult has returned NULL, indicating that the query is done.
|
|
|
|
|
|
|
|
$result = $conn->getResult
|
|
|
|
|
|
|
|
Wait for the next result from a prior PQsendQuery, and return it. NULL
|
|
|
|
is returned when the query is complete and there will be no more results.
|
|
|
|
getResult will block only if a query is active and the necessary response
|
|
|
|
data has not yet been read by PQconsumeInput.
|
|
|
|
|
|
|
|
$ret = $conn->isBusy
|
|
|
|
|
|
|
|
Returns TRUE if a query is busy, that is, PQgetResult would block waiting
|
|
|
|
for input. A FALSE return indicates that PQgetResult can be called with
|
|
|
|
assurance of not blocking.
|
|
|
|
|
|
|
|
$result = $conn->consumeInput
|
|
|
|
|
|
|
|
If input is available from the backend, consume it. After calling consumeInput,
|
|
|
|
the application may check isBusy and/or notifies to see if their state has changed.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$ret = $conn->getline($string, $length)
|
|
|
|
|
|
|
|
Reads a string up to $length - 1 characters from the backend.
|
|
|
|
getline returns EOF at EOF, 0 if the entire line has been read,
|
|
|
|
and 1 if the buffer is full. If a line consists of the two
|
|
|
|
characters "\." the backend has finished sending the results of
|
|
|
|
the copy command.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$ret = $conn->putline($string)
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
Sends a string to the backend. The application must explicitly
|
|
|
|
send the two characters "\." to indicate to the backend that
|
|
|
|
it has finished sending its data.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$ret = $conn->getlineAsync($buffer, $bufsize)
|
|
|
|
|
|
|
|
Non-blocking version of getline. It reads up to $bufsize
|
|
|
|
characters from the backend. getlineAsync returns -1 if
|
|
|
|
the end-of-copy-marker has been recognized, 0 if no data
|
|
|
|
is avilable, and >0 the number of bytes returned.
|
|
|
|
|
|
|
|
$ret = $conn->putnbytes($buffer, $nbytes)
|
|
|
|
|
|
|
|
Sends n bytes to the backend. Returns 0 if OK, EOF if not.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$ret = $conn->endcopy
|
|
|
|
|
|
|
|
This function waits until the backend has finished the copy.
|
|
|
|
It should either be issued when the last string has been sent
|
|
|
|
to the backend using putline or when the last string has
|
|
|
|
been received from the backend using getline. endcopy returns
|
1998-09-27 21:12:35 +02:00
|
|
|
0 on success, 1 on failure.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$result = $conn->makeEmptyPGresult($status);
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Returns a newly allocated, initialized result with given status.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
|
|
|
|
=head2 2. Result
|
|
|
|
|
|
|
|
With these functions you can send commands to a database and
|
|
|
|
investigate the results. In Libpq the result of a command is
|
|
|
|
represented by a structure called PGresult. Using the appropriate
|
|
|
|
methods you can access almost all fields of this structure.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$result_status = $result->resultStatus
|
|
|
|
|
|
|
|
Returns the status of the result. For comparing the status you
|
|
|
|
may use one of the following constants depending upon the
|
|
|
|
command executed:
|
|
|
|
|
|
|
|
- PGRES_EMPTY_QUERY
|
|
|
|
- PGRES_COMMAND_OK
|
|
|
|
- PGRES_TUPLES_OK
|
|
|
|
- PGRES_COPY_OUT
|
|
|
|
- PGRES_COPY_IN
|
|
|
|
- PGRES_BAD_RESPONSE
|
|
|
|
- PGRES_NONFATAL_ERROR
|
|
|
|
- PGRES_FATAL_ERROR
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
Use the functions below to access the contents of the PGresult structure.
|
|
|
|
|
1997-09-17 22:46:29 +02:00
|
|
|
$ntuples = $result->ntuples
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
Returns the number of tuples in the query result.
|
|
|
|
|
|
|
|
$nfields = $result->nfields
|
|
|
|
|
|
|
|
Returns the number of fields in the query result.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$ret = $result->binaryTuples
|
|
|
|
|
|
|
|
Returns 1 if the tuples in the query result are bianry.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$fname = $result->fname($field_num)
|
|
|
|
|
|
|
|
Returns the field name associated with the given field number.
|
|
|
|
|
|
|
|
$fnumber = $result->fnumber($field_name)
|
|
|
|
|
|
|
|
Returns the field number associated with the given field name.
|
|
|
|
|
|
|
|
$ftype = $result->ftype($field_num)
|
|
|
|
|
|
|
|
Returns the oid of the type of the given field number.
|
|
|
|
|
|
|
|
$fsize = $result->fsize($field_num)
|
|
|
|
|
|
|
|
Returns the size in bytes of the type of the given field number.
|
|
|
|
It returns -1 if the field has a variable length.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$fmod = $result->fmod($field_num)
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Returns the type-specific modification data of the field associated
|
|
|
|
with the given field index. Field indices start at 0.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$cmdStatus = $result->cmdStatus
|
|
|
|
|
1997-09-17 22:46:29 +02:00
|
|
|
Returns the command status of the last query command.
|
|
|
|
In case of DELETE it returns also the number of deleted tuples.
|
|
|
|
In case of INSERT it returns also the OID of the inserted
|
|
|
|
tuple followed by 1 (the number of affected tuples).
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$oid = $result->oidStatus
|
|
|
|
|
|
|
|
In case the last query was an INSERT command it returns the oid of the
|
|
|
|
inserted tuple.
|
|
|
|
|
1997-09-17 22:46:29 +02:00
|
|
|
$oid = $result->cmdTuples
|
|
|
|
|
|
|
|
In case the last query was an INSERT or DELETE command it returns the
|
|
|
|
number of affected tuples.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$value = $result->getvalue($tup_num, $field_num)
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Returns the value of the given tuple and field. This is
|
|
|
|
a null-terminated ASCII string. Binary cursors will not
|
|
|
|
work.
|
|
|
|
|
|
|
|
$length = $result->getlength($tup_num, $field_num)
|
|
|
|
|
|
|
|
Returns the length of the value for a given tuple and field.
|
|
|
|
|
|
|
|
$null_status = $result->getisnull($tup_num, $field_num)
|
|
|
|
|
|
|
|
Returns the NULL status for a given tuple and field.
|
|
|
|
|
|
|
|
PQclear($result)
|
|
|
|
|
|
|
|
Old style only !
|
|
|
|
Frees all memory of the given result.
|
|
|
|
|
|
|
|
$res->fetchrow
|
|
|
|
|
|
|
|
New style only !
|
|
|
|
Fetches the next row from the server and returns NULL if all rows
|
|
|
|
have been processed. Columns which have NULL as value will be set to C<undef>.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
$result->print($fout, $header, $align, $standard, $html3, $expanded, $pager, $fieldSep, $tableOpt, $caption, ...)
|
|
|
|
|
|
|
|
Prints out all the tuples in an intelligent manner. This function
|
|
|
|
differs from the C-counterpart. The struct PQprintOpt has been
|
|
|
|
implemented with a list. This list is of variable length, in order
|
|
|
|
to care for the character array fieldName in PQprintOpt.
|
|
|
|
The arguments $header, $align, $standard, $html3, $expanded, $pager
|
|
|
|
are boolean flags. The arguments $fieldSep, $tableOpt, $caption
|
|
|
|
are strings. You may append additional strings, which will be
|
|
|
|
taken as replacement for the field names.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$result->displayTuples($fp, $fillAlign, $fieldSep, $printHeader, qiet)
|
1997-04-29 21:37:10 +02:00
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
Kept for backward compatibility. Use print.
|
|
|
|
|
|
|
|
$result->printTuples($fout, $printAttName, $terseOutput, $width)
|
|
|
|
|
|
|
|
Kept for backward compatibility. Use print.
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
|
|
|
|
=head2 3. Large Objects
|
|
|
|
|
|
|
|
These functions provide file-oriented access to user data.
|
|
|
|
The large object interface is modeled after the Unix file
|
1997-09-17 22:46:29 +02:00
|
|
|
system interface with analogies of open, close, read, write,
|
1997-04-29 21:37:10 +02:00
|
|
|
lseek, tell. In order to get a consistent naming, all function
|
|
|
|
names have been prepended with 'PQ' (old style only).
|
|
|
|
|
|
|
|
$lobj_fd = $conn->lo_open($lobjId, $mode)
|
|
|
|
|
|
|
|
Opens an existing large object and returns an object id.
|
|
|
|
For the mode bits see lo_create. Returns -1 upon failure.
|
|
|
|
|
|
|
|
$ret = $conn->lo_close($lobj_fd)
|
|
|
|
|
|
|
|
Closes an existing large object. Returns 0 upon success
|
|
|
|
and -1 upon failure.
|
|
|
|
|
|
|
|
$nbytes = $conn->lo_read($lobj_fd, $buf, $len)
|
|
|
|
|
|
|
|
Reads $len bytes into $buf from large object $lobj_fd.
|
|
|
|
Returns the number of bytes read and -1 upon failure.
|
|
|
|
|
|
|
|
$nbytes = $conn->lo_write($lobj_fd, $buf, $len)
|
|
|
|
|
|
|
|
Writes $len bytes of $buf into the large object $lobj_fd.
|
|
|
|
Returns the number of bytes written and -1 upon failure.
|
|
|
|
|
|
|
|
$ret = $conn->lo_lseek($lobj_fd, $offset, $whence)
|
|
|
|
|
|
|
|
Change the current read or write location on the large object
|
|
|
|
$obj_id. Currently $whence can only be 0 (L_SET).
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$lobjId = $conn->lo_creat($mode)
|
|
|
|
|
|
|
|
Creates a new large object. $mode is a bit-mask describing
|
|
|
|
different attributes of the new object. Use the following constants:
|
|
|
|
|
|
|
|
- PGRES_INV_SMGRMASK
|
|
|
|
- PGRES_INV_ARCHIVE
|
|
|
|
- PGRES_INV_WRITE
|
|
|
|
- PGRES_INV_READ
|
|
|
|
|
|
|
|
Upon failure it returns PGRES_InvalidOid.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$location = $conn->lo_tell($lobj_fd)
|
|
|
|
|
|
|
|
Returns the current read or write location on the large object
|
|
|
|
$lobj_fd.
|
|
|
|
|
1998-09-27 21:12:35 +02:00
|
|
|
$ret = $conn->lo_unlink($lobjId)
|
|
|
|
|
|
|
|
Deletes a large object. Returns -1 upon failure.
|
|
|
|
|
1997-04-29 21:37:10 +02:00
|
|
|
$lobjId = $conn->lo_import($filename)
|
|
|
|
|
|
|
|
Imports a Unix file as large object and returns
|
|
|
|
the object id of the new object.
|
|
|
|
|
|
|
|
$ret = $conn->lo_export($lobjId, $filename)
|
|
|
|
|
|
|
|
Exports a large object into a Unix file.
|
|
|
|
Returns -1 upon failure, 1 otherwise.
|
|
|
|
|
|
|
|
|
|
|
|
=head1 AUTHOR
|
|
|
|
|
|
|
|
Edmund Mergl <E.Mergl@bawue.de>
|
|
|
|
|
|
|
|
=head1 SEE ALSO
|
|
|
|
|
1997-09-17 22:46:29 +02:00
|
|
|
L<libpq>, L<large_objects>
|
1997-04-29 21:37:10 +02:00
|
|
|
|
|
|
|
=cut
|