php-doc-en/functions/pgsql.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.47 $ -->
 <reference id="ref.pgsql">
  <title>PostgreSQL functions</title>
  <titleabbrev>PostgreSQL</titleabbrev>

  <partintro>
   <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 is available without cost. The current version is
    available at <ulink url="&url.pgsql;">www.PostgreSQL.org</ulink>.
   </para>
   <para>
    Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets.
    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");</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.php3 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>
    One can establish a connection 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>
    To use the large object (lo) interface, it is necessary to enclose
    it within a transaction block. A transaction block starts with a
    <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">
&lt;?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, "gaga");
    pg_loclose ($handle);
    pg_exec ($database, "commit");
?>
     </programlisting>
    </example>
   </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>int <parameter>connection</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns &false; if connection is not a valid connection index, &true;
     otherwise.  Closes down the connection to a PostgreSQL database
     associated with the given connection index.
    </para>
    <note><para> 
     This isn't usually necessary, as non-persistent open
     links are automatically closed at the end of the script's
     execution.
    </para></note>
    <para> 
     <function>pg_close</function> will not close persistent links
     generated by <function>pg_pconnect</function>.
    </para>	 
   </refsect1>
  </refentry>

  <refentry id="function.pg-cmdtuples">
   <refnamediv>
    <refname>pg_cmdtuples</refname>
    <refpurpose>Returns number of affected tuples</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>pg_cmdtuples</function></funcdef>
      <paramdef>int <parameter>result_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_cmdtuples</function> returns the number of tuples
     (instances) affected by INSERT, UPDATE, and DELETE queries. If no
     tuple is affected the function will return 0.
     <example>
      <title><function>pg_cmdtuples</function></title>
      <programlisting role="php">
&lt;?php
$result = pg_exec ($conn, "INSERT INTO publisher VALUES ('Author')");
$cmdtuples = pg_cmdtuples ($result);
echo $cmdtuples . " &lt;- cmdtuples affected.";
?>
      </programlisting>
     </example>
    </para>
    <para>
     See also <function>pg_numfields</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>int <function>pg_connect</function></funcdef>
      <paramdef>string <parameter>host</parameter></paramdef>
      <paramdef>string <parameter>port</parameter></paramdef>
      <paramdef>string <parameter>dbname</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>int <function>pg_connect</function></funcdef>
      <paramdef>string <parameter>host</parameter></paramdef>
      <paramdef>string <parameter>port</parameter></paramdef>
      <paramdef>string <parameter>options</parameter></paramdef>
      <paramdef>string <parameter>dbname</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>int <function>pg_connect</function></funcdef>
      <paramdef>string <parameter>host</parameter></paramdef>
      <paramdef>string <parameter>port</parameter></paramdef>
      <paramdef>string <parameter>options</parameter></paramdef>
      <paramdef>string <parameter>tty</parameter></paramdef>
      <paramdef>string <parameter>dbname</parameter></paramdef>
     </funcprototype>
     <funcprototype>
      <funcdef>int <function>pg_connect</function></funcdef>
      <paramdef>string <parameter>conn_string</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns a connection index on success, or &false; if the connection
     could not be made.  Opens a connection to a PostgreSQL database.
     The arguments should be within a quoted string.
     <example>
     <title>Using pg_connect arguments</title>
     <programlisting role="php">
&lt;?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=baaaa");
//connect to a database named "mary" on the host "sheep" with a username and password
?>
     </programlisting>
     </example>
     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>
    <para>
     If a second call is made to <function>pg_connect</function> with
     the same arguments, no new connection will be established, but
     instead, the connection index of the already opened connection
     will be returned.
    </para>
    <para>
     This function returns a connection index that is needed by other
     PostgreSQL functions. You can have multiple connections open at
     once.
    </para>
    <para>
     The previous syntax of:
     <command>$conn = pg_connect ("host", "port", "options", "tty",
    "dbname")
     </command>
     has been deprecated.
    </para>
    <para>
     See also <function>pg_pconnect</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>int <parameter>connection</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns the name of the database that the given PostgreSQL
     connection index is connected to, or &false; if connection is not a
     valid connection index.
    </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 with
     the backend after doing a copy operation. It must be issued or
     the backend may get "out of sync" with the frontend. Returns
     &true; if successfull, &false; otherwise.
    </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 error message string</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>pg_errormessage</function></funcdef>
      <paramdef>int <parameter>connection</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns a string containing the error message, &false; on failure.
     Details about the error probably cannot be retrieved using the
     <function>pg_errormessage</function> function if an error occured
     on the last database action for which a valid connection exists,
     this function will return a string containing the error message
     generated by the backend server.
    </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>int <function>pg_exec</function></funcdef>
      <paramdef>int <parameter>connection</parameter></paramdef>
      <paramdef>string <parameter>query</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns a result index if query could be executed, &false; on
     failure or if connection is not a valid connection index. Details
     about the error can be retrieved using the
     <function>pg_ErrorMessage</function> function if connection is
     valid.  Sends an SQL statement to the PostgreSQL database
     specified by the connection index. The connection must be a valid
     index that was returned by <function>pg_Connect</function>.  The
     return value of this function is an index to be used to access
     the results from other PostgreSQL functions.  
     <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>
   </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>int <parameter>result</parameter></paramdef>
      <paramdef>int <parameter>row</parameter></paramdef>
      <paramdef>int 
       <parameter><optional>result_type</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para> 
     Returns: An array that corresponds to the fetched row, or &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 of the result array, it also stores
     the data in associative indices, using the field names as keys.
    </para>
    <para>
     The third optional argument <parameter>result_type</parameter> in
     <function>pg_fetch_array</function> is a constant and can take the
     following values: PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
     <note>
      <para>
       <parameter>Result_type</parameter> was added in PHP 4.0.
      </para>
     </note>
    </para>
    <para>
     An important thing to note is that using
     <function>pg_fetch_array</function> is NOT significantly
     slower than using <function>pg_fetch_row</function>, while it
     provides a significant added value.
    </para>
    <para>
     For further details, see also
     <function>pg_fetch_row</function>
    </para>
    <example>
     <title>PostgreSQL fetch array</title>
     <programlisting role="php">
&lt;?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);
echo $arr[0] . " &lt;- array\n";

$arr = pg_fetch_array ($result, 1);
echo $arr["author"] . " &lt;- array\n";
?>
     </programlisting>
    </example>
   </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>int <parameter>result</parameter></paramdef>
      <paramdef>int <parameter>row</parameter></paramdef>
      <paramdef>int 
       <parameter><optional>result_type</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para> 
     Returns: An object with properties that correspond to the fetched
     row, or &false; if there are no more rows.
    </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>
     The third optional argument <parameter>result_type</parameter> in
     <function>pg_fetch_object</function> is a constant and can take the
     following values: PGSQL_ASSOC, PGSQL_NUM, and PGSQL_BOTH.
     <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_fetch_array</function> and
     <function>pg_fetch_row</function>.
     <example>
      <title>Postgres fetch object</title>
      <programlisting role="php">
&lt;?php 
$database = "verlag";
$db_conn = pg_connect ("host=localhost port=5432 dbname=$database");
if (!$db_conn): ?>
    &lt;H1>Failed connecting to postgres database &lt;?php echo $database ?>&lt;/H1> &lt;?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."&lt;BR>";
    $row++;
endwhile; ?>

&lt;PRE>&lt;?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"; ?>
&lt;/PRE> &lt;?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>int <parameter>result</parameter></paramdef>
      <paramdef>int <parameter>row</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para> 
     Returns: An array that corresponds to the fetched row, or &false;
     if there are no more rows.
    </para>
    <para>
     <function>pg_fetch_row</function> fetches one row of data from
     the result associated with the specified result identifier.  The
     row is returned as an array.  Each result column is stored in an
     array offset, starting at offset 0.
    </para>
    <para>
     See also: <function>pg_fetch_array</function>,
     <function>pg_fetch_object</function>,
     <function>pg_result</function>.
     <example>
      <title>Postgres fetch row</title>
      <programlisting role="php">
&lt;?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&lt;$num; $i++) {
  $r = pg_fetch_row($result, $i);

  for ($j=0; $j&lt;count($r); $j++) {
    echo "$r[$j]&amp;nbsp;";
  }

  echo "&lt;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>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>row</parameter></paramdef>
      <paramdef>mixed <parameter>field</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Test if a field is &null; or not. Returns 0 if the field in the
     given row is not &null;. Returns 1 if the field in the given row is
     &null;. Field can be specified as number or fieldname. 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>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>field_number</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_fieldname</function> will return the name of the
     field occupying the given column number in the given PostgreSQL
     result identifier.  Field numbering starts from 0.
    </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>int <parameter>result_id</parameter></paramdef>
      <paramdef>string <parameter>field_name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_fieldnum</function> will return the number of the
     column slot that corresponds to the named field in the given
     PosgreSQL result identifier.  Field numbering starts at 0.  This
     function will return -1 on error.
    </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>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>row_number</parameter></paramdef>
      <paramdef>string <parameter>field_name</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_fieldprtlen</function> will return the actual
     printed length (number of characters) of a specific value in a
     PostgreSQL result.  Row numbering starts at 0.  This function
     will return -1 on an error.
    </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>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>field_number</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_fieldsize</function> will return the internal
     storage size (in bytes) of the field number in the given
     PostgreSQL result. Field numbering starts at 0. A field size of
     -1 indicates a variable length field. This function will return
     &false; on error.
    </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>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>field_number</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_fieldtype</function> will return a string containing
     the type name of the given field in the given PostgreSQL result
     identifier.  Field numbering starts at 0.
    </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>int <function>pg_freeresult</function></funcdef>
      <paramdef>int <parameter>result_id</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 result identifier as
     an argument and the associated result memory will be freed.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.pg-getlastoid">
   <refnamediv>
    <refname>pg_getlastoid</refname> 
    <refpurpose>Returns the last object identifier</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>pg_getlastoid</function></funcdef>
      <paramdef>int <parameter>result_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_getlastoid</function> can be used to retrieve the
     <varname>oid</varname> assigned to an inserted tuple if the
     result identifier is used from the last command sent via
     <function>pg_exec</function> and was an SQL INSERT.  This
     function will return a positive integer if there was a valid
     <varname>oid</varname>.  It will return -1 if an error occured or
     the last command sent via <function>pg_exec</function> was not an
     INSERT.
    </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>int <parameter>connection_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_host</function> will return the host name of the
     given PostgreSQL connection identifier is connected to.
    </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>void <function>pg_loclose</function></funcdef>
      <paramdef>int <parameter>fd</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_loclose</function> closes an Inversion Large
     Object. <parameter>Fd</parameter> is a file descriptor for the
     large object from <function>pg_loopen</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>int <parameter>conn</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>conn</parameter> specifies a valid database
     connection.  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).
    </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>int
       <parameter>file</parameter>
      </paramdef>
      <paramdef>int
       <parameter><optional>connection_id</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The <parameter>oid</parameter> argument specifies the object id
     of the large object to export and the
     <parameter>filename</parameter> argument specifies the pathname
     of the file. Returns &false; if an error occurred, &true;
     otherwise. Remember that handling large objects in PostgreSQL
     must happen inside a transaction.
    </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>int
       <parameter>file</parameter>
      </paramdef>
      <paramdef>int
       <parameter><optional>connection_id</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The <parameter>filename</parameter> argument specifies the
     pathname of the file to be imported as a large object. Returns
     &false; if an error occurred, object id of the just created large
     object otherwise. Remember that handling large objects in
     PostgreSQL must happen inside a transaction.
    </para>
	&note.sm.uidcheck;
   </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>int <function>pg_loopen</function></funcdef>
      <paramdef>int <parameter>conn</parameter></paramdef>
      <paramdef>int <parameter>objoid</parameter></paramdef>
      <paramdef>string <parameter>mode</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_loopen</function> open an Inversion Large Object and
     returns file descriptor of the large object. The file descriptor
     encapsulates information about the connection. Do not close the
     connection before closing the large object file descriptor.
     <parameter>objoid</parameter> specifies a valid large object oid
     and <parameter>mode</parameter> can be either "r", "w", or "rw".
    </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>int <parameter>fd</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>fd</parameter> specifies a valid large object file
     descriptor and<parameter>len</parameter> specifies the maximum
     allowable size of the large object segment.
    </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>void <function>pg_loreadall</function></funcdef>
      <paramdef>int <parameter>fd</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.
    </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>void <function>pg_lounlink</function></funcdef>
      <paramdef>int <parameter>conn</parameter></paramdef>
      <paramdef>int <parameter>lobjid</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_lounlink</function> deletes a large object with the
     <parameter>lobjid</parameter> identifier for that large object.
    </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>int <parameter>fd</parameter></paramdef>
      <paramdef>string <parameter>buf</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_lowrite</function> writes at most to a large object
     from a variable <parameter>buf</parameter> and returns the number
     of bytes actually written, or &false; in the case of an error.
     <parameter>fd</parameter> is a file descriptor for the large
     object from <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>int <parameter>result_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_numfields</function> will return the number of
     fields (columns) in a PostgreSQL result.  The argument is a valid
     result identifier 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>int <parameter>result_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_numrows</function> will return the number of rows in a
     PostgreSQL result.  The argument is a valid result identifier
     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>int <parameter>connection_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_options</function> will return a string containing
     the options specified on the given PostgreSQL connection
     identifier.
    </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>conn_string</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Returns a connection index on success, or &false; if the connection
     could not be made.  Opens a connection to a PostgreSQL database.
     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>
    <para>
     This function returns a connection index that is needed by other
     PostgreSQL functions. You can have multiple connections open at
     once.
    </para>
    <para>
     The previous syntax of:
     <command>$conn = pg_pconnect ("host", "port", "options", "tty",
    "dbname")
     </command>
     has been deprecated.
    </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>int <parameter>connection_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_port</function> will return the port number that the
     given PostgreSQL connection identifier 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_id</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. 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">
&lt;?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 identifier</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>mixed <function>pg_result</function></funcdef>
      <paramdef>int <parameter>result_id</parameter></paramdef>
      <paramdef>int <parameter>row_number</parameter></paramdef>
      <paramdef>mixed <parameter>fieldname</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_result</function> will return values from a result
     identifier produced by <function>pg_Exec</function>.  The
     <parameter>row_number</parameter> and
     <parameter>fieldname</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... -->
     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>int 
       <parameter><optional>connection</optional></parameter>
      </paramdef>
      <paramdef>string <parameter>encoding</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The function set 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.
     </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>int 
       <parameter><optional>connection</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     The functions 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>filename</parameter>
      </paramdef>
      <paramdef>string
       <parameter><optional>mode</optional></parameter>
      </paramdef>
      <paramdef>int
       <parameter><optional>connection</optional></parameter>
      </paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     Enables tracing of the PostgreSQL frontend/backend communication
     to a debugging file. 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.
    </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>
     Returns &true; if <parameter>filename</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>int <parameter>connection_id</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>pg_tty</function> will return the tty name that server
     side debugging output is sent to on the given PostgreSQL
     connection identifier.
    </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>int
       <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
-->