cvs: phpdoc /en/reference/pgsql/functions pg-select.xml pg-set-client-encoding.xml pg-unescape-bytea.xml

chriskl Mon Jul 4 05:01:00 2005 EDT Modified files: /phpdoc/en/reference/pgsql/functions pg-select.xml pg-set-client-encoding.xml pg-unescape-bytea.xml Log: Another three pgsql functions.

http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-select.xml?r1=1.11&r2=1.12&ty=u Index: phpdoc/en/reference/pgsql/functions/pg-select.xml diff -u phpdoc/en/reference/pgsql/functions/pg-select.xml:1.11 phpdoc/en/reference/pgsql/functions/pg-select.xml:1.12 --- phpdoc/en/reference/pgsql/functions/pg-select.xml:1.11 Fri Jun 24 05:11:45 2005 +++ phpdoc/en/reference/pgsql/functions/pg-select.xml Mon Jul 4 05:00:59 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.11 $ --> +<!-- $Revision: 1.12 $ --> <!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.80 --> <refentry id='function.pg-select'> <refnamediv> @@ -21,18 +21,80 @@ <para> <function>pg_select</function> selects records specified by <literal>assoc_array</literal> which has - <literal>field=>value</literal>. For successful query, it returns - array contains all records and fields that match the condition - specified by <literal>assoc_array</literal>. If - <literal>options</literal> is specified, + <literal>field=>value</literal>. For a successful query, it returns an + array containing all records and fields that match the condition + specified by <literal>assoc_array</literal>. + </para> + <para>If <literal>options</literal> is specified, <function>pg_convert</function> is applied to - <literal>assoc_array</literal> with specified option. - If <constant>PGSQL_DML_STRING</constant> is part of the - <parameter>options</parameter> then query string is returned. + <literal>assoc_array</literal> with the specified flags. </para> &warn.experimental.func; </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>table_name</parameter></term> + <listitem> + <para> + Name of the table from which to select rows. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>assoc_array</parameter></term> + <listitem> + <para> + An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>, + and whose values are what matched rows are to be updated to. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>condition</parameter></term> + <listitem> + <para> + An <type>array</type> whose keys are field names in the table <parameter>table_name</parameter>, + and whose values are the conditions that a row must meet to be retrieved. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>options</parameter></term> + <listitem> + <para> + Any number of <constant>PGSQL_CONV_FORCE_NULL</constant>, + <constant>PGSQL_DML_NO_CONV</constant>, + <constant>PGSQL_DML_EXEC</constant>, + <constant>PGSQL_DML_ASYNC</constant> or + <constant>PGSQL_DML_STRING</constant> combined. If <constant>PGSQL_DML_STRING</constant> is part of the + <parameter>options</parameter> then query string is returned. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + &return.success; Returns <type>string</type> if <constant>PGSQL_DML_STRING</constant> is passed + via <parameter>options</parameter>. + </para> + </refsect1> + <refsect1 role="examples"> &reftitle.examples; <para> http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml?r1=1.8&r2=1.9&ty=u Index: phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml diff -u phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml:1.8 phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml:1.9 --- phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml:1.8 Thu Apr 21 05:29:07 2005 +++ phpdoc/en/reference/pgsql/functions/pg-set-client-encoding.xml Mon Jul 4 05:00:59 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.8 $ --> +<!-- $Revision: 1.9 $ --> <!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.16 --> <refentry id="function.pg-set-client-encoding"> <refnamediv> @@ -25,26 +25,59 @@ encoding and returns 0 if success or -1 if error. </para> <para> - <parameter>encoding</parameter> is the client encoding and can be - either : SQL_ASCII, EUC_JP, EUC_CN, EUC_KR, EUC_TW, UNICODE, - MULE_INTERNAL, LATINX (X=1...9), KOI8, WIN, ALT, SJIS, BIG5, - WIN1250. Available encoding depends on your PostgreSQL and libpq - version. Refer to PostgreSQL manual for supported encodings for - your PostgreSQL. + PostgreSQL will automatically convert data in the backend database + encoding into the frontend encoding. </para> <note> <para> - This function requires PHP-4.0.3 or higher and PostgreSQL-7.0 or - higher. Supported encoding depends on PostgreSQL version. Refer - to PostgreSQL manual for details. - </para> - <para> The function used to be called <function>pg_setclientencoding</function>. </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>encoding</parameter></term> + <listitem> + <para> + The required client encoding. One of <literal>SQL_ASCII</literal>, <literal>EUC_JP</literal>, + <literal>EUC_CN</literal>, <literal>EUC_KR</literal>, <literal>EUC_TW</literal>, + <literal>UNICODE</literal>, <literal>MULE_INTERNAL</literal>, <literal>LATINX</literal> (X=1...9), + <literal>KOI8</literal>, <literal>WIN</literal>, <literal>ALT</literal>, <literal>SJIS</literal>, + <literal>BIG5</literal> or <literal>WIN1250</literal>. + </para> + <para> + The exact list of available encodings depends on your PostgreSQL version, so check your + PostgreSQL manual for a more specific list. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + Returns 0 on success or -1 on error. + </para> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para> http://cvs.php.net/diff.php/phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml?r1=1.4&r2=1.5&ty=u Index: phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml diff -u phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml:1.4 phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml:1.5 --- phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml:1.4 Fri Mar 11 11:03:26 2005 +++ phpdoc/en/reference/pgsql/functions/pg-unescape-bytea.xml Mon Jul 4 05:00:59 2005 @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <!-- splitted from ./en/functions/pgsql.xml, last change in rev 1.61 --> <refentry id='function.pg-unescape-bytea'> <refnamediv> @@ -16,27 +16,76 @@ <methodparam><type>string</type><parameter>data</parameter></methodparam> </methodsynopsis> <para> - <function>pg_unescape_bytea</function> unescapes string from - bytea datatype. It returns unescaped string (binary). + <function>pg_unescape_bytea</function> unescapes PostgreSQL bytea data + values. It returns the unescaped string, possibly containing binary data. </para> <note> <para> - When you SELECT bytea type, PostgreSQL returns octal byte value - prefixed by \ (e.g. \032). Users are supposed to convert back to - binary format by yourself. + When you <literal>SELECT</literal> a bytea type, PostgreSQL returns octal byte values + prefixed with '\' (e.g. \032). Users are supposed to convert back to + binary format manually. </para> <para> This function requires PostgreSQL 7.2 or later. With PostgreSQL - 7.2.0 and 7.2.1, bytea type must be casted when you enable + 7.2.0 and 7.2.1, bytea values must be cast when you enable multi-byte support. i.e. <literal>INSERT INTO test_table (image) VALUES ('$image_escaped'::bytea);</literal> PostgreSQL 7.2.2 or - later does not need cast. Exception is when client and backend - character encoding does not match, there may be multi-byte - stream error. User must cast to bytea to avoid this error. + later does not need a cast. The exception is when the client and backend + character encoding does not match, and there may be multi-byte + stream error. User must then cast to bytea to avoid this error. </para> </note> </refsect1> + <refsect1 role="parameters"> + &reftitle.parameters; + <para> + <variablelist> + <varlistentry> + <term><parameter>data</parameter></term> + <listitem> + <para> + A <type>string</type> containing PostgreSQL bytea data to be converted into + a PHP binary string. + </para> + </listitem> + </varlistentry> + </variablelist> + </para> + </refsect1> + + <refsect1 role="returnvalues"> + &reftitle.returnvalues; + <para> + A <type>string</type> containing the unescaped data. + </para> + </refsect1> + + <refsect1 role="examples"> + &reftitle.examples; + <para> + <example> + <title><function>pg_unescape_bytea</function> example</title> + <programlisting role="php"> +<![CDATA[ +<?php + // Connect to the database + $dbconn = pg_connect('dbname=foo'); + + // Get the bytea data + $res = pg_query("SELECT data FROM gallery WHERE name='Pine trees'"); + $raw = pg_fetch_result($res, 'data'); + + // Convert to binary and send to the browser + header('Content-type: image/jpeg'); + echo pg_unescape_bytea($raw); +?> +]]> + </programlisting> + </example> + </para> + </refsect1> + <refsect1 role="seealso"> &reftitle.seealso; <para>