cvs: phpdoc /en/reference/pdo/functions PDOStatement-getColumnMeta.xml

dbs Tue Mar 8 19:17:19 2005 EDT Modified files: /phpdoc/en/reference/pdo/functions PDOStatement-getColumnMeta.xml Log: Actually document PDOStatement::getColumnMeta. http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml?r1=1.1&r2=1.2&ty=u Index: phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml diff -u phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml:1.1 phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml:1.2 --- phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml:1.1 Mon Jan 17 22:16:39 2005 +++ phpdoc/en/reference/pdo/functions/PDOStatement-getColumnMeta.xml Tue Mar 8 19:17:15 2005 @@ -1,21 +1,31 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!-- $Revision: 1.1 $ --> +<!-- $Revision: 1.2 $ --> <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. --> <refentry id="function.PDOStatement-getColumnMeta"> <refnamediv> <refname>PDOStatement::getColumnMeta</refname> <refpurpose> - Returns meta data for a numbered column + Returns metadata for a column in a result set </refpurpose> </refnamediv> <refsect1 role="description"> &reftitle.description; <methodsynopsis> - <type>array</type><methodname>PDOStatement::getColumnMeta</methodname> - <methodparam><type>int</type><parameter>$column</parameter></methodparam> + <type>mixed</type><methodname>PDOStatement::getColumnMeta</methodname> + <methodparam><type>int</type><parameter>column</parameter></methodparam> </methodsynopsis> - &warn.undocumented.func; + &warn.experimental.func; + <para> + Retrieves the metadata for a 0-indexed column in a result set as an + associative array. + </para> + <warning> + <simpara> + Not all PDO drivers support + <function>PDOStatement::getColumnMeta</function>. + </simpara> + </warning> </refsect1> <refsect1 role="parameters"> @@ -23,21 +33,76 @@ <para> <variablelist> <varlistentry> - <term><parameter>$column</parameter></term> + <term><parameter>column</parameter></term> <listitem> <para> - Its description + The 0-indexed column in the result set. </para> </listitem> </varlistentry> </variablelist> </para> </refsect1> + <refsect1 role="returnvalues"> &reftitle.returnvalues; <para> - What the function returns, first on success, then on failure. See - also the &return.success; entity + Returns an associative array containing the following values representing + the metadata for a single column: + </para> + <table> + <title>Column metadata</title> + <tgroup cols='2'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Name</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry><literal>native_type</literal></entry> + <entry>The PHP native type used to represent the column value.</entry> + </row> + <row> + <entry><literal><varname>driver</varname>:decl_type</literal></entry> + <entry>The SQL type used to represent the column value in the database. + If the column in the result set is the result of a function, this value + is not returned by <function>PDOStatement::getColumnMeta</function>. + </entry> + </row> + <row> + <entry><literal>flags</literal></entry> + <entry>Any flags set for this column.</entry> + </row> + <row> + <entry><literal>name</literal></entry> + <entry>The name of this column as returned by the database.</entry> + </row> + <row> + <entry><literal>len</literal></entry> + <entry>The length of this column. Normally <literal>-1</literal> for + types other than floating point decimals.</entry> + </row> + <row> + <entry><literal>precision</literal></entry> + <entry>The numeric precision of this column. Normally + <literal>0</literal> for types other than floating point + decimals.</entry> + </row> + <row> + <entry><literal>pdo_type</literal></entry> + <entry>The type of this column as represented by the + <literal>PDO_PARAM_*</literal> constants.</entry> + </row> + </tbody> + </tgroup> + </table> + <para> + Returns &false; if the requested column does not exist in the result set, + or if no result set exists. </para> </refsect1> @@ -50,7 +115,6 @@ </refsect1> --> - <!-- Use when a CHANGELOG exists <refsect1 role="changelog"> &reftitle.changelog; @@ -75,51 +139,58 @@ </refsect1> --> - - <!-- Use when examples exist <refsect1 role="examples"> &reftitle.examples; <para> <example> - <title><function>A PDOStatement-getColumnMeta example</title> + <title>Retrieving column metadata</title> <para> - Any text that describes the purpose of the example, or - what goes on in the example should go here (inside the - <example> tag, not out + The following example shows the results of retrieving the metadata for a + single column generated by a function (COUNT) in a PDO_SQLITE driver. </para> <programlisting role="php"> <![CDATA[ <?php -if ($anexample === true) { - echo 'Use the PEAR Coding Standards'; -} +$select = $DB->query('SELECT COUNT(*) FROM fruit'); +$meta = $select->getColumnMeta(0); +var_dump($meta); ?> ]]> </programlisting> &example.outputs; <screen> <![CDATA[ -Use the PEAR Coding Standards +array(6) { + ["native_type"]=> + string(7) "integer" + ["flags"]=> + array(0) { + } + ["name"]=> + string(8) "COUNT(*)" + ["len"]=> + int(-1) + ["precision"]=> + int(0) + ["pdo_type"]=> + int(2) +} + ]]> </screen> </example> </para> </refsect1> - --> - - <!-- Use when adding See Also links <refsect1 role="seealso"> &reftitle.seealso; <para> <simplelist> - <member><function></function></member> - <member>Or <link linkend="somethingelse">something else</link></member> + <member><function>PDOStatement::columnCount</function></member> + <member><function>PDOStatement::rowCount</function></member> </simplelist> </para> </refsect1> - --> - </refentry>