chriskl Mon Jul 4 03:42:00 2005 EDT
Modified files:
/phpdoc/en/reference/pgsql/functions pg-end-copy.xml
pg-put-line.xml pg-query.xml
pg-send-query.xml
Log:
Another four pgsql functions documented in the new style. Only a couple left
now.
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-end-copy.xml?r1=1.4&r2=1.5&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-end-copy.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-end-copy.xml:1.4
phpdoc/en/reference/pgsql/functions/pg-end-copy.xml:1.5
--- phpdoc/en/reference/pgsql/functions/pg-end-copy.xml:1.4 Fri Mar 11
11:03:25 2005
+++ phpdoc/en/reference/pgsql/functions/pg-end-copy.xml Mon Jul 4 03:42:00 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.4 $ -->
+<!-- $Revision: 1.5 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.82 -->
<refentry id="function.pg-end-copy">
<refnamediv>
@@ -19,7 +19,55 @@
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 with the frontend and will report an error. &return.success;
+ sync with the frontend and will report an error.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.success;
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_end_copy</function> example</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>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-put-line.xml?r1=1.7&r2=1.8&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-put-line.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-put-line.xml:1.7
phpdoc/en/reference/pgsql/functions/pg-put-line.xml:1.8
--- phpdoc/en/reference/pgsql/functions/pg-put-line.xml:1.7 Fri Mar 11
11:03:26 2005
+++ phpdoc/en/reference/pgsql/functions/pg-put-line.xml Mon Jul 4 03:42:00 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.20 -->
<refentry id="function.pg-put-line">
<refnamediv>
@@ -20,16 +20,23 @@
</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. &return.success;
+ to the PostgreSQL backend server. This is needed in conjunction
+ with PostgreSQL's <literal>COPY FROM</literal> command.
+ </para>
+ <para><literal>COPY</literal> is a high-speed data loading interface
+ supported by PostgreSQL. Data is passed in without being parsed,
+ and in a single transaction.
+ </para>
+ <para>
+ An alternative to using raw <function>pg_put_line</function> commands
+ is to use <function>pg_copy_from</function>. This is a far simpler
+ interface.
</para>
<note>
<para>
The application must explicitly send the two characters "\."
on the last line to indicate to the backend that it has finished
- sending its data.
+ sending its data, before issuing <function>pg_end_copy</function>.
</para>
</note>
<warning>
@@ -43,11 +50,46 @@
</warning>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>data</parameter></term>
+ <listitem>
+ <para>
+ A line of text to be sent directly to the PostgreSQL backend. A
<literal>NULL</literal>
+ terminator is added automatically.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ &return.success;
+ </para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>High-speed insertion of data into a table</title>
+ <title><function>pg_put_line</function> example</title>
<programlisting role="php">
<![CDATA[
<?php
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-query.xml?r1=1.10&r2=1.11&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-query.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-query.xml:1.10
phpdoc/en/reference/pgsql/functions/pg-query.xml:1.11
--- phpdoc/en/reference/pgsql/functions/pg-query.xml:1.10 Thu Apr 21
05:29:07 2005
+++ phpdoc/en/reference/pgsql/functions/pg-query.xml Mon Jul 4 03:42:00 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-query">
<refnamediv>
@@ -19,33 +19,20 @@
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_query</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
+ <function>pg_query</function> executes the <parameter>query</parameter>
+ on the specified database <parameter>connection</parameter>.
+ </para>
+ <para>
+ If an error occurs, and &false; is returned, details of the error can
be retrieved using the <function>pg_last_error</function>
- function if connection is valid.
- <function>pg_query</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>.
+ function if the connection is valid.
+ </para>
+ <para>
<note>
<simpara>
- <parameter>connection</parameter> is an optional parameter for
- <function>pg_query</function>. If
- <parameter>connection</parameter> is not set, 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.
+ is not recommended, since it can be the cause of hard to find
+ bugs in scripts.
</simpara>
</note>
</para>
@@ -53,11 +40,78 @@
<para>
This function used to be called <function>pg_exec</function>.
<function>pg_exec</function> is still available for compatibility
- reasons but users are encouraged to use the newer name.
+ reasons, but users are encouraged to use the newer name.
</para>
</note>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ The SQL statement or statements to be executed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ A query result resource on success, or &false; on failure.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_query</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn = pg_pconnect("dbname=publisher");
+if (!$conn) {
+ echo "An error occured.\n";
+ exit;
+}
+
+$result = pg_query($conn, "SELECT author, email FROM authors");
+if (!$result) {
+ echo "An error occured.\n";
+ exit;
+}
+
+while ($row = pg_fetch_row($result)) {
+ echo "Author: $row[0] E-mail: $row[1]";
+ echo "<br />\n";
+}
+
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
<refsect1 role="seealso">
&reftitle.seealso;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-send-query.xml?r1=1.12&r2=1.13&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-send-query.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-send-query.xml:1.12
phpdoc/en/reference/pgsql/functions/pg-send-query.xml:1.13
--- phpdoc/en/reference/pgsql/functions/pg-send-query.xml:1.12 Mon Jul 4
01:01:28 2005
+++ phpdoc/en/reference/pgsql/functions/pg-send-query.xml Mon Jul 4
03:42:00 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
+<!-- $Revision: 1.13 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id='function.pg-send-query'>
<refnamediv>
@@ -21,29 +21,66 @@
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_send_query</function> send asynchronous query to the
+ <function>pg_send_query</function> sends a query or queries asynchronously
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 blocked
- while query is executing. Use
- <function>pg_connection_busy</function> to check connection is
- busy (i.e. query is executing). Query may be cancelled by calling
+ <function>pg_query</function>, it can send multiple queries at once to
+ PostgreSQL and get the results one by one using
+ <function>pg_get_result</function>.
+ </para>
+ <para>
+ Script execution is not blocked while the queries are executing. Use
+ <function>pg_connection_busy</function> to check if the connection is
+ busy (i.e. the query is executing). Queries may be cancelled using
<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.
+ Although the user can send multiple queries at once, multiple queries
+ cannot be sent over a busy connection. If a query is sent while
+ the connection is busy, it waits until the last query is finished and
+ discards all its results.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource. When
+ <parameter>connection</parameter> is not present, the default
connection
+ is used. The default connection is the last connection made by
+ <function>pg_connect</function> or <function>pg_pconnect</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ The SQL statement or statements to be executed.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</para>
</refsect1>
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>&return.success;</para>
+ <para>
+ Use <function>pg_get_result</function> to determine the query result.
+ </para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
- <title>Asynchronous Queries</title>
+ <title><function>pg_send_query</function> example</title>
<programlisting role="php">
<