chriskl Sun Apr 3 03:21:51 2005 EDT
Modified files:
/phpdoc/en/reference/pgsql/functions pg-execute.xml
pg-parameter-status.xml
pg-prepare.xml
pg-query-params.xml
pg-result-error-field.xml
pg-send-execute.xml
pg-send-prepare.xml
pg-send-query-params.xml
pg-set-error-verbosity.xml
pg-transaction-status.xml
Log:
- Update several PostgreSQL functions to the new doc style
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-execute.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-execute.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-execute.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-execute.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-execute.xml:1.1 Sun Mar 20
03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-execute.xml Sun Apr 3 03:21:50 2005
@@ -1,62 +1,87 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-execute">
<refnamediv>
<refname>pg_execute</refname>
- <refpurpose>Execute a previously prepared query</refpurpose>
+ <refpurpose>Sends a request to execute a prepared statement with given
parameters, and waits for the result.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>pg_execute</methodname>
-
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
- <methodparam><type>array</type><parameter>params</parameter></methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>resource</type><methodname>pg_execute</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_execute</function> returns a query result resource if
- the named prepared query could be executed with the given parameters.
- It returns &false; on failure or if
- connection is not a valid connection. Details about the error can
- be retrieved using the <function>pg_last_error</function>
- function if connection is valid.
- <function>pg_execute</function> executes a previously prepared
- query on the
- <parameter>connection</parameter> resource with the specified
- parameters. It is identical to <function>pg_query_params</function>
- except that it takes the name of a previously prepared query instead
- of an actual query. The
- <parameter>connection</parameter> must be a valid connection that
- was returned by <function>pg_connect</function> or
- <function>pg_pconnect</function>. The return value of this
- function is an query result resource to be used to access the
- results from other PostgreSQL functions such as
- <function>pg_fetch_array</function>.
- <note>
- <simpara>
- <parameter>connection</parameter> is an optional parameter for
- <function>pg_execute</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.
- </simpara>
- </note>
+ Sends a request to execute a prepared statement with given parameters, and
+ waits for the result.
+ </para>
+ <para>
+ <function>pg_execute</function> is like
<function>pg_query_params</function>,
+ but the command to be executed is
+ specified by naming a previously-prepared statement, instead of giving a
+ query string. This feature allows commands that will be used repeatedly to
+ be parsed and planned just once, rather than each time they are executed.
+ The statement must have been prepared previously in the current session.
+ <function>pg_execute</function> is supported only against PostgreSQL 7.4 or
+ higher connections; it will fail when using earlier versions.
+ </para>
+ <para>
+ The parameters are identical to <function>pg_query_params</function>,
except that the name of a
+ prepared statement is given instead of a query string.
</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>stmtname</parameter></term>
+ <listitem>
+ <para>
+ The name of the prepared statement to execute. if
+ "" is specified, then the unnamed statement is executed. The name must
have
+ been previously prepared using <function>pg_prepare</function>,
+ <function>pg_send_prepare</function> or a <literal>PREPARE</literal> SQL
+ command.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <para>
+ An array of parameter values to substitute for the $1, $2, etc.
placeholders
+ in the original prepared query string. The number of elements in the
array
+ must match the number of placeholders.
+ </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>
@@ -89,11 +114,9 @@
&reftitle.seealso;
<para>
<simplelist>
- <member><function>pg_connect</function></member>
- <member><function>pg_pconnect</function></member>
<member><function>pg_prepare</function></member>
- <member><function>pg_send_execute</function></member>
-
+ <member><function>pg_send_prepare</function></member>
+ <member><function>pg_query_params</function></member>
</simplelist>
</para>
</refsect1>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml?r1=1.6&r2=1.7&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml:1.6
phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml:1.7
--- phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml:1.6 Sun Mar
27 04:51:26 2005
+++ phpdoc/en/reference/pgsql/functions/pg-parameter-status.xml Sun Apr 3
03:21:50 2005
@@ -1,11 +1,9 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.6 $ -->
+<!-- $Revision: 1.7 $ -->
<refentry id="function.pg-parameter-status">
<refnamediv>
<refname>pg_parameter_status</refname>
- <refpurpose>
- Returns the value of a server parameter
- </refpurpose>
+ <refpurpose>Looks up a current parameter setting of the server.</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -16,19 +14,100 @@
<methodparam><type>string</type><parameter>param_name</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_parameter_status</function> returns a string with the
- current <parameter>param_name</parameter> value. Returns &false; on
- failure.
+ Looks up a current parameter setting of the server.
</para>
<para>
- The parameters currently available include:
<literal>server_version</literal>,
- <literal>server_encoding</literal>, <literal>client_encoding</literal>,
- <literal>is_superuser</literal>, <literal>session_authorization</literal>,
- <literal>DateStyle</literal>, <literal>TimeZone</literal>
- and <literal>integer_datetimes</literal>.
(<literal>server_encoding</literal>,
- <literal>TimeZone</literal> and <literal>integer_datetimes</literal> were
- not reported before PostgreSQL 8.0.)
- </para>
+ Certain parameter values are reported by the server automatically at
+ connection startup or whenever their values change.
<function>pg_parameter_status</function> can be
+ used to interrogate these settings. It returns the current value of a
+ parameter if known, or &false; if the parameter is not known.
+ </para>
+ <para>
+ Parameters reported as of PostgreSQL 8.0 include
<literal>server_version</literal>,
+ <literal>server_encoding</literal>, <literal>client_encoding</literal>,
+ <literal>is_superuser</literal>, <literal>session_authorization</literal>,
+ <literal>DateStyle</literal>, <literal>TimeZone</literal>, and
<literal>integer_datetimes</literal>.
+ (<literal>server_encoding</literal>, <literal>TimeZone</literal>, and
+ <literal>integer_datetimes</literal> were not reported by releases before
8.0.) Note that
+ <literal>server_version</literal>, <literal>server_encoding</literal> and
<literal>integer_datetimes</literal>
+ cannot change after PostgreSQL startup.
+ </para>
+ <para>
+ PostgreSQL 7.3 or lower servers do not report parameter settings,
+ <function>pg_parameter_status</function>
+ includes logic to obtain values for <literal>server_version</literal> and
+ <literal>client_encoding</literal>
+ anyway. Applications are encouraged to use
<function>pg_parameter_status</function> rather than ad
+ hoc code to determine these values.
+ </para>
+ <caution>
+ <para>
+ On a pre-7.4
+ PostgreSQL server, changing <literal>client_encoding</literal> via
<literal>SET</literal> after connection startup will
+ not be reflected by <function>pg_parameter_status</function>.
+ </para>
+ </caution>
+ </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>param_name</parameter></term>
+ <listitem>
+ <para>
+ Possible <parameter>param_name</parameter> values include
<literal>server_version</literal>,
+ <literal>server_encoding</literal>,
<literal>client_encoding</literal>,
+ <literal>is_superuser</literal>,
<literal>session_authorization</literal>,
+ <literal>DateStyle</literal>, <literal>TimeZone</literal>, and
+ <literal>integer_datetimes</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>A &string; containing the value of the parameter, &false; on failure
or invalid
+ <param>param_name</param>.</para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>pg_parameter_status</function> example</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ $dbconn = pg_connect("dbname=publisher") or die("Could not connect");
+
+ echo "Server encoding: ", pg_parameter_status($dbconn, "server_encoding");
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Server encoding: SQL_ASCII
+]]>
+ </screen>
+ </example>
+ </para>
</refsect1>
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-prepare.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-prepare.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-prepare.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-prepare.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-prepare.xml:1.1 Sun Mar 20
03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-prepare.xml Sun Apr 3 03:21:50 2005
@@ -1,72 +1,92 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-prepare">
<refnamediv>
<refname>pg_prepare</refname>
- <refpurpose>Prepares a query for future execution</refpurpose>
+ <refpurpose> Submits a request to create a prepared statement with the
+ given parameters, and waits for completion.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>pg_prepare</methodname>
-
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
- <methodparam><type>string</type><parameter>query</parameter></methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>resource</type><methodname>pg_prepare</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_prepare</function> returns a query result resource if
- query could be prepared. It returns &false; on failure or if
- connection is not a valid connection. Details about the error can
- be retrieved using the <function>pg_last_error</function>
- function if connection is valid.
- <function>pg_prepare</function> prepares an SQL statement for
- the PostgreSQL database connection 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. The <parameter>stmtname</parameter>
- is the name of the prepared query, for future use with
- <function>pg_execute</function> or <function>pg_send_execute</function>.
- <note>
- <simpara>
- <parameter>connection</parameter> is an optional parameter for
- <function>pg_prepare</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.
- </simpara>
- </note>
+ <function>pg_prepare</function> creates a prepared statement for later
execution with
+ <function>pg_execute</function> or <function>pg_send_execute</function>.
+ This feature allows commands that will be used repeatedly to
+ be parsed and planned just once, rather than each time they are executed.
+ <function>pg_prepare</function> is supported only against PostgreSQL 7.4 or
+ higher connections; it will fail when using earlier versions.
</para>
<para>
- Parameters to <function>pg_prepare</function> are specified
- using placeholders in the query. It is not necessary to quote
- parameters as quoting and escaping is done automatically.
- Placeholders are indicated in the <parameter>query</parameter>
- by $1, $2, $3 and so on.
+ The function creates a prepared statement named <param>stmtname</param>
from the <param>query</param>
+ string, which must contain a single SQL command. <param>stmtname</param>
may be "" to
+ create an unnamed statement, in which case any pre-existing unnamed
+ statement is automatically replaced; otherwise it is an error if the
+ statement name is already defined in the current session. If any
parameters
+ are used, they are referred to in the <param>query</param> as $1, $2, etc.
</para>
- <para>Using prepared queries means you can prepare one and
- then execute many times, with different parameters. PostgreSQL
- will cache the query plan on the prepare, then re-use it for
- each execute, resulting in speed improvements. There is no
- need to use a prepared query if it will only be executed once.
- In this case, it is simpler to use <function>pg_query_params</function>.
+ <para>
+ Prepared statements for use with <function>pg_prepare</function> can also
be created by
+ executing SQL <literal>PREPARE</literal> statements. (But
<function>pg_prepare</function> is more flexible since it
+ does not require parameter types to be pre-specified.) Also, although
there
+ is no PHP function for deleting a prepared statement, the SQL
<litearl>DEALLOCATE</literal>
+ statement can be used for that purpose.
</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>stmtname</parameter></term>
+ <listitem>
+ <para>
+ The name to give the prepared statement. Must be unique
per-connection. If
+ "" is specified, then an unnamed statement is created, overwriting any
+ previously defined unnamed statement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ The parameterised SQL statement. Must contain only a single statement.
+ (multiple statements separated by semi-colons are not allowed.) If any
parameters
+ are used, they are referred to as $1, $2, etc.
+ </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>
@@ -99,11 +119,8 @@
&reftitle.seealso;
<para>
<simplelist>
- <member><function>pg_connect</function></member>
- <member><function>pg_pconnect</function></member>
<member><function>pg_execute</function></member>
<member><function>pg_send_execute</function></member>
- <member><function>pg_query_params</function></member>
</simplelist>
</para>
</refsect1>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-query-params.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-query-params.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-query-params.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-query-params.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-query-params.xml:1.1 Sun Mar 20
03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-query-params.xml Sun Apr 3
03:21:50 2005
@@ -1,45 +1,93 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-query-params">
<refnamediv>
<refname>pg_query_params</refname>
- <refpurpose>Execute a query, specifying query variables as separate
parameters</refpurpose>
+ <refpurpose>Submits a command to the server and waits for the result, with
the ability to pass parameters separately from the SQL command
text.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type>resource</type><methodname>pg_query_params</methodname>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
- <methodsynopsis>
- <type>resource</type><methodname>pg_query_params</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
- <methodparam><type>string</type><parameter>query</parameter></methodparam>
- <methodparam><type>array</type><parameter>params</parameter></methodparam>
- </methodsynopsis>
<para>
- <function>pg_query_params</function> works identically to
- <function>pg_query</function>, except that instead of putting
- query parameters directly into the <parameter>query</parameter>
- <type>string</type>, placeholders are used and the parameters are
- passed in separately. Unlike <function>pg_query</function>,
- only one non-empty SQL statement can be executed at a time.
- </para>
- <para>
- Parameters passed in this way are automatically quoted and escaped
- if necessary. This is an effective way of improving the security
- of your scripts and eliminating the need for manual quoting and
- escaping of parameters.
- </para>
- <para>Placeholders are indicated in the <parameter>query</parameter>
- by $1, $2, $3 and so on. The first parameter will be substituted for
- $1, the second for $2, the third for $3.
+ Submits a command to the server and waits for the result, with the ability
+ to pass parameters separately from the SQL command text.
+ </para>
+ <para>
+ <function>pg_query_params</function> is like
<function>pg_query</function>,
+ but offers additional functionality: parameter
+ values can be specified separately from the command string proper.
+ <function>pg_query_params</function> is supported only against PostgreSQL
7.4 or
+ higher connections; it will fail when using earlier versions.
+ </para>
+ <para>
+ If parameters are used, they are referred to in the
<parameter>query</parameter>
+ string as $1, $2, etc. <param>params</param> specifies the actual values
of the
+ parameters. A &null; value in this array means the corresponding parameter
is SQL
+ <literal>NULL</literal>.
+ </para>
+ <para>
+ The primary advantage of <function>pg_query_params</function> over
<function>pg_query</function>
+ is that parameter values
+ may be separated from the <parameter>query</parameter> string, thus
avoiding the need for tedious
+ and error-prone quoting and escaping. Unlike
<function>pg_query</function>,
+ <function>pg_query_params</function> allows at
+ most one SQL command in the given string. (There can be semicolons in it,
+ but not more than one nonempty command.)
</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 parameterised SQL statement. Must contain only a single statement.
+ (multiple statements separated by semi-colons are not allowed.) If any
parameters
+ are used, they are referred to as $1, $2, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <para>
+ An array of parameter values to substitute for the $1, $2, etc.
placeholders
+ in the original prepared query string. The number of elements in the
array
+ must match the number of placeholders.
+ </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>
@@ -71,8 +119,6 @@
<para>
<simplelist>
<member><function>pg_query</function></member>
- <member><function>pg_connect</function></member>
- <member><function>pg_escape_string</function></member>
</simplelist>
</para>
</refsect1>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml:1.3
phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml:1.4
--- phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml:1.3 Tue Mar
22 23:37:22 2005
+++ phpdoc/en/reference/pgsql/functions/pg-result-error-field.xml Sun Apr
3 03:21:50 2005
@@ -1,18 +1,16 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.58 -->
<refentry id='function.pg-result-error-field'>
<refnamediv>
<refname>pg_result_error_field</refname>
- <refpurpose>
- Get error message field associated with result
- </refpurpose>
+ <refpurpose>Returns an individual field of an error report.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <type>string</type><methodname>pg_result_error_field</methodname>
+ <type>mixed</type><methodname>pg_result_error_field</methodname>
<methodparam><type>resource</type><parameter>result</parameter></methodparam>
<methodparam><type>int</type><parameter>fieldcode</parameter></methodparam>
</methodsynopsis>
@@ -27,19 +25,47 @@
you must use <function>pg_send_query</function> and
<function>pg_get_result</function> to get the result handle.
</para>
- <para>
- Possible <parameter>fieldcode</parameter> values are:
<literal>PGSQL_DIAG_SEVERITY</literal>,
- <literal>PGSQL_DIAG_SQLSTATE</literal>,
<literal>PGSQL_DIAG_MESSAGE_PRIMARY</literal>,
- <literal>PGSQL_DIAG_MESSAGE_DETAIL</literal>,
- <literal>PGSQL_DIAG_MESSAGE_HINT</literal>,
<literal>PGSQL_DIAG_STATEMENT_POSITION</literal>,
- <literal>PGSQL_DIAG_INTERNAL_POSITION</literal> (PostgreSQL 8.0+ only),
- <literal>PGSQL_DIAG_INTERNAL_QUERY</literal> (PostgreSQL 8.0+ only),
- <literal>PGSQL_DIAG_CONTEXT</literal>,
<literal>PGSQL_DIAG_SOURCE_FILE</literal>,
- <literal>PGSQL_DIAG_SOURCE_LINE</literal> or
- <literal>PGSQL_DIAG_SOURCE_FUNCTION</literal>.
- </para>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>result</parameter></term>
+ <listitem>
+ <para>
+ A PostgreSQL query result resource from a previously executed
+ statement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>fieldcode</parameter></term>
+ <listitem>
+ <para>
+ Possible <parameter>fieldcode</parameter> values are:
<literal>PGSQL_DIAG_SEVERITY</literal>,
+ <literal>PGSQL_DIAG_SQLSTATE</literal>,
<literal>PGSQL_DIAG_MESSAGE_PRIMARY</literal>,
+ <literal>PGSQL_DIAG_MESSAGE_DETAIL</literal>,
+ <literal>PGSQL_DIAG_MESSAGE_HINT</literal>,
<literal>PGSQL_DIAG_STATEMENT_POSITION</literal>,
+ <literal>PGSQL_DIAG_INTERNAL_POSITION</literal> (PostgreSQL 8.0+
only),
+ <literal>PGSQL_DIAG_INTERNAL_QUERY</literal> (PostgreSQL 8.0+ only),
+ <literal>PGSQL_DIAG_CONTEXT</literal>,
<literal>PGSQL_DIAG_SOURCE_FILE</literal>,
+ <literal>PGSQL_DIAG_SOURCE_LINE</literal> or
+ <literal>PGSQL_DIAG_SOURCE_FUNCTION</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>A &string; containing the contents of the error field, &null; if the
field does not exist or &false;
+ on failure.</para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-send-execute.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-send-execute.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-send-execute.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-send-execute.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-send-execute.xml:1.1 Sun Mar 20
03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-send-execute.xml Sun Apr 3
03:21:50 2005
@@ -1,41 +1,80 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-send-execute">
<refnamediv>
<refname>pg_send_execute</refname>
- <refpurpose>Asynchronously execute a previously prepared query</refpurpose>
+ <refpurpose>Sends a request to execute a prepared statement with given
parameters, without waiting for the result(s).</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <type>resource</type><methodname>pg_send_execute</methodname>
-
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
- <methodparam><type>array</type><parameter>params</parameter></methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>resource</type><methodname>pg_send_execute</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <type>bool</type><methodname>pg_send_execute</methodname>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_send_execute</function> executes a previously prepared
- named query on the <parameter>connection</parameter>, with the
- specified parameters. Unlike <function>pg_execute</function>, script
execution
- is not blocked while the query is executing.
+ Sends a request to execute a prepared statement with given parameters,
+ without waiting for the result(s).
</para>
<para>
- <function>pg_send_execute</function> returns a query result resource if
- the named prepared query could be executed with the given parameters.
- It returns &false; on failure or if connection is not a valid connection.
- It is identical to <function>pg_send_query_params</function>
- except that it takes the name of a previously prepared query instead
- of an actual query.
+ This is similar to <function>pg_send_query_params</function>, but the
command to be executed is specified
+ by naming a previously-prepared statement, instead of giving a query
string. The
+ function's parameters are handled identically to
<function>pg_execute</function>.
+ Like <function>pg_execute</function>, it will not work on pre-7.4 versions
of
+ PostgreSQL.
</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>stmtname</parameter></term>
+ <listitem>
+ <para>
+ The name of the prepared statement to execute. if
+ "" is specified, then the unnamed statement is executed. The name must
have
+ been previously prepared using <function>pg_prepare</function>,
+ <function>pg_send_prepare</function> or a <literal>PREPARE</literal> SQL
+ command.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <para>
+ An array of parameter values to substitute for the $1, $2, etc.
placeholders
+ in the original prepared query string. The number of elements in the
array
+ must match the number of placeholders.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>Returns &true; on success, &false; on failure. Use
<function>pg_get_result</function>
+ to determine the query result.</para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -76,12 +115,9 @@
&reftitle.seealso;
<para>
<simplelist>
- <member><function>pg_connect</function></member>
- <member><function>pg_pconnect</function></member>
<member><function>pg_prepare</function></member>
<member><function>pg_send_prepare</function></member>
- <member><function>pg_execute</function></member>
-
+ <member><function>pg_execute</function></member>
</simplelist>
</para>
</refsect1>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml:1.1 Sun Mar 20
03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-send-prepare.xml Sun Apr 3
03:21:50 2005
@@ -1,47 +1,79 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id="function.pg-send-prepare">
<refnamediv>
<refname>pg_send_prepare</refname>
- <refpurpose>Asynchronously prepares a query for future execution</refpurpose>
+ <refpurpose>Sends a request to create a prepared statement with the given
parameters, without waiting for completion.</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
- <type>resource</type><methodname>pg_send_prepare</methodname>
-
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
- <methodparam><type>string</type><parameter>query</parameter></methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>resource</type><methodname>pg_send_prepare</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <type>bool</type><methodname>pg_send_prepare</methodname>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>string</type><parameter>stmtname</parameter></methodparam>
<methodparam><type>string</type><parameter>query</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_send_prepare</function> asynchronously prepares a query
- on the <parameter>connection</parameter>. Unlike
<function>pg_prepare</function>,
- script execution is not blocked while the query is being prepared. It
- behaves in the same fashion as <function>pg_send_query</function>.
+ Sends a request to create a prepared statement with the given parameters,
+ without waiting for completion.
</para>
<para>
- Parameters to <function>pg_prepare</function> are specified
- using placeholders in the query. It is not necessary to quote
- parameters as quoting and escaping is done automatically.
- Placeholders are indicated in the <parameter>query</parameter>
- by $1, $2, $3 and so on.
- </para>
- <para>Using prepared queries means you can prepare one and
- then execute many times, with different parameters. PostgreSQL
- will cache the query plan on the prepare, then re-use it for
- each execute, resulting in speed improvements. There is no
- need to use a prepared query if it will only be executed once.
- In this case, it is simpler to use <function>pg_query_params</function>.
+ This is an asynchronous version of <function>pg_prepare</function>: it
returns &true; if it was able to
+ dispatch the request, and &false; if not. After a successful call, call
+ <function>pg_get_result</function> to determine whether the server
successfully created the
+ prepared statement. The function's parameters are handled identically to
+ <function>pg_prepare</function>. Like <function>pg_prepare</function>, it
will not work
+ on pre-7.4 versions of PostgreSQL.
</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>stmtname</parameter></term>
+ <listitem>
+ <para>
+ The name to give the prepared statement. Must be unique
per-connection. If
+ "" is specified, then an unnamed statement is created, overwriting any
+ previously defined unnamed statement.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ The parameterised SQL statement. Must contain only a single statement.
+ (multiple statements separated by semi-colons are not allowed.) If any
parameters
+ are used, they are referred to as $1, $2, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>Returns &true; on success, &false; on failure. Use
<function>pg_get_result</function>
+ to determine the query result.</para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml:1.1 Sun Mar
20 03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-send-query-params.xml Sun Apr
3 03:21:50 2005
@@ -1,12 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.2 -->
<refentry id='function.pg-send-query-params'>
<refnamediv>
<refname>pg_send_query_params</refname>
- <refpurpose>
- Sends asynchronous query, specifying query variables as separate parameters
- </refpurpose>
+ <refpurpose>Submits a command and separate parameters to the server without
waiting for the result(s).</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -18,25 +16,61 @@
<methodparam><type>array</type><parameter>params</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_send_query_params</function> works identically to
- <function>pg_send_query</function>, except that instead of putting
- query parameters directly into the <parameter>query</parameter>
- <type>string</type>, placeholders are used and the parameters are
- passed in separately. Unlike <function>pg_send_query</function>,
- only one non-empty SQL statement can be executed at a time.
+ Submits a command and separate parameters to the server without
+ waiting for the result(s).
</para>
<para>
- Parameters passed in this way are automatically quoted and escaped
- if necessary. This is an effective way of improving the security
- of your scripts and eliminating the need for manual quoting and
- escaping of parameters.
- </para>
- <para>Placeholders are indicated in the <parameter>query</parameter>
- by $1, $2, $3 and so on. The first parameter will be substituted for
- $1, the second for $2, the third for $3.
- </para>
+ This is equivalent to <function>pg_send_query</function> except that query
+ parameters can be specified separately from the
+ <parameter>query</parameter> string. The function's parameters are
+ handled identically to <function>pg_query_params</function>. Like
+ <function>pg_query_params</function>, it will not work on pre-7.4
PostgreSQL
+ connections, and it allows only one command in the query string.
+ </para>
</refsect1>
-
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>query</parameter></term>
+ <listitem>
+ <para>
+ The parameterised SQL statement. Must contain only a single statement.
+ (multiple statements separated by semi-colons are not allowed.) If any
parameters
+ are used, they are referred to as $1, $2, etc.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>params</parameter></term>
+ <listitem>
+ <para>
+ An array of parameter values to substitute for the $1, $2, etc.
placeholders
+ in the original prepared query string. The number of elements in the
array
+ must match the number of placeholders.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>Returns &true; on success, &false; on failure. Use
<function>pg_get_result</function>
+ to determine the query result.</para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
@@ -66,8 +100,6 @@
<para>
<simplelist>
<member><function>pg_send_query</function></member>
- <member><function>pg_connect</function></member>
- <member><function>pg_escape_string</function></member>
</simplelist>
</para>
</refsect1>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml:1.1 Tue Mar
22 22:11:05 2005
+++ phpdoc/en/reference/pgsql/functions/pg-set-error-verbosity.xml Sun Apr
3 03:21:50 2005
@@ -1,11 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.16 -->
<refentry id="function.pg-set-error-verbosity">
<refnamediv>
<refname>pg_set_error_verbosity</refname>
<refpurpose>
- Set the error verbosity
+ Determines the verbosity of messages returned by
<function>pg_last_error</function>
+ and <function>pg_result_error</function>.
</refpurpose>
</refnamediv>
@@ -13,33 +14,62 @@
&reftitle.description;
<methodsynopsis>
<type>int</type><methodname>pg_set_error_verbosity</methodname>
- <methodparam><type>int</type><parameter>verbosity</parameter></methodparam>
- </methodsynopsis>
- <methodsynopsis>
- <type>int</type><methodname>pg_set_error_verbosity</methodname>
-
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
+ <methodparam
choice="opt"><type>resource</type><parameter>connection</parameter></methodparam>
<methodparam><type>int</type><parameter>verbosity</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_set_error_verbosity</function> determines the verbosity
- of messages returned by <function>pg_last_error</function> and
- <function>pg_result_error</function>. The <parameter>verbosity</parameter>
- can be one of three constants: <literal>PGSQL_ERRORS_TERSE</literal>,
- <literal>PGSQL_ERRORS_DEFAULT</literal>
- or <literal>PGSQL_ERRORS_VERBOSE</literal>.
+ Determines the verbosity of messages returned by
<function>pg_last_error</function>
+ and <function>pg_result_error</function>.
</para>
- <para><function>pg_set_error_verbosity</function> will return the
- <parameter>connection</parameter> previous verbosity.
+ <para>
+ <function>pg_set_error_verbosity</function> sets the verbosity mode,
returning the connection's previous
+ setting. In <literal>TERSE</literal> mode, returned messages include
severity, primary text, and
+ position only; this will normally fit on a single line. The default
mode
+ produces messages that include the above plus any detail, hint, or
context
+ fields (these may span multiple lines). The <literal>VERBOSE</literal>
mode includes all available
+ fields. Changing the verbosity does not affect the messages available
from
+ already-existing result objects, only subsequently-created ones.
</para>
- <note>
- <para>
- This function requires PostgreSQL 7.4 or higher. Changing the
- verbosity in this manner will only affect future results, existing
- result objects will be unchanged.
- </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>verbosity</parameter></term>
+ <listitem>
+ <para>
+ The required verbosity: <literal>PGSQL_ERRORS_TERSE</literal>,
+ <literal>PGSQL_ERRORS_DEFAULT</literal>
+ or <literal>PGSQL_ERRORS_VERBOSE</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ The previous verbosity level: <literal>PGSQL_ERRORS_TERSE</literal>,
+ <literal>PGSQL_ERRORS_DEFAULT</literal>
+ or <literal>PGSQL_ERRORS_VERBOSE</literal>.
+ </para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml
diff -u phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml:1.1
phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml:1.2
--- phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml:1.1 Sun Mar
20 03:54:31 2005
+++ phpdoc/en/reference/pgsql/functions/pg-transaction-status.xml Sun Apr
3 03:21:50 2005
@@ -1,12 +1,10 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.82 -->
<refentry id='function.pg_transaction_status'>
<refnamediv>
<refname>pg_transaction_status</refname>
- <refpurpose>
- Get transaction status
- </refpurpose>
+ <refpurpose>Returns the current in-transaction status of the
server.</refpurpose>
</refnamediv>
<refsect1 role="description">
@@ -16,26 +14,46 @@
<methodparam><type>resource</type><parameter>connection</parameter></methodparam>
</methodsynopsis>
<para>
- <function>pg_transaction_status</function> returns the current
in-transaction status
- of the server.
- The status can be <literal>PGSQL_TRANSACTION_IDLE</literal> (currently
idle),
- <literal>PGSQL_TRANSACTION_ACTIVE</literal> (a command is in progress),
- <literal>PGSQL_TRANSACTION_INTRANS</literal> (idle, in a valid transaction
block),
- or <literal>PGSQL_TRANSACTION_INERROR</literal> (idle, in a failed
transaction block).
- <literal>PGSQL_TRANSACTION_UNKNOWN</literal> is reported if the connection
is bad.
- <literal>PGSQL_TRANSACTION_ACTIVE</literal> is reported only when a query
- has been sent to the server and not yet completed.
- </para>
- <caution>
- <para>
- <function>pg_transaction_status</function> will give incorrect results
when using
- a PostgreSQL 7.3 server that has the parameter
<literal>autocommit</literal>
- set to off. The server-side autocommit feature has been
- deprecated and does not exist in later server versions.
- </para>
- </caution>
+ Returns the current in-transaction status of the server.
+ </para>
+ <caution>
+ <para>
+ <function>pg_transaction_status</function> will give incorrect results
when using
+ a PostgreSQL 7.3 server that has the parameter
<literal>autocommit</literal>
+ set to off. The server-side autocommit feature has been
+ deprecated and does not exist in later server versions.
+ </para>
+ </caution>
</refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>connection</parameter></term>
+ <listitem>
+ <para>
+ PostgreSQL database connection resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>The status can be <literal>PGSQL_TRANSACTION_IDLE</literal> (currently
idle),
+ <literal>PGSQL_TRANSACTION_ACTIVE</literal> (a command is in progress),
+ <literal>PGSQL_TRANSACTION_INTRANS</literal> (idle, in a valid transaction
block),
+ or <literal>PGSQL_TRANSACTION_INERROR</literal> (idle, in a failed
transaction block).
+ <literal>PGSQL_TRANSACTION_UNKNOWN</literal> is reported if the connection
is bad.
+ <literal>PGSQL_TRANSACTION_ACTIVE</literal> is reported only when a query
+ has been sent to the server and not yet completed.
+ </para>
+ </refsect1>
+
<refsect1 role="examples">
&reftitle.examples;
<para>
