yohgaki Sun Jan 20 04:03:44 2002 EDT
Modified files:
/phpdoc/en/functions pgsql.xml
Log:
Added renamed function list.
Added new functions descriptions.
Removed obsolete function refs created by mistake.
Added description for optional row parameters for pg_fetch_*() 4.1.0 or later.
Index: phpdoc/en/functions/pgsql.xml
diff -u phpdoc/en/functions/pgsql.xml:1.65 phpdoc/en/functions/pgsql.xml:1.66
--- phpdoc/en/functions/pgsql.xml:1.65 Fri Jan 18 17:49:45 2002
+++ phpdoc/en/functions/pgsql.xml Sun Jan 20 04:03:41 2002
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.65 $ -->
+<!-- $Revision: 1.66 $ -->
<reference id="ref.pgsql">
<title>PostgreSQL functions</title>
<titleabbrev>PostgreSQL</titleabbrev>
@@ -21,9 +21,41 @@
from 4.2.0, but they may be deleted in the future. CVS version
has new function names.
</para>
+ <example>
+ <title>Function names changed</title>
+ <programlisting role="php">
+<![CDATA[
+OLD NAME NEW NAME
+pg_exec pg_query
+getlastoid pg_last_oid
+pg_cmdtuples pg_affected_rows
+pg_errormessage pg_last_error
+pg_numrows pg_num_rows
+pg_numfields pg_num_fields
+pg_fieldname pg_field_name
+pg_fieldsize pg_field_size
+pg_fieldtype pg_field_type
+pg_fieldnum pg_field_num
+pg_fieldprtlen pg_field_prtlen
+pg_fieldisnull pg_field_is_null
+pg_freeresult pg_free_result
+pg_result pg_fetch_result
+pg_loreadall pg_lo_read_all
+pg_locreate pg_lo_create
+pg_lounlink pg_lo_unlink
+pg_loopen pg_lo_open
+pg_loclose pg_lo_close
+pg_loread pg_lo_read
+pg_lowrite pg_lo_write
+pg_loimport pg_lo_import
+pg_loexport pg_lo_export
+]]>
+ </programlisting>
+ </example>
<para>
- Obsolete pg_connect()/pg_pconnect() may be depreciated to support
- async connect feature in the future.
+ Obsolete pg_connect()/pg_pconnect() syntax will be depreciated to
+ support async connect feature in the future. Please use
+ connection string for pg_connect() and pg_pconnect().
</para>
</warning>
<para>
@@ -65,7 +97,7 @@
</para>
<para>
Since version 6.3 (03/02/1998) PostgreSQL uses unix domain sockets
- by default. TCP port will not be opened by default. A table is
+ by default. TCP port will NOT be opened by default. A table is
shown below describing these new connection possibilities. This
socket will be found in <filename>/tmp/.s.PGSQL.5432</filename>.
This option can be enabled with the '-i' flag to
@@ -169,6 +201,8 @@
</para>
</partintro>
+
+
<refentry id="function.pg-close">
<refnamediv>
<refname>pg_close</refname>
@@ -205,6 +239,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-cmdtuples">
<refnamediv>
<refname>pg_cmdtuples</refname>
@@ -243,6 +279,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-connect">
<refnamediv>
<refname>pg_connect</refname>
@@ -315,6 +353,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-dbname">
<refnamediv>
<refname>pg_dbname</refname>
@@ -337,6 +377,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-end-copy">
<refnamediv>
<refname>pg_end_copy</refname>
@@ -368,6 +410,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-errormessage">
<refnamediv>
<refname>pg_errormessage</refname>
@@ -455,6 +499,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fetch-array">
<refnamediv>
<refname>pg_fetch_array</refname>
@@ -541,9 +587,16 @@
</programlisting>
</example>
</para>
+ <note>
+ <para>
+ From 4.1.0, <parameter>row</parameter> became optional.
+ </para>
+ </note>
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fetch-object">
<refnamediv>
<refname>pg_fetch_object</refname>
@@ -649,9 +702,16 @@
</programlisting>
</example>
</para>
+ <note>
+ <para>
+ From 4.1.0, <parameter>row</parameter> became optional.
+ </para>
+ </note>
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fetch-row">
<refnamediv>
<refname>pg_fetch_row</refname>
@@ -719,9 +779,16 @@
</programlisting>
</example>
</para>
+ <note>
+ <para>
+ From 4.1.0, <parameter>row</parameter> became optional.
+ </para>
+ </note>
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldisnull">
<refnamediv>
<refname>pg_fieldisnull</refname>
@@ -747,6 +814,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldname">
<refnamediv>
<refname>pg_fieldname</refname>
@@ -773,6 +842,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldnum">
<refnamediv>
<refname>pg_fieldnum</refname>
@@ -790,7 +861,7 @@
<para>
<function>pg_fieldnum</function> will return the number of the
column (field) slot that corresponds to the
- <parameter>field_name</parameter> in the given PosgreSQL
+ <parameter>field_name</parameter> in the given PostgreSQL
<parameter>result</parameter> resource. Field numbering starts
at 0. This function will return -1 on error.
</para>
@@ -800,6 +871,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldprtlen">
<refnamediv>
<refname>pg_fieldprtlen</refname>
@@ -827,6 +900,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldsize">
<refnamediv>
<refname>pg_fieldsize</refname>
@@ -856,6 +931,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-fieldtype">
<refnamediv>
<refname>pg_fieldtype</refname>
@@ -884,6 +961,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-freeresult">
<refnamediv>
<refname>pg_freeresult</refname>
@@ -914,6 +993,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-getlastoid">
<refnamediv>
<refname>pg_getlastoid</refname>
@@ -943,6 +1024,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-host">
<refnamediv>
<refname>pg_host</refname>
@@ -970,6 +1053,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-last-notice">
<refnamediv>
<refname>pg_last_notice</refname>
@@ -1012,6 +1097,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loclose">
<refnamediv>
<refname>pg_loclose</refname>
@@ -1042,6 +1129,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-locreate">
<refnamediv>
<refname>pg_locreate</refname>
@@ -1075,6 +1164,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loexport">
<refnamediv>
<refname>pg_loexport</refname>
@@ -1112,6 +1203,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loimport">
<refnamediv>
<refname>pg_loimport</refname>
@@ -1146,6 +1239,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loopen">
<refnamediv>
<refname>pg_loopen</refname>
@@ -1186,6 +1281,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loread">
<refnamediv>
<refname>pg_loread</refname>
@@ -1218,6 +1315,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-loreadall">
<refnamediv>
<refname>pg_loreadall</refname>
@@ -1250,6 +1349,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-lounlink">
<refnamediv>
<refname>pg_lounlink</refname>
@@ -1280,6 +1381,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-lowrite">
<refnamediv>
<refname>pg_lowrite</refname>
@@ -1312,6 +1415,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-numfields">
<refnamediv>
<refname>pg_numfields</refname>
@@ -1339,6 +1444,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-numrows">
<refnamediv>
<refname>pg_numrows</refname>
@@ -1372,6 +1479,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-options">
<refnamediv>
<refname>pg_options</refname>
@@ -1474,6 +1583,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-port">
<refnamediv>
<refname>pg_port</refname>
@@ -1497,6 +1608,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-put-line">
<refnamediv>
<refname>pg_put_line</refname>
@@ -1550,6 +1663,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-result">
<refnamediv>
<refname>pg_result</refname>
@@ -1594,6 +1709,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-set-client-encoding">
<refnamediv>
<refname>pg_set_client_encoding</refname>
@@ -1617,11 +1734,12 @@
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.
+ <parameter>encoding</parameter> is the client encoding and can be
+ either : SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE,
+ MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5,
+ WIN1250. Available encoding depends on your PostgreSQL and libpq
+ version. Refer to PostgreSQL manual for supported encodings for
+ your PostgreSQL.
</para>
<note>
<para>
@@ -1640,6 +1758,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-client-encoding">
<refnamediv>
<refname>pg_client_encoding</refname>
@@ -1684,6 +1804,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-trace">
<refnamediv>
<refname>pg_trace</refname>
@@ -1735,6 +1857,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-tty">
<refnamediv>
<refname>pg_tty</refname>
@@ -1758,6 +1882,8 @@
</refsect1>
</refentry>
+
+
<refentry id="function.pg-untrace">
<refnamediv>
<refname>pg_untrace</refname>
@@ -1787,6 +1913,8 @@
</refsect1>
</refentry>
+
+
<refentry id='function.pg-get-result'>
<refnamediv>
<refname>pg_get_result</refname>
@@ -1803,53 +1931,49 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_get_result</function> get result resource from async
+ query executed by
+ <function>pg_send_query</function>. <function>pg_send_query</function>
+ can send multiple queries to PostgreSQL server and
+ <function>pg_get_result</function> is used to get query result
+ one by one. It returns result resource. If there is no more
+ results, it returns &false;.
</para>
</refsect1>
</refentry>
- <refentry id='function.pg-request-cancel'>
+
+
+ <refentry id='function.pg-result-status'>
<refnamediv>
- <refname>pg_request_cancel</refname>
+ <refname>pg_result_status</refname>
<refpurpose>
- Cancel request
+ Get status of query result
</refpurpose>
</refnamediv>
<refsect1>
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>bool <function>pg_request_cancel</function></funcdef>
- <paramdef>resource
<parameter><optional>connection</optional></parameter></paramdef>
+ <funcdef>int <function>pg_result_status</function></funcdef>
+ <paramdef>resource <parameter>result</parameter></paramdef>
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_result_status</function> returns status of result
+ resource. Possible retun values are PGSQL_EMPTY_QUERY,
+ PGSQL_COMMAND_OK, PGSQL_TUPLES_OK, PGSQL_COPY_TO,
+ PGSQL_COPY_FROM, PGSQL_BAD_RESPONSE, PGSQL_NONFATAL_ERROR and
+ PGSQL_FATAL_ERROR.
</para>
- </refsect1>
- </refentry>
-
- <refentry id='function.pg-is-busy'>
- <refnamediv>
- <refname>pg_is_busy</refname>
- <refpurpose>
- Get connection is busy or not
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>bool <function>pg_is_busy</function></funcdef>
- <paramdef>resource
<parameter><optional>connection</optional></parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
<para>
- &warn.undocumented.func;
+ See also <function>pgsql_connection_status</function>.
</para>
</refsect1>
</refentry>
+
+
<refentry id='function.pg-send-query'>
<refnamediv>
<refname>pg_send_query</refname>
@@ -1871,16 +1995,38 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_send_query</function> send asynchronous query to the
+ <parameter>connection</parameter>. Unlike
+ <function>pg_query</function>, it can send multiple query to
+ PostgreSQL and get the result one by one using
+ <function>pg_get_result</function>. Script execution is not block
+ while query is executing. Use
+ <function>pg_connection_busy</function> to check connection is
+ busy (i.e. query is executing) Query may be canceled by calling
+ <function>pg_cancel_query</function>.
+ </para>
+ <para>
+ Although, user can send multiple query at once. User cannot send
+ multiple query over busy connection. If query is sent while
+ connection is busy, it waits until last query is finished and
+ discards all result.
+ </para>
+ <para>
+ See also <function>pg_query</function>,
+ <function>pg_cancel_query</function>,
+ <function>pg_get_result</function> and
+ <function>pg_connection_busy</function>
</para>
</refsect1>
</refentry>
+
+
<refentry id='function.pg-cancel-query'>
<refnamediv>
<refname>pg_cancel_query</refname>
<refpurpose>
- Cancel request
+ Cancel async query
</refpurpose>
</refnamediv>
<refsect1>
@@ -1892,7 +2038,14 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_cancel_query</function> cancel asynchronous query sent by
+ <function>pg_send_query</function>. You cannot cancel query executed by
+ <function>pg_query</function>.
+ </para>
+ <para>
+ See also <function>pg_send_query</function>,
+ <function>pg_cancel_result</function> and
+ <function>pg_connection_busy</function>
</para>
</refsect1>
</refentry>
@@ -1915,7 +2068,15 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <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>
@@ -1938,7 +2099,15 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <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>
@@ -1961,7 +2130,12 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_connection_status</function> returns a connection
+ status. Possible status is <literal>PGSQL_CONNECTION_O</literal>
+ or <literal>PGSQL_CONNECTION_BAD</literal>.
+ </para>
+ <para>
+ See also <function>pg_connection_busy</function>
</para>
</refsect1>
</refentry>
@@ -1972,7 +2146,7 @@
<refnamediv>
<refname>pg_copy_from</refname>
<refpurpose>
- No description given yet
+ Copy table from array
</refpurpose>
</refnamediv>
<refsect1>
@@ -1988,7 +2162,11 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <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>
@@ -1999,7 +2177,7 @@
<refnamediv>
<refname>pg_copy_to</refname>
<refpurpose>
- Send null-terminated string to backend server
+ Copy table to array
</refpurpose>
</refnamediv>
<refsect1>
@@ -2014,7 +2192,12 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <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>
@@ -2037,7 +2220,16 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_escape_string</function> escapes string for
+ bytea datatype. It returns escaped string.
+ </para>
+ <note>
+ <para>
+ This function is requires PostgreSQL 7.2 or later.
+ </para>
+ </note>
+ <para>
+ See also <function>pg_escape_string</function>
</para>
</refsect1>
</refentry>
@@ -2060,30 +2252,16 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_escape_string</function> escapes string for
+ text/char datatype. It returns escaped string.
</para>
- </refsect1>
- </refentry>
-
-
-
- <refentry id='function.pg-lo-close'>
- <refnamediv>
- <refname>pg_lo_close</refname>
- <refpurpose>
- Close a large object
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>bool <function>pg_lo_close</function></funcdef>
- <paramdef>resource <parameter>large_object</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
+ <note>
+ <para>
+ This function is requires PostgreSQL 7.2 or later.
+ </para>
+ </note>
<para>
- &warn.undocumented.func;
+ See also <function>pg_escape_bytea</function>
</para>
</refsect1>
</refentry>
@@ -2108,7 +2286,12 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_lo_seek</function> seeks position of large object
+ resource. <parameter>whence</parameter> is PGSQL_SEEK_SET,
+ PGSQL_SEEK_CUR or PGSQL_SEEK_END.
+ </para>
+ <para>
+ See also <function>pg_lo_tell</function>.
</para>
</refsect1>
</refentry>
@@ -2131,7 +2314,11 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <function>pg_lo_tell</function> returns current position (offset
+ from the beginning of large object).
+ </para>
+ <para>
+ See also <function>pg_lo_seek</function>.
</para>
</refsect1>
</refentry>
@@ -2154,34 +2341,21 @@
</funcprototype>
</funcsynopsis>
<para>
- &warn.undocumented.func;
+ <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>
- </refsect1>
- </refentry>
-
-
-
- <refentry id='function.pg-result-status'>
- <refnamediv>
- <refname>pg_result_status</refname>
- <refpurpose>
- Get status of query result
- </refpurpose>
- </refnamediv>
- <refsect1>
- <title>Description</title>
- <funcsynopsis>
- <funcprototype>
- <funcdef>int <function>pg_result_status</function></funcdef>
- <paramdef>resource <parameter>result</parameter></paramdef>
- </funcprototype>
- </funcsynopsis>
<para>
- &warn.undocumented.func;
- </para>
+ See also <function>pg_query</function>,
+ <function>pg_send_query</function>,
+ <function>pg_get_result</function>,
+ <function>pg_last_error</function> and
+ <function>pg_last_notice</function>
+ </para>
</refsect1>
</refentry>
-
+
</reference>
<!-- Keep this comment at the end of the file
