<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.52 $ -->
<reference id="ref.pgsql">
<title>PostgreSQL functions</title>
<titleabbrev>PostgreSQL</titleabbrev>
<partintro>
<warning>
<para>
Use of PostgreSQL module with PHP 4.0.6 is not recommended due to
a bug in notice message handling.
</para>
</warning>
<para>
Postgres, developed originally in the UC Berkeley Computer Science
Department, pioneered many of the object-relational concepts now
becoming available in some commercial databases. It provides
SQL92/SQL3 language support, transaction integrity and type
extensibility. PostgreSQL is an open source descendant of this
original Berkeley code.
</para>
<para>
PostgreSQL database is Open Source product and available without
cost. To use PostgreSQL support, you need PostgreSQL 6.5 or
later. PostgreSQL 7.0 or later to enable all PostgreSQL module
feature. PostgreSQL supports many charactor encoding including
multibyte character encoding. The current version and more
information about PostgreSQL is available at <ulink
url="&url.pgsql;">www.postgresql.org</ulink>.
</para>
<para>
In order to enable PostgreSQL support,
"--enable-pgsql[=DIR]" is required when you compile
PHP. If shared object module is available, PostgreSQL module may
be loaded using <link linkend="ini.extension">extension</link>
directive in php.ini or <function>dl</function>
function. Supported ini directives are described in php.ini-dist
file which comes with source distribution.
</para>
<para>
Not all functions are supported by all builds. It depends on your
libpq (The PostgreSQL C Client interface) versoin and how libpq is
compiled. If there is missing function, libpq does not support
the feature required for the function.
</para>
<para>
It is also important that you use newer libpq than PostgreSQL
Server to be connected. If you use libpq older than PostgreSQL
Server expects, you may have problems.
</para>
<para>
Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets
by default. TCP port will not be openned by default. A table is
shown below describing these new connection possibilities. This
socket will be found in <filename>/tmp/.s.PGSQL.5432</filename>.
This option can be enabled with the '-i' flag to
<command>postmaster</command> and it's meaning is: "listen on
TCP/IP sockets as well as Unix domain sockets".
<table>
<title>Postmaster and PHP</title>
<tgroup cols="3">
<thead>
<row>
<entry>Postmaster</entry>
<entry>PHP</entry>
<entry>Status</entry>
</row>
</thead>
<tbody>
<row>
<entry>postmaster &</entry>
<entry>pg_connect("dbname=MyDbName");</entry>
<entry>OK</entry>
</row>
<row>
<entry>postmaster -i &</entry>
<entry>pg_connect("dbname=MyDbName");</entry>
<entry>OK</entry>
</row>
<row>
<entry>postmaster &</entry>
<entry>pg_connect("host=localhost dbname=MyDbName");</entry>
<entry>
Unable to connect to PostgreSQL server: connectDB() failed:
Is the postmaster running and accepting TCP/IP (with -i)
connection at 'localhost' on port '5432'? in
/path/to/file.php on line 20.
</entry>
</row>
<row>
<entry>postmaster -i &</entry>
<entry>pg_connect("host=localhost dbname=MyDbName");</entry>
<entry>OK</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
A connection to PostgreSQL server can be established with the
following value pairs set in the command string: <command>$conn =
pg_connect("host=myHost port=myPort tty=myTTY options=myOptions
dbname=myDB user=myUser password=myPassword ");
</command>
</para>
<para>
The previous syntax of:
<command>
$conn = pg_connect ("host", "port", "options", "tty", "dbname")
</command>
has been deprecated.
</para>
<para>
Environmental variable affects PostgreSQL server/client
behavior. For example, PostgreSQL module will lookup PGHOST
environment variable when hostname is omitted in connection
string. Supported environment variables are different from version
to version. Refer to PostgreSQL Programmer's Manual (libpq -
Environment Variables) for details.
</para>
<para>
From PostgreSQL 7.1.0, text data type has 1GB as its max
size. Older PostgreSQL's text data type is limitted by block
size. (Default 8KB. Max 32KB defined at compile time)
</para>
<para>
To use the large object (lo) interface, it is required to enclose
large object functions within a transaction block. A transaction
block starts with a SQL statement <command>begin</command> and if
the transaction was valid ends with <command>commit</command> or
<command>end</command>. If the transaction fails the transaction
should be closed with <command>rollback</command> or
<command>abort</command>.
<example>
<title>Using Large Objects</title>
<programlisting role="php">
<![CDATA[
<?php
$database = pg_connect ("dbname=jacarta");
pg_exec ($database, "begin");
$oid = pg_locreate ($database);
echo ("$oid\n");
$handle = pg_loopen ($database, $oid, "w");
echo ("$handle\n");
pg_lowrite ($handle, "large object data");
pg_loclose ($handle);
pg_exec ($database, "commit");
?>
]]>
</programlisting>
</example>
Do not close connection resource before closing large object
resource.
</para>
</partintro>
<refentry id="function.pg-close">
<refnamediv>
<refname>pg_close</refname>
<refpurpose>Close a PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_close</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_close</function> closes down the non-persistent
connection to a PostgreSQL database associated with the given
<parameter>connection</parameter> resource. It returns &true;, if
<parameter>connection</parameter> is a valid connection resource,
otherwise it return &false;.
</para>
<note>
<para>
<function>pg_close</function> is not usually necessary, as
non-persistent open links are automatically closed at the end of
the script's execution. <function>pg_close</function> will not
close persistent links generated by
<function>pg_pconnect</function>.
</para>
</note>
<para>
If there is open large object resource on the connection, do not
close the connection before closing all large object resources.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-cmdtuples">
<refnamediv>
<refname>pg_cmdtuples</refname>
<refpurpose>Returns number of affected records(tuples)</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_cmdtuples</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_cmdtuples</function> returns the number of tuples
(instances/records/rows) affected by INSERT, UPDATE, and DELETE
queries executed by <function>pg_exec</function>. If no tuple is
affected by this function, it will return 0.
<example>
<title><function>pg_cmdtuples</function></title>
<programlisting role="php">
<![CDATA[
<?php
$result = pg_exec ($conn, "INSERT INTO publisher VALUES ('Author')");
$cmdtuples = pg_cmdtuples ($result);
echo $cmdtuples . " tuples are affected.";
?>
]]>
</programlisting>
</example>
</para>
<para>
See also <function>pg_exec</function> and
<function>pg_numrows</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-connect">
<refnamediv>
<refname>pg_connect</refname>
<refpurpose>Open a PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>resource <function>pg_connect</function></funcdef>
<paramdef>string <parameter>connection_string</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_connect</function> returns a connection resource
that is needed by other PostgreSQL functions.
</para>
<para>
<function>pg_connect</function> opens a connection to a
PostgreSQL database specified by
<parameter>connection_string</parameter>. It returns a connection
resource on success. It returns &false;, if the connection could
not be made. <parameter>connection_string</parameter> should be
a quoted string.
<example>
<title>Using pg_connect</title>
<programlisting role="php">
<![CDATA[
<?php
$dbconn = pg_connect ("dbname=mary");
//connect to a database named "mary"
$dbconn2 = pg_connect ("host=localhost port=5432 dbname=mary");
// connect to a database named "mary" on "localhost" at port "5432"
$dbconn3 = pg_connect ("host=sheep port=5432 dbname=mary user=lamb password=foo");
//connect to a database named "mary" on the host "sheep" with a username and password
$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_connect ($conn_string);
//connect to a database named "test" on the host "sheep" with a username and password
?>
]]>
</programlisting>
</example>
The arguments available for
<parameter>connection_string</parameter> includes
<parameter>host</parameter>, <parameter>port</parameter>,
<parameter>tty</parameter>, <parameter>options</parameter>,
<parameter>dbname</parameter>, <parameter>user</parameter>, and
<parameter>password</parameter>.
</para>
<para>
If a second call is made to <function>pg_connect</function> with
the same <parameter>connection_string</parameter> arguments, no
new connection will be established, but instead, the connection
resource of the already opened connection will be returned. You
can have multiple connections to the same database if you use
different connection patameters. (i.e. Use different username)
</para>
<para>
Syntax supports multiple parameters:
<command>$conn = pg_connect ("host", "port", "options", "tty", "dbname")
</command>
has been deprecated.
</para>
<para>
See also <function>pg_pconnect</function>,
<function>pg_close</function>, <function>pg_host</function>,
<function>pg_port</function>, <function>pg_tty</function>,
<function>pg_options</function> and <function>pg_dbname</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-dbname">
<refnamediv>
<refname>pg_dbname</refname>
<refpurpose>Get the database name</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_dbname</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_dbname</function> returns the name of the database
that the given PostgreSQL <parameter>connection</parameter>
resource. It retuns &false;, if <parameter>connection</parameter>
is not a valid PostgreSQL connection resource.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-end-copy">
<refnamediv>
<refname>pg_end_copy</refname>
<refpurpose>Sync with PostgreSQL backend</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_end_copy</function></funcdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_end_copy</function> syncs PostgreSQL frontend
(usually a web server process) with the PostgreSQL server after
doing a copy operation performed by
<function>pg_put_line</function>. <function>pg_end_copy</function>
must be issued, otherwise the PostgreSQL server may get "out of
sync" error with the frontend. It returns &true; for success,
otherwise it returns &false;.
</para>
<para>
For further details and an example, see also
<function>pg_put_line</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-errormessage">
<refnamediv>
<refname>pg_errormessage</refname>
<refpurpose>Get the last error message string of a connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_errormessage</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_errormessage</function> returns a string containing
the last error message for given
<parameter>connection</parameter>. It returns &false; on failure.
</para>
<para>
<function>pg_errormessage</function> returns the last error
message for given <parameter>connection</parameter> and error
message may be overwritten if other libpq functions are called on
the connection. PostgreSQL functions calls libpq functions
internally. Therefore, details about the error may not be
retrieved using the <function>pg_errormessage</function>
function. pg_result_error_message() will be added from 4.2.0 to
get last error for the result resource.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-exec">
<refnamediv>
<refname>pg_exec</refname>
<refpurpose>Execute a query</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>resource <function>pg_exec</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
<paramdef>string <parameter>query</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_exec</function> returns a query result resource if
query could be executed. It returns &false; on failure or if
connection is not a valid connection. Details about the error can
be retrieved using the <function>pg_errormessage</function>
function if connection is valid.
<function>pg_errormessage</function> sends an SQL statement to
the PostgreSQL database specified by the
<parameter>connection</parameter> resource. The
<parameter>connection</parameter> must be a valid connection that
was returned by <function>pg_connect</function> or
<function>pg_pconnect</function>. The return value of this
function is an query result resource to be used to access the
results from other PostgreSQL functions such as
<function>pg_fetch_array</function>.
<note>
<simpara>
PHP/FI returned 1 if the query was not expected to return data
(inserts or updates, for example) and greater than 1 even on
selects that did not return anything. No such assumption can be
made in PHP.
</simpara>
</note>
</para>
<para>
See also <function>pg_fetch_array</function>,
<function>pg_fetch_object</function>,
<function>pg_result</function>, <function>pg_numrows</function>,
<function>pg_cmdtuples</function> and
<function>pg_numfields</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fetch-array">
<refnamediv>
<refname>pg_fetch_array</refname>
<refpurpose>Fetch a row as an array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>pg_fetch_array</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
<paramdef>int
<parameter><optional>result_type</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fetch_array</function> returns an array that
corresponds to the fetched row (tuples/records). It returns
&false;, if there are no more rows.
</para>
<para>
<function>pg_fetch_array</function> is an extended version of
<function>pg_fetch_row</function>. In addition to storing the
data in the numeric indices (field index) to the result array, it
also stores the data in associative indices (field name) by
default.
</para>
<para>
<parameter>row</parameter> is row (record) number to be
retrived. First row is 0.
</para>
<para>
<parameter>result_type</parameter> is optional parameter controls
how return value is initilized.
<parameter>result_type</parameter> is a constant and can take the
following values: PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
<function>pg_fetch_array</function> returns associative array
that has field name as key for PGSQL_ASSOC. field index as key
with PGSQL_NUM and both field name/index as key with
PGSQL_BOTH. Default is PGSQL_BOTH.
<note>
<para>
<parameter>result_type</parameter> was added in PHP 4.0.
</para>
</note>
</para>
<para>
<function>pg_fetch_array</function> is NOT significantly
slower than using <function>pg_fetch_row</function>, while it
provides a significant ease of use.
</para>
<para>
See also <function>pg_fetch_row</function> and
<function>pg_fetch_object</function> and
<function>pg_result</function>.
</para>
<para>
<example>
<title>PostgreSQL fetch array</title>
<programlisting role="php">
<![CDATA[
<?php
$conn = pg_pconnect ("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_exec ($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
$arr = pg_fetch_array ($result, 0, PGSQL_NUM);
echo $arr[0] . " <- array\n";
$arr = pg_fetch_array ($result, 1, PGSQL_ASSOC);
echo $arr["author"] . " <- array\n";
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fetch-object">
<refnamediv>
<refname>pg_fetch_object</refname>
<refpurpose>Fetch a row as an object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>object <function>pg_fetch_object</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
<paramdef>int
<parameter><optional>result_type</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fetch_object</function> returns an object with
properties that correspond to the fetched row. It returns &false;
if there are no more rows or error.
</para>
<para>
<function>pg_fetch_object</function> is similar to
<function>pg_fetch_array</function>, with one difference - an
object is returned, instead of an array. Indirectly, that means
that you can only access the data by the field names, and not by
their offsets (numbers are illegal property names).
</para>
<para>
<parameter>result_type</parameter> is optional parameter controls
how return value is initilized.
<parameter>result_type</parameter> is a constant and can take the
following values: PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
<function>pg_fetch_array</function> returns associative array
that has field name as key for PGSQL_ASSOC. field index as key
with PGSQL_NUM and both field name/index as key with
PGSQL_BOTH. Default is PGSQL_BOTH.
</para>
<para>
<note>
<para>
<parameter>result_type</parameter> was added in PHP 4.0.
</para>
</note>
</para>
<para>
Speed-wise, the function is identical to
<function>pg_fetch_array</function>, and almost as quick as
<function>pg_fetch_row</function> (the difference is
insignificant).
</para>
<para>
See also <function>pg_exec</function>, <function>pg_fetch_array</function>,
<function>pg_fetch_row</function> and <function>pg_result</function>.
</para>
<para>
<example>
<title>Postgres fetch object</title>
<programlisting role="php">
<![CDATA[
<?php
$database = "verlag";
$db_conn = pg_connect ("host=localhost port=5432 dbname=$database");
if (!$db_conn): ?>
<H1>Failed connecting to postgres database <?php echo $database ?></H1> <?php
exit;
endif;
$qu = pg_exec ($db_conn, "SELECT * FROM verlag ORDER BY autor");
$row = 0; // postgres needs a row counter other dbs might not
while ($data = pg_fetch_object ($qu, $row)):
echo $data->autor." (";
echo $data->jahr ."): ";
echo $data->titel."<BR>";
$row++;
endwhile; ?>
<PRE><?php
$fields[] = Array ("autor", "Author");
$fields[] = Array ("jahr", " Year");
$fields[] = Array ("titel", " Title");
$row= 0; // postgres needs a row counter other dbs might not
while ($data = pg_fetch_object ($qu, $row)):
echo "----------\n";
reset ($fields);
while (list (,$item) = each ($fields)):
echo $item[1].": ".$data->$item[0]."\n";
endwhile;
$row++;
endwhile;
echo "----------\n"; ?>
</PRE> <?php
pg_freeresult ($qu);
pg_close ($db_conn);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fetch-row">
<refnamediv>
<refname>pg_fetch_row</refname>
<refpurpose>Get a row as an enumerated array</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>array <function>pg_fetch_row</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fetch_row</function> fetches one row of data from
the result associated with the specified
<parameter>result</parameter> resource. The row (record) is
returned as an array. Each result column is stored in an array
offset, starting at offset 0.
</para>
<para>
It returns an array that corresponds to the fetched row, or &false;
if there are no more rows.
</para>
<para>
See also: <function>pg_exec</function>,
<function>pg_fetch_array</function>,
<function>pg_fetch_object</function> and
<function>pg_result</function>.
</para>
<para>
<example>
<title>Postgres fetch row</title>
<programlisting role="php">
<![CDATA[
<?php
$conn = pg_pconnect ("dbname=publisher");
if (!$conn) {
echo "An error occured.\n";
exit;
}
$result = pg_Exec ($conn, "SELECT * FROM authors");
if (!$result) {
echo "An error occured.\n";
exit;
}
$num = pg_numrows($result);
for ($i=0; $i < $num; $i++) {
$r = pg_fetch_row($result, $i);
for ($j=0; $j < count($r); $j++) {
echo "$r[$j] ";
}
echo "<BR>";
}
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldisnull">
<refnamediv>
<refname>pg_fieldisnull</refname>
<refpurpose>Test if a field is &null;</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_fieldisnull</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row</parameter></paramdef>
<paramdef>mixed <parameter>field</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldisnull</function> test if a field is &null; or
not. It returns 1 if the field in the given row is &null;. It
returns 0 if the field in the given row is NOT &null;. Field can
be specified as colum index (number) or fieldname (string). Row
numbering starts at 0.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldname">
<refnamediv>
<refname>pg_fieldname</refname>
<refpurpose>Returns the name of a field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_fieldname</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldname</function> returns the name of the field
occupying the given <parameter>field_number</parameter> in the
given PostgreSQL <parameter>result</parameter> resource. Field
numbering starts from 0.
</para>
<para>
See also <function>pg_filednum</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldnum">
<refnamediv>
<refname>pg_fieldnum</refname>
<refpurpose>Returns the field number of the named field</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_fieldnum</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>string <parameter>field_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldnum</function> will return the number of the
column (field) slot that corresponds to the
<parameter>field_name</parameter> in the given PosgreSQL
<parameter>result</parameter> resource. Field numbering starts
at 0. This function will return -1 on error.
</para>
<para>
See also <function>pg_fieldname</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldprtlen">
<refnamediv>
<refname>pg_fieldprtlen</refname>
<refpurpose>Returns the printed length</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_fieldprtlen</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row_number</parameter></paramdef>
<paramdef>string <parameter>field_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldprtlen</function> returns the actual printed
length (number of characters) of a specific value in a PostgreSQL
<parameter>result</parameter>. Row numbering starts at 0. This
function will return -1 on an error.
</para>
<para>
See also <function>pg_fieldsize</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldsize">
<refnamediv>
<refname>pg_fieldsize</refname>
<refpurpose>
Returns the internal storage size of the named field
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_fieldsize</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldsize</function> returns the internal storage
size (in bytes) of the field number in the given PostgreSQL
<parameter>result</parameter>. Field numbering starts at 0. A
field size of -1 indicates a variable length field. This function
will return &false; on error.
</para>
<para>
See also <function>pg_fieldlen</function> and <function>pg_fieldtype</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-fieldtype">
<refnamediv>
<refname>pg_fieldtype</refname>
<refpurpose>
Returns the type name for the corresponding field number
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_fieldtype</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>field_number</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_fieldtype</function> returns a string containing the
type name of the given <parameter>field_number</parameter> in the
given PostgreSQL <parameter>result</parameter> resource. Field
numbering starts at 0.
</para>
<para>
See also <function>pg_fieldlen</function> and <function>pg_fieldname</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-freeresult">
<refnamediv>
<refname>pg_freeresult</refname>
<refpurpose>Free result memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_freeresult</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_freeresult</function> only needs to be called if you
are worried about using too much memory while your script is
running. All result memory will automatically be freed when the
script is finished. But, if you are sure you are not going to
need the result data anymore in a script, you may call
<function>pg_freeresult</function> with the
<parameter>result</parameter> resource as an argument and the
associated result memory will be freed.
</para>
<para>
See also <function>pg_exec</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-getlastoid">
<refnamediv>
<refname>pg_getlastoid</refname>
<refpurpose>Returns the last object's oid</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_getlastoid</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_getlastoid</function> is used to retrieve the
<varname>oid</varname> assigned to an inserted tuple (record) if
the result resource is used from the last command sent via
<function>pg_exec</function> and was an SQL INSERT. Returns a
positive integer if there was a valid <varname>oid</varname>. It
returns &false; if an error occurs or the last command sent via
<function>pg_exec</function> was not an INSERT or INSERT is
failed.
</para>
<para>
See also <function>pg_exec</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-host">
<refnamediv>
<refname>pg_host</refname>
<refpurpose>
Returns the host name associated with the connection
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_host</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_host</function> returns the host name of the given
PostgreSQL <parameter>connection</parameter> resource is
connected to.
</para>
<para>
See also <function>pg_connect</function> and
<function>pg_pconnect</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-last-notice">
<refnamediv>
<refname>pg_last_notice</refname>
<refpurpose>
Returns the last notice message from PostgreSQL server
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_last_notice</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_last_notice</function> returns the last notice
message from PostgreSQL server specified by
<parameter>connection</parameter>. PostgreSQL server set notice
message when transaction cannot be continued. There one can avoid
issuing useless SQL using <function>pg_exec</function> using
<function>pg_last_notice</function>. There are other cases that
PostgreSQL server sets notice message. Programmer must check
contents of notice message if it is related to transaction or
not.
</para>
<warning>
<para>
<function>pg_last_notice</function> is added form PHP
4.0.6. However, PHP 4.0.6 has problem with notice message
handling. Use of PostgreSQL module with PHP 4.0.6 is not recommended
even if you are not using <function>pg_last_notice</function>.
</para>
</warning>
<para>
See also <function>pg_exec</function> and <function>pg_errormessage</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loclose">
<refnamediv>
<refname>pg_loclose</refname>
<refpurpose>Close a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_loclose</function></funcdef>
<paramdef>resource <parameter>large_object</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_loclose</function> closes an Inversion Large
Object. <parameter>large_object</parameter> is a resource for the
large object from <function>pg_loopen</function>.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_loopen</function>,
<function>pg_locreate</function> and
<function>pg_loimport</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-locreate">
<refnamediv>
<refname>pg_locreate</refname>
<refpurpose>Create a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_locreate</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_locreate</function> creates an Inversion Large
Object and returns the <varname>oid</varname> of the large
object. <parameter>connection</parameter> specifies a valid
database connection opened by <function>pg_connect</function> or
<function>pg_pconnect</function>. PostgreSQL access modes
INV_READ, INV_WRITE, and INV_ARCHIVE are not supported, the
object is created always with both read and write
access. INV_ARCHIVE has been removed from PostgreSQL itself
(version 6.3 and above). It returns large object oid
otherwise. It retuns &false;, if an error occurred,
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loexport">
<refnamediv>
<refname>pg_loexport</refname>
<refpurpose>Export a large object to file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_loexport</function></funcdef>
<paramdef>int
<parameter>oid</parameter>
</paramdef>
<paramdef>string
<parameter>pathname</parameter>
</paramdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <parameter>oid</parameter> argument specifies oid of the
large object to export and the <parameter>pathname</parameter>
argument specifies the pathname of the file. It returns &false; if
an error occurred, &true; otherwise.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_loimport</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loimport">
<refnamediv>
<refname>pg_loimport</refname>
<refpurpose>Import a large object from file</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_loimport</function></funcdef>
<paramdef>string <parameter>pathname</parameter></paramdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
The <parameter>pathname</parameter> argument specifies the
pathname of the file to be imported as a large object. It returns
&false; if an error occurred, oid of the just created large
object otherwise.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
¬e.sm.uidcheck;
<para>
See also <function>pg_loexport</function> and
<function>pg_loopen</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loopen">
<refnamediv>
<refname>pg_loopen</refname>
<refpurpose>Open a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>resource <function>pg_loopen</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
<paramdef>int <parameter>oid</parameter></paramdef>
<paramdef>string <parameter>mode</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_loopen</function> open an Inversion Large Object and
returns large object resource. The resource encapsulates
information about the connection.
<parameter>oid</parameter> specifies a valid large object oid and
<parameter>mode</parameter> can be either "r", "w", or "rw". It
returns &false; if there is an error.
</para>
<warning>
<para>
Do not close the database connection before closing the large
object resource.
</para>
</warning>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_loclose</function> and
<function>pg_locreate</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loread">
<refnamediv>
<refname>pg_loread</refname>
<refpurpose>Read a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_loread</function></funcdef>
<paramdef>resource <parameter>large_object</parameter></paramdef>
<paramdef>int <parameter>len</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_loread</function> reads at most
<parameter>len</parameter> bytes from a large object and returns
it as a string. <parameter>large_object</parameter> specifies a
valid large object resource and<parameter>len</parameter>
specifies the maximum allowable size of the large object
segment. It returns &false; if there is an error.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_loreadall</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-loreadall">
<refnamediv>
<refname>pg_loreadall</refname>
<refpurpose>
Read a entire large object and send straight to browser
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_loreadall</function></funcdef>
<paramdef>resource <parameter>large_object</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_loreadall</function> reads a large object and passes
it straight through to the browser after sending all pending
headers. Mainly intended for sending binary data like images or
sound. It returns number of bytes read. It returns &false;, if an
error occured.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_loread</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-lounlink">
<refnamediv>
<refname>pg_lounlink</refname>
<refpurpose>Delete a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_lounlink</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
<paramdef>int <parameter>oid</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_lounlink</function> deletes a large object with the
<parameter>oid</parameter>. It rreturn &true; on success,
otherwise returns &false;.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_locreate</function> and
<function>pg_loimport</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-lowrite">
<refnamediv>
<refname>pg_lowrite</refname>
<refpurpose>Write a large object</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_lowrite</function></funcdef>
<paramdef>resource <parameter>large_object</parameter></paramdef>
<paramdef>string <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_lowrite</function> writes at most to a large object
from a variable <parameter>data</parameter> and returns the number
of bytes actually written, or &false; in the case of an error.
<parameter>large_object</parameter> is a large object resource
from <function>pg_loopen</function>.
</para>
<para>
To use the large object (lo) interface, it is necessary to
enclose it within a transaction block.
</para>
<para>
See also <function>pg_locreate</function> and
<function>pg_loopen</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-numfields">
<refnamediv>
<refname>pg_numfields</refname>
<refpurpose>Returns the number of fields</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_numfields</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_numfields</function> returns the number of fields
(columns) in a PostgreSQL <parameter>result</parameter>. The
argument is a result resource returned by
<function>pg_exec</function>. This function will return -1 on
error.
</para>
<para>
See also <function>pg_numrows</function> and
<function>pg_cmdtuples</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-numrows">
<refnamediv>
<refname>pg_numrows</refname>
<refpurpose>Returns the number of rows</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_numrows</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_numrows</function> will return the number of rows in a
PostgreSQL result. The argument is a result resource
returned by <function>pg_exec</function>. This function will
return -1 on error.
</para>
<para>
See also <function>pg_numfields</function> and
<function>pg_cmdtuples</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-options">
<refnamediv>
<refname>pg_options</refname>
<refpurpose>Get the options associated with the connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_options</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_options</function> will return a string containing
the options specified on the given PostgreSQL
<parameter>connection</parameter> resource.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-pconnect">
<refnamediv>
<refname>pg_pconnect</refname>
<refpurpose>Open a persistent PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_pconnect</function></funcdef>
<paramdef>string <parameter>connection_string</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_pconnect</function> opens a connection to a
PostgreSQL database. It returns a connection resource that is
needed by other PostgreSQL functions.
</para>
<para>
It returns a connection resource on success, or &false; if the
connection could not be made. The arguments should be within a
quoted string. The arguments available include
<parameter>host</parameter>, <parameter>port</parameter>,
<parameter>tty</parameter>, <parameter>options</parameter>,
<parameter>dbname</parameter>, <parameter>user</parameter>, and
<parameter>password</parameter>.
</para>
<example>
<title>Using pg_connect</title>
<programlisting role="php">
<![CDATA[
<?php
$dbconn = pg_connect ("dbname=mary");
//connect to a database named "mary"
$dbconn2 = pg_connect ("host=localhost port=5432 dbname=mary");
// connect to a database named "mary" on "localhost" at port "5432"
$dbconn3 = pg_connect ("host=sheep port=5432 dbname=mary user=lamb password=foo");
//connect to a database named "mary" on the host "sheep" with a username and password
$conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
$dbconn4 = pg_connect ($conn_string);
//connect to a database named "test" on the host "sheep" with a username and password
?>
]]>
</programlisting>
</example>
<para>
If a second call is made to <function>pg_pconnect</function> with
the same arguments, no new connection will be established, but
instead, the connection resource of the already opened connection
will be returned. You can have multiple connections to the same
database if you use different connection patameters. (i.e. Use
different username)
</para>
<para>
The previous syntax of:
<command>$conn = pg_pconnect ("host", "port", "options", "tty",
"dbname")
</command>
has been deprecated.
</para>
<para>
To enable persistent connection, <link
linkend="ini.pgsql.allow-persistent">pgsql.allow_persistent</link>
php.ini directive must be set to "On". (Default is On)
Max number of persistent connection can be defined by <link
linkend="ini.pgsql.max-persistent">pgsql.max_persistent</link>
php.ini directive. (Default is -1 which is no limit) Total number
of connection can be set by <link
linkend="ini.pgsql.max-links">pgsql.max_links</link> php.ini
directive.
</para>
<para>
<function>pg_close</function> will not close persistent links
generated by <function>pg_pconnect</function>.
</para>
<para>
See also <function>pg_connect</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-port">
<refnamediv>
<refname>pg_port</refname>
<refpurpose>
Return the port number associated with the connection
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_port</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_port</function> returns the port number that the
given PostgreSQL <parameter>connection</parameter> resource is
connected to.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-put-line">
<refnamediv>
<refname>pg_put_line</refname>
<refpurpose>Send a NULL-terminated string to PostgreSQL backend</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_put_line</function></funcdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
<paramdef>string <parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_put_line</function> sends a NULL-terminated string
to the PostgreSQL backend server. This is useful for example for
very high-speed inserting of data into a table, initiated by
starting a PostgreSQL copy-operation. That final NULL-character
is added automatically. It returns &true; if successfull, &false;
otherwise.
</para>
<note>
<para>
Note the application must explicitly send the two characters "\."
on a final line to indicate to the backend that it has finished
sending its data.
</para>
</note>
<para>
See also <function>pg_end_copy</function>.
<example>
<title>High-speed insertion of data into a table</title>
<programlisting role="php">
<![CDATA[
<?php
$conn = pg_pconnect ("dbname=foo");
pg_exec($conn, "create table bar (a int4, b char(16), d float8)");
pg_exec($conn, "copy bar from stdin");
pg_put_line($conn, "3\thello world\t4.5\n");
pg_put_line($conn, "4\tgoodbye world\t7.11\n");
pg_put_line($conn, "\\.\n");
pg_end_copy($conn);
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
</refentry>
<refentry id="function.pg-result">
<refnamediv>
<refname>pg_result</refname>
<refpurpose>Returns values from a result resource</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>mixed <function>pg_result</function></funcdef>
<paramdef>resource <parameter>result</parameter></paramdef>
<paramdef>int <parameter>row_number</parameter></paramdef>
<paramdef>mixed <parameter>field</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_result</function> returns values from a
<parameter>result</parameter> resource returned by
<function>pg_exec</function>. <parameter>row_number</parameter>
is integer. <parameter>field</parameter> is field name(string)
or field index (integer). The <parameter>row_number</parameter>
and <parameter>field</parameter> sepcify what cell in the table
of results to return. Row numbering starts from 0. Instead of
naming the field, you may use the field index as an unquoted
number. Field indices start from 0.
</para>
<para>
PostgreSQL has many built in types and only the basic ones are
directly supported here. All forms of <type>integer</type>,
<type>boolean</type> and void
<!-- FIXME: is that still true? PHP supports boolean&null now... -->
<!-- Yes, supporting boolean&null breaks scripts. pg_fetch_array()
can be used instead. I might take of this issue with additional
ini directive. yohgaki@php.net -->
types are
returned as <type>integer</type> values. All forms of float, and
real types are returned as <type>float</type> values. All other
types, including arrays are returned as strings formatted in the
same default PostgreSQL manner that you would see in the
<command>psql</command> program.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-set-client-encoding">
<refnamediv>
<refname>pg_set_client_encoding</refname>
<refpurpose>
Set the client encoding
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>pg_set_client_encoding</function></funcdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
<paramdef>string <parameter>encoding</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_set_client_encoding</function> sets the client
encoding and return 0 if success or -1 if error.
</para>
<para>
<parameter>encoding</parameter> is the client
encoding and can be either :
SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,
MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT,
SJIS, BIG5, WIN1250.
</para>
<note>
<para>
This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or
higher. If libpq is compiled without multibyte encoding support,
<function>pg_set_client_encoding</function> will not be
included. Refer to PostgreSQL manual to enable multibyte support
for PostgreSQL server and libpq.
</para>
<para>
The function used to be called
<function>pg_setclientencoding</function>.
</para>
</note>
<para>
See also <function>pg_client_encoding</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-client-encoding">
<refnamediv>
<refname>pg_client_encoding</refname>
<refpurpose>
Get the client encoding
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_client_encoding</function></funcdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_client_encoding</function> returns the client
encoding as the string. The returned string should be either :
SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,
MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5,
WIN1250.
</para>
<note>
<para>
This function requires PHP-4.0.2 or higher and PostgreSQL-7.0 or
higher.
</para>
<para>
The function used to be called
<function>pg_clientencoding</function>.
</para>
</note>
<para>
See also <function>pg_set_client_encoding</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-trace">
<refnamediv>
<refname>pg_trace</refname>
<refpurpose>Enable tracing a PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_trace</function></funcdef>
<paramdef>string
<parameter>pathname</parameter>
</paramdef>
<paramdef>string
<parameter><optional>mode</optional></parameter>
</paramdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_trace</function> enables tracing of the PostgreSQL
frontend/backend communication to a debugging file specified as
<parameter>pathname</parameter>. To fully understand the results,
one needs to be familiar with the internals of PostgreSQL
communication protocol. For those who are not, it can still be
useful for tracing errors in queries sent to the server, you
could do for example <command>grep '^To backend'
trace.log</command> and see what query actually were sent to the
PostgreSQL server. For more information, refer to PostgreSQL
manual.
</para>
<para>
<parameter>Filename</parameter> and <parameter>mode</parameter>
are the same as in <function>fopen</function>
(<parameter>mode</parameter> defaults to 'w'),
<parameter>connection</parameter> specifies the connection to
trace and defaults to the last one opened.
</para>
<para>
It returns &true; if <parameter>pathname</parameter> could be opened
for logging, &false; otherwise.
</para>
<para>
See also <function>fopen</function> and
<function>pg_untrace</function>.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-tty">
<refnamediv>
<refname>pg_tty</refname>
<refpurpose>
Return the tty name associated with the connection
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>string <function>pg_tty</function></funcdef>
<paramdef>resource <parameter>connection</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
<function>pg_tty</function> returns the tty name that server
side debugging output is sent to on the given PostgreSQL
<parameter>connection</parameter> resource.
</para>
</refsect1>
</refentry>
<refentry id="function.pg-untrace">
<refnamediv>
<refname>pg_untrace</refname>
<refpurpose>Disable tracing of a PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
<funcdef>bool <function>pg_untrace</function></funcdef>
<paramdef>resource
<parameter><optional>connection</optional></parameter>
</paramdef>
</funcprototype>
</funcsynopsis>
<para>
Stop tracing started by <function>pg_trace</function>.
<parameter>connection</parameter> specifies the connection that was
traced and defaults to the last one opened.
</para>
<para>
Returns always &true;.
</para>
<para>
See also <function>pg_trace</function>.
</para>
</refsect1>
</refentry>
</reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->