cvs: 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

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>