yohgaki Mon Apr 8 21:59:28 2002 EDT
Modified files:
/phpdoc/en/functions pgsql.xml
Log:
Change function listing order.
Index: phpdoc/en/functions/pgsql.xml
diff -u phpdoc/en/functions/pgsql.xml:1.81 phpdoc/en/functions/pgsql.xml:1.82
--- phpdoc/en/functions/pgsql.xml:1.81 Mon Apr 8 21:36:10 2002
+++ phpdoc/en/functions/pgsql.xml Mon Apr 8 21:59:27 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.81 $ -->
+<!-- $Revision: 1.82 $ -->
<reference id="ref.pgsql">
<title>PostgreSQL functions</title>
<titleabbrev>PostgreSQL</titleabbrev>
@@ -225,42 +225,6 @@
- <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-affected-rows">
<refnamediv>
<refname>pg_affected_rows</refname>
@@ -376,22 +340,258 @@
- <refentry id="function.pg-dbname">
+ <refentry id="function.pg-pconnect">
<refnamediv>
- <refname>pg_dbname</refname>
- <refpurpose>Get the database name</refpurpose>
+ <refname>pg_pconnect</refname>
+ <refpurpose>Open a persistent PostgreSQL connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>string</type><methodname>pg_dbname</methodname>
+ <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>
+ &php.ini; directive must be set to "On". (Default is On)
+ Max number of persistent connection can be defined by <link
+ linkend="ini.pgsql.max-persistent">pgsql.max_persistent</link>
+ &php.ini; directive. (Default is -1 which is no limit) Total number
+ of connection can be set by <link
+ linkend="ini.pgsql.max-links">pgsql.max_links</link>
+ &php.ini; directive.
+ </para>
+ <para>
+ <function>pg_close</function> will not close persistent links
+ generated by <function>pg_pconnect</function>.
+ </para>
+ <para>
+ See also <function>pg_connect</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+
+
+ <refentry id='function.pg-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_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.
+ <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_OK</literal>
+ or <literal>PGSQL_CONNECTION_BAD</literal>.
+ </para>
+ <para>
+ See also <function>pg_connection_busy</function>
+ </para>
+ </refsect1>
+ </refentry>
+
+
+
+ <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-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>
@@ -419,8 +619,59 @@
otherwise it returns &false;.
</para>
<para>
- For further details and an example, see also
- <function>pg_put_line</function>.
+ For further details and an example, see also
+ <function>pg_put_line</function>.
+ </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_query($conn, "create table bar (a int4, b char(16), d float8)");
+ pg_query($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>
@@ -461,6 +712,97 @@
</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 the PostgreSQL server specified by
+ <parameter>connection</parameter>. The PostgreSQL server sends notice
+ messages in several cases, e.g. if the transactions can't be continued.
+ With <function>pg_last_notice</function>, you can avoid issuing useless
+ queries, by checking whether the notice is related to the transaction
+ or not.
+ </para>
+ <warning>
+ <para>
+ This function is EXPERIMENTAL and it is not fully implemented
+ yet. <function>pg_last_notice</function> was added in PHP
+ 4.0.6. However, PHP 4.0.6 has problem with notice message
+ handling. Use of the PostgreSQL module with PHP 4.0.6 is not
+ recommended even if you are not using
+ <function>pg_last_notice</function>.
+ </para>
+ <para>
+ This function is fully implemented in PHP 4.3.0. PHP earlier than
+ PHP 4.3.0 ignores database connection parameter.
+ </para>
+ </warning>
+ <para>
+ Notice message tracking can be set to optional by setting 1 for
+ <literal>pgsql.ignore_notice</literal> ini from PHP 4.3.0.
+ </para>
+ <para>
+ Notice message logging can be set to optional by setting 0 for
+ <literal>pgsql.log_notice</literal> ini from PHP 4.3.0. Unless
+ <literal>pgsql.ignore_notice</literal> is set to 0, notice message
+ cannot be logged.
+ </para>
+ <para>
+ See also <function>pg_query</function> and
+ <function>pg_last_error</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+
+
+ <refentry id="function.pg-last-oid">
+ <refnamediv>
+ <refname>pg_last_oid</refname>
+ <refpurpose>Returns the last object's oid</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>int</type><methodname>pg_last_oid</methodname>
+ <methodparam><type>resource</type><parameter>result</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ <function>pg_last_oid</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_query</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_query</function> was not an INSERT or INSERT is
+ failed.
+ </para>
+ <note>
+ <para>
+ This function used called <literal>pg_getlastoid()</literal>.
+ </para>
+ </note>
+ <para>
+ See also <function>pg_query</function>.
+ </para>
+ </refsect1>
+ </refentry>
+
+
+
<refentry id="function.pg-query">
<refnamediv>
<refname>pg_query</refname>
@@ -725,6 +1067,50 @@
+ <refentry id="function.pg-fetch-result">
+ <refnamediv>
+ <refname>pg_fetch_result</refname>
+ <refpurpose>Returns values from a result resource</refpurpose>
+ </refnamediv>
+ <refsect1>
+ <title>Description</title>
+ <methodsynopsis>
+ <type>mixed</type><methodname>pg_fetch_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_fetch_result</function> returns values from a
+ <parameter>result</parameter> resource returned by
+ <function>pg_query</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. [EMAIL PROTECTED] -->
+ 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-fetch-row">
<refnamediv>
<refname>pg_fetch_row</refname>
@@ -963,180 +1349,64 @@
<refnamediv>
<refname>pg_field_type</refname>
<refpurpose>
- Returns the type name for the corresponding field number
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>string</type><methodname>pg_field_type</methodname>
- <methodparam><type>resource</type><parameter>result</parameter></methodparam>
- <methodparam><type>int</type><parameter>field_number</parameter></methodparam>
- </methodsynopsis>
- <para>
- <function>pg_field_type</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>
- <note>
- <para>
- This function used called <literal>pg_field_type()</literal>.
- </para>
- </note>
- <para>
- See also <function>pg_field_len</function> and
<function>pg_field_name</function>.
- </para>
- </refsect1>
- </refentry>
-
-
-
- <refentry id="function.pg-free-result">
- <refnamediv>
- <refname>pg_free_result</refname>
- <refpurpose>Free result memory</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>bool</type><methodname>pg_free_result</methodname>
- <methodparam><type>resource</type><parameter>result</parameter></methodparam>
- </methodsynopsis>
- <para>
- <function>pg_free_result</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_free_result</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>
- <note>
- <para>
- This function used called <literal>pg_field_len()</literal>.
- </para>
- </note>
- <para>
- See also <function>pg_query</function>.
- </para>
- </refsect1>
- </refentry>
-
-
-
- <refentry id="function.pg-last-oid">
- <refnamediv>
- <refname>pg_last_oid</refname>
- <refpurpose>Returns the last object's oid</refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <methodsynopsis>
- <type>int</type><methodname>pg_last_oid</methodname>
- <methodparam><type>resource</type><parameter>result</parameter></methodparam>
- </methodsynopsis>
- <para>
- <function>pg_last_oid</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_query</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_query</function> was not an INSERT or INSERT is
- failed.
- </para>
- <note>
- <para>
- This function used called <literal>pg_getlastoid()</literal>.
- </para>
- </note>
- <para>
- See also <function>pg_query</function>.
- </para>
- </refsect1>
- </refentry>
-
-
-
- <refentry id="function.pg-host">
- <refnamediv>
- <refname>pg_host</refname>
- <refpurpose>
- Returns the host name associated with the connection
+ Returns the type name for the corresponding field number
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>string</type><methodname>pg_host</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <type>string</type><methodname>pg_field_type</methodname>
+ <methodparam><type>resource</type><parameter>result</parameter></methodparam>
+ <methodparam><type>int</type><parameter>field_number</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_host</function> returns the host name of the given
- PostgreSQL <parameter>connection</parameter> resource is
- connected to.
+ <function>pg_field_type</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>
+ <note>
+ <para>
+ This function used called <literal>pg_field_type()</literal>.
+ </para>
+ </note>
<para>
- See also <function>pg_connect</function> and
- <function>pg_pconnect</function>.
+ See also <function>pg_field_len</function> and
+<function>pg_field_name</function>.
</para>
</refsect1>
</refentry>
- <refentry id="function.pg-last-notice">
+ <refentry id="function.pg-free-result">
<refnamediv>
- <refname>pg_last_notice</refname>
- <refpurpose>
- Returns the last notice message from PostgreSQL server
- </refpurpose>
+ <refname>pg_free_result</refname>
+ <refpurpose>Free result memory</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>string</type><methodname>pg_last_notice</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <type>bool</type><methodname>pg_free_result</methodname>
+ <methodparam><type>resource</type><parameter>result</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_last_notice</function> returns the last notice
- message from the PostgreSQL server specified by
- <parameter>connection</parameter>. The PostgreSQL server sends notice
- messages in several cases, e.g. if the transactions can't be continued.
- With <function>pg_last_notice</function>, you can avoid issuing useless
- queries, by checking whether the notice is related to the transaction
- or not.
+ <function>pg_free_result</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_free_result</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>
- <warning>
- <para>
- This function is EXPERIMENTAL and it is not fully implemented
- yet. <function>pg_last_notice</function> was added in PHP
- 4.0.6. However, PHP 4.0.6 has problem with notice message
- handling. Use of the PostgreSQL module with PHP 4.0.6 is not
- recommended even if you are not using
- <function>pg_last_notice</function>.
- </para>
+ <note>
<para>
- This function is fully implemented in PHP 4.3.0. PHP earlier than
- PHP 4.3.0 ignores database connection parameter.
+ This function used called <literal>pg_field_len()</literal>.
</para>
- </warning>
- <para>
- Notice message tracking can be set to optional by setting 1 for
- <literal>pgsql.ignore_notice</literal> ini from PHP 4.3.0.
- </para>
- <para>
- Notice message logging can be set to optional by setting 0 for
- <literal>pgsql.log_notice</literal> ini from PHP 4.3.0. Unless
- <literal>pgsql.ignore_notice</literal> is set to 0, notice message
- cannot be logged.
- </para>
+ </note>
<para>
- See also <function>pg_query</function> and
- <function>pg_last_error</function>.
+ See also <function>pg_query</function>.
</para>
</refsect1>
</refentry>
@@ -1603,99 +1873,27 @@
- <refentry id="function.pg-options">
+ <refentry id="function.pg-host">
<refnamediv>
- <refname>pg_options</refname>
- <refpurpose>Get the options associated with the connection</refpurpose>
+ <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_options</methodname>
+ <type>string</type><methodname>pg_host</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>
- &php.ini; directive must be set to "On". (Default is On)
- Max number of persistent connection can be defined by <link
- linkend="ini.pgsql.max-persistent">pgsql.max_persistent</link>
- &php.ini; directive. (Default is -1 which is no limit) Total number
- of connection can be set by <link
- linkend="ini.pgsql.max-links">pgsql.max_links</link>
- &php.ini; directive.
- </para>
- <para>
- <function>pg_close</function> will not close persistent links
- generated by <function>pg_pconnect</function>.
+ <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>.
+ See also <function>pg_connect</function> and
+ <function>pg_pconnect</function>.
</para>
</refsect1>
</refentry>
@@ -1725,95 +1923,43 @@
- <refentry id="function.pg-put-line">
+ <refentry id="function.pg-dbname">
<refnamediv>
- <refname>pg_put_line</refname>
- <refpurpose>Send a NULL-terminated string to PostgreSQL backend</refpurpose>
+ <refname>pg_dbname</refname>
+ <refpurpose>Get the database name</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>
+ <type>string</type><methodname>pg_dbname</methodname>
+
+<methodparam><type>resource</type><parameter>connection</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_query($conn, "create table bar (a int4, b char(16), d float8)");
- pg_query($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>
+ <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-fetch-result">
+ <refentry id="function.pg-options">
<refnamediv>
- <refname>pg_fetch_result</refname>
- <refpurpose>Returns values from a result resource</refpurpose>
+ <refname>pg_options</refname>
+ <refpurpose>Get the options associated with the connection</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<methodsynopsis>
- <type>mixed</type><methodname>pg_fetch_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_fetch_result</function> returns values from a
- <parameter>result</parameter> resource returned by
- <function>pg_query</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. [EMAIL PROTECTED] -->
- 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.
+ <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>
@@ -1907,6 +2053,29 @@
+ <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-trace">
<refnamediv>
<refname>pg_trace</refname>
@@ -1952,29 +2121,6 @@
- <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>
@@ -2029,6 +2175,37 @@
+ <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>
+
+
+
<refentry id='function.pg-result-status'>
<refnamediv>
<refname>pg_result_status</refname>
@@ -2131,148 +2308,6 @@
- <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_OK</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>
@@ -2345,37 +2380,6 @@
<para>
See also <function>pg_escape_bytea</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>
