<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.70 $ -->
 <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>
   <warning>
    <para>
     PostgreSQL function names will be changed in 4.2.0 release to
     confirm current coding standard. Most of new names will have
     additional under score(s), e.g. pg_lo_open(). Some functions are
     renamed to different name for consistency. e.g. pg_exec() to
     pg_query(). Older names may be used in 4.2.0 and a few releases
     from 4.2.0, but they may be deleted in the future. CVS version
     has new function names.
    </para>
    <example>
     <title>Function names changed</title>
     <programlisting role="php">
<![CDATA[
OLD NAME           NEW NAME
pg_exec            pg_query
getlastoid         pg_last_oid
pg_cmdtuples       pg_affected_rows
pg_errormessage    pg_last_error
pg_numrows         pg_num_rows
pg_numfields       pg_num_fields
pg_fieldname       pg_field_name
pg_fieldsize       pg_field_size
pg_fieldtype       pg_field_type
pg_fieldnum        pg_field_num
pg_fieldprtlen     pg_field_prtlen
pg_fieldisnull     pg_field_is_null
pg_freeresult      pg_free_result
pg_result          pg_fetch_result
pg_loreadall       pg_lo_read_all
pg_locreate        pg_lo_create
pg_lounlink        pg_lo_unlink
pg_loopen          pg_lo_open
pg_loclose         pg_lo_close
pg_loread          pg_lo_read
pg_lowrite         pg_lo_write
pg_loimport        pg_lo_import
pg_loexport        pg_lo_export
]]>
     </programlisting>
    </example>
    <para>
     Obsolete pg_connect()/pg_pconnect() syntax will be depreciated to
     support async connect feature in the future. Please use
     connection string for pg_connect() and pg_pconnect().
    </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/SQL99 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 character 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,
    &quot;--with-pgsql[=DIR]&quot; 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 <filename>php.ini</filename> or <function>dl</function>
    function. Supported ini directives are described in 
    <filename>php.ini-dist</filename> 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) version 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 opened 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 &amp;</entry>
	<entry>pg_connect("dbname=MyDbName");</entry>
	<entry>OK</entry>
       </row>
       <row>
	<entry>postmaster -i &amp;</entry>
	<entry>pg_connect("dbname=MyDbName");</entry>
	<entry>OK</entry>
       </row>
       <row>
	<entry>postmaster &amp;</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 &amp;</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 limited 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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_close</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_cmdtuples</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>resource</type><methodname>pg_connect</methodname>
      <methodparam><type>string</type><parameter>connection_string</parameter></methodparam>
     </methodsynopsis>
    <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 string.
    </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>
     <methodsynopsis>
      <type>string</type><methodname>pg_dbname</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_dbname</function> returns the name of the database
     that the given PostgreSQL <parameter>connection</parameter>
     resource. It returns &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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_end_copy</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_errormessage</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>resource</type><methodname>pg_exec</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
    <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>
       <parameter>connection</parameter> is a optional parameter for
       <function>pg_exec</function>. If
       <parameter>connection</parameter> is not used, default
       connection is used. Default connection is the last connection
       made by <function>pg_connect</function> or
       <function>pg_pconnect</function>.
      </simpara>
      <simpara>
       Although <parameter>connection</parameter> can be omitted, it
       is not recommended, since it could be a cause of hard to find
       bug in script.
      </simpara>
     </note>
    </para>
    <para>
     See also <function>pg_connect</function>,
     <function>pg_pconnect</function>,
     <function>pg_fetch_array</function>,
     <function>pg_fetch_object</function>,
     <function>pg_numrows</function>,
     and <function>pg_cmdtuples</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>
     <methodsynopsis>
      <type>array</type><methodname>pg_fetch_array</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
     </methodsynopsis>
    <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
     retrieved. First row is 0.
    </para>
    <para>
     <parameter>result_type</parameter> is optional parameter controls
     how return value is initialized.
     <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>
    <note>
     <para>
      From 4.1.0, <parameter>row</parameter> became optional.
     </para>
    </note>
   </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>
     <methodsynopsis>
      <type>object</type><methodname>pg_fetch_object</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>result_type</parameter></methodparam>
     </methodsynopsis>
    <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 initialized.
     <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++;
}
?>
<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++;
}
echo "----------\n"; 
?>
</PRE> 
<?php
pg_freeresult ($qu);
pg_close ($db_conn);
?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      From 4.1.0, <parameter>row</parameter> became optional.
     </para>
    </note>
   </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>
     <methodsynopsis>
      <type>array</type><methodname>pg_fetch_row</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
     </methodsynopsis>
    <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]&nbsp;";
  }

  echo "<BR>";

}
 
?>
]]>
      </programlisting>
     </example>
    </para>
    <note>
     <para>
      From 4.1.0, <parameter>row</parameter> became optional.
     </para>
    </note>
   </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>
     <methodsynopsis>
      <type>int</type><methodname>pg_fieldisnull</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>field</parameter></methodparam>
     </methodsynopsis>
    <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 column 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>
     <methodsynopsis>
      <type>string</type><methodname>pg_fieldname</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_number</parameter></methodparam>
     </methodsynopsis>
    <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_fieldnum</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>
     <methodsynopsis>
      <type>int</type><methodname>pg_fieldnum</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>string</type><parameter>field_name</parameter></methodparam>
     </methodsynopsis>
    <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 PostgreSQL
     <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_fieldprtlen</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row_number</parameter></methodparam>
      <methodparam><type>string</type><parameter>field_name</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_fieldsize</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_number</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_fieldtype</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>field_number</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_freeresult</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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. It returns true on success
     and false if an error occurs.
    </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>
     <methodsynopsis>
      <type>int</type><methodname>pg_getlastoid</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_host</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_last_notice</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
      This function is EXPERIMENTAL and it is not fully implemented
      yet. <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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_loclose</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_locreate</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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 returns &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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_loexport</methodname>
      <methodparam><type>int</type><parameter>oid</parameter></methodparam>
      <methodparam><type>string</type><parameter>pathname</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_loimport</methodname>
      <methodparam><type>string</type><parameter>pathname</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
    &note.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>
     <methodsynopsis>
      <type>resource</type><methodname>pg_loopen</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>int</type><parameter>oid</parameter></methodparam>
      <methodparam><type>string</type><parameter>mode</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_loread</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
      <methodparam><type>int</type><parameter>len</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_loreadall</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
     </methodsynopsis>
    <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 occurred.
    </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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_lounlink</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>int</type><parameter>oid</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_lounlink</function> deletes a large object with the
     <parameter>oid</parameter>. It returns &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>
     <methodsynopsis>
      <type>int</type><methodname>pg_lowrite</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_numfields</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_numrows</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_numrows</function> will return the number of rows in
     a PostgreSQL <parameter>result</parameter> resource.
     <parameter>result</parameter> is a query result resource returned
     by <function>pg_exec</function>. This function will return -1 on
     error.
    </para>
    <note>
     <para>
      Use <function>pg_cmdtuples</function> to get number of rows
      affected by INSERT, UPDATE and DELETE query.
     </para>
    </note>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_options</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>int</type><methodname>pg_pconnect</methodname>
      <methodparam><type>string</type><parameter>connection_string</parameter></methodparam>
     </methodsynopsis>
    <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_pconnect</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 string.
    </para>
    <para>
     Multiple parameters syntax for <function>pg_pconnect</function> 
     <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>
     <filename>php.ini</filename> directive must be set to &quot;On&quot;. (Default is On)
     Max number of persistent connection can be defined by <link
     linkend="ini.pgsql.max-persistent">pgsql.max_persistent</link>
     <filename>php.ini</filename> 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> 
     <filename>php.ini</filename> 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>
     <methodsynopsis>
      <type>int</type><methodname>pg_port</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_put_line</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <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 successful, &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>
     <methodsynopsis>
      <type>mixed</type><methodname>pg_result</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
      <methodparam><type>int</type><parameter>row_number</parameter></methodparam>
      <methodparam><type>mixed</type><parameter>field</parameter></methodparam>
     </methodsynopsis>
    <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> specify 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>
     <methodsynopsis>
      <type>int</type><methodname>pg_set_client_encoding</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>encoding</parameter></methodparam>
     </methodsynopsis>
    <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. Available encoding depends on your PostgreSQL and libpq
     version. Refer to PostgreSQL manual for supported encodings for
     your PostgreSQL.
    </para>
    <note>
     <para>
      This function requires PHP-4.0.3 or higher and PostgreSQL-7.0 or
      higher. Supported encoding depends on PostgreSQL version. Refer
      to PostgreSQL manual for details.
     </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>      
     <methodsynopsis>
      <type>string</type><methodname>pg_client_encoding</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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.3 or higher and PostgreSQL-7.0 or
      higher. If libpq is compiled without multibyte encoding support,
      <function>pg_set_client_encoding</function> always return
      &quot;SQL_ASCII&quot;. Supported encoding depends on PostgreSQL
      version.  Refer to PostgreSQL manual for details to enable
      multibyte support and encoding supported.
     </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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_trace</methodname>
      <methodparam><type>string</type><parameter>pathname</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>mode</parameter></methodparam>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>string</type><methodname>pg_tty</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>
     <methodsynopsis>
      <type>bool</type><methodname>pg_untrace</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <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>



  <refentry id='function.pg-get-result'>
   <refnamediv>
    <refname>pg_get_result</refname>
    <refpurpose>
     Get asynchronous query result
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>pg_get_result</methodname>
      <methodparam choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_get_result</function> get result resource from async
     query executed by
     <function>pg_send_query</function>. <function>pg_send_query</function>
     can send multiple queries to PostgreSQL server and
     <function>pg_get_result</function> is used to get query result
     one by one. It returns result resource. If there is no more
     results, it returns &false;.
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-result-status'>
   <refnamediv>
    <refname>pg_result_status</refname>
    <refpurpose>
     Get status of query result
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>pg_result_status</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_result_status</function> returns status of result
     resource. Possible retun values are PGSQL_EMPTY_QUERY,
     PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO,
     PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR and
     PGSQL_FATAL_ERROR.
    </para>
    <para>
     See also <function>pg_connection_status</function>.
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-send-query'>
   <refnamediv>
    <refname>pg_send_query</refname>
    <refpurpose>
     Send asynchronous query
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pg_send_query</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
     <methodsynopsis>
      <type>bool</type><methodname>pg_send_query</methodname>
      <methodparam><type>string</type><parameter>query</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_send_query</function> send asynchronous query to the
     <parameter>connection</parameter>. Unlike
     <function>pg_query</function>, it can send multiple query to
     PostgreSQL and get the result one by one using
     <function>pg_get_result</function>. Script execution is not block
     while query is executing. Use
     <function>pg_connection_busy</function> to check connection is
     busy (i.e. query is executing) Query may be canceled by calling
     <function>pg_cancel_query</function>.
    </para>
    <para>
     Although, user can send multiple query at once. User cannot send
     multiple query over busy connection. If query is sent while
     connection is busy, it waits until last query is finished and
     discards all result.
    </para>
    <para>
     See also <function>pg_query</function>,
     <function>pg_cancel_query</function>,
     <function>pg_get_result</function> and
     <function>pg_connection_busy</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-cancel-query'>
   <refnamediv>
    <refname>pg_cancel_query</refname>
    <refpurpose>
     Cancel async query
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pg_cancel_query</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_cancel_query</function> cancel asynchronous query sent by 
     <function>pg_send_query</function>. You cannot cancel query executed by 
     <function>pg_query</function>.
    </para>
    <para>
     See also <function>pg_send_query</function>,
     <function>pg_cancel_result</function> and
     <function>pg_connection_busy</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-connection-busy'>
   <refnamediv>
    <refname>pg_connection_busy</refname>
    <refpurpose>
     Get connection is busy or not
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pg_connection_busy</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_connection_busy</function> returns &true; if
     connection busy. If connection is busy, previously sent query to
     PostgreSQL server is still executing. If
     <function>pg_get_result</function> is called,
     <function>pg_get_result</function> will block.
    </para>
    <para>
     See also <function>pg_connection_status</function> and
     <function>pg_get_result</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-connection-reset'>
   <refnamediv>
    <refname>pg_connection_reset</refname>
    <refpurpose>
     Reset connection (reconnect)
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pg_connection_reset</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_connection_reset</function> reset connection with
     the same parameter when connection is made. It is useful for
     error recovery. It returns &true; if it resets connection
     successfully, otherwise returns &false;.
    </para>
    <para>
     See also <function>pg_connect</function>,
     <function>pg_pconnect</function> and
     <function>pg_connection_status</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-connection-status'>
   <refnamediv>
    <refname>pg_connection_status</refname>
    <refpurpose>
     Get connection status
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>pg_connection_status</methodname>
      <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_connection_status</function> returns a connection
     status. Possible status is <literal>PGSQL_CONNECTION_O</literal>
     or <literal>PGSQL_CONNECTION_BAD</literal>.
    </para>
    <para>
     See also <function>pg_connection_busy</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-copy-from'>
   <refnamediv>
    <refname>pg_copy_from</refname>
    <refpurpose>
     Copy table from array
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>pg_copy_from</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>table_name</parameter></methodparam>
      <methodparam><type>array</type><parameter>rows</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>null_as</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_copy_from</function> copy table from array. It
     return &true; for success, otherwise &false;.
    </para>
    <para>
     See also <function>pg_copy_to</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-copy-to'>
   <refnamediv>
    <refname>pg_copy_to</refname>
    <refpurpose>
     Copy table to array
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>pg_copy_to</methodname>
      <methodparam><type>int</type><parameter>connection</parameter></methodparam>
      <methodparam><type>string</type><parameter>table_name</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>delimiter</parameter></methodparam>
      <methodparam choice="opt"><type>string</type><parameter>null_as</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_copy_to</function> copy table to array. The result
     array is returned if it success to copy. Otherwise it returns
     &false;.
    </para>
    <para>
     See also <function>pg_copy_from</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-escape-bytea'>
   <refnamediv>
    <refname>pg_escape_bytea</refname>
    <refpurpose>
     Escape binary for bytea type
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>pg_escape_bytea</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_escape_string</function> escapes string for
     bytea datatype.  It returns escaped string.
    </para>
    <note>
     <para>
      This function is requires PostgreSQL 7.2 or later.
      </para>
    </note>
    <para>
     See also <function>pg_escape_string</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-escape-string'>
   <refnamediv>
    <refname>pg_escape_string</refname>
    <refpurpose>
     Escape string for text/char type
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>pg_escape_string</methodname>
      <methodparam><type>string</type><parameter>data</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_escape_string</function> escapes string for
     text/char datatype.  It returns escaped string.
    </para>
    <note>
     <para>
      This function is requires PostgreSQL 7.2 or later.
      </para>
    </note>
    <para>
     See also <function>pg_escape_bytea</function>
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-lo-seek'>
   <refnamediv>
    <refname>pg_lo_seek</refname>
    <refpurpose>
     Seeks position of large object
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>pg_lo_seek</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
      <methodparam><type>int</type><parameter>offset</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>whence</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_lo_seek</function> seeks position of large object
     resource. <parameter>whence</parameter> is PGSQL_SEEK_SET,
     PGSQL_SEEK_CUR or PGSQL_SEEK_END.
    </para>
    <para>
     See also <function>pg_lo_tell</function>.
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-lo-tell'>
   <refnamediv>
    <refname>pg_lo_tell</refname>
    <refpurpose>
     Returns current position of large object
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>pg_lo_tell</methodname>
      <methodparam><type>resource</type><parameter>large_object</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_lo_tell</function> returns current position (offset
     from the beginning of large object).
    </para>
    <para>
     See also <function>pg_lo_seek</function>.
    </para>
   </refsect1>
  </refentry>



  <refentry id='function.pg-result-error'>
   <refnamediv>
    <refname>pg_result_error</refname>
    <refpurpose>
     Get error message associated with result
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>pg_result_error</methodname>
      <methodparam><type>resource</type><parameter>result</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>pg_result_error</function> returns error message
     associated with <parameter>result</parameter> resource. Therefore,
     user has better chance to get better error message than
     <function>pg_last_error</function>.
    </para>
    <para>
     See also <function>pg_query</function>,
     <function>pg_send_query</function>,
     <function>pg_get_result</function>,
     <function>pg_last_error</function> and
     <function>pg_last_notice</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
indent-tabs-mode:nil
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
-->