dbs Sun Jan 23 22:11:02 2005 EDT
Modified files:
/phpdoc/en/reference/pdo constants.xml
/phpdoc/en/reference/pdo/functions PDO-prepare.xml
PDOStatement-bindColumn.xml
PDOStatement-fetch.xml
PDO-lastInsertId.xml
Log:
Document constants, bindColumn, and lastInsertID.
Correct minor errors in prepare and fetch.
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/constants.xml?r1=1.1&r2=1.2&ty=u
Index: phpdoc/en/reference/pdo/constants.xml
diff -u phpdoc/en/reference/pdo/constants.xml:1.1
phpdoc/en/reference/pdo/constants.xml:1.2
--- phpdoc/en/reference/pdo/constants.xml:1.1 Wed Nov 10 17:21:18 2004
+++ phpdoc/en/reference/pdo/constants.xml Sun Jan 23 22:11:01 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<section id="pdo.constants">
&reftitle.constants;
@@ -12,7 +12,7 @@
</term>
<listitem>
<simpara>
-
+ Represents the SQL NULL data type.
</simpara>
</listitem>
</varlistentry>
@@ -23,7 +23,7 @@
</term>
<listitem>
<simpara>
-
+ Represents the SQL INTEGER data type.
</simpara>
</listitem>
</varlistentry>
@@ -34,7 +34,7 @@
</term>
<listitem>
<simpara>
-
+ Represents the SQL CHAR, VARCHAR, or other string data type.
</simpara>
</listitem>
</varlistentry>
@@ -45,7 +45,7 @@
</term>
<listitem>
<simpara>
-
+ Represents the SQL large object data type.
</simpara>
</listitem>
</varlistentry>
@@ -67,7 +67,9 @@
</term>
<listitem>
<simpara>
-
+ Specifies that the fetch method shall return each row as an object with
+ variable names that correspond to the column names returned in the result
+ set. PDO_FETCH_LAZY creates the object variable names as they are
accessed.
</simpara>
</listitem>
</varlistentry>
@@ -78,7 +80,8 @@
</term>
<listitem>
<simpara>
-
+ Specifies that the fetch method shall return each row as an array indexed
+ by column name as returned in the corresponding result set.
</simpara>
</listitem>
</varlistentry>
@@ -89,7 +92,9 @@
</term>
<listitem>
<simpara>
-
+ Specifies that the fetch method shall return each row as an array indexed
+ by column number as returned in the corresponding result set, starting at
+ column 0.
</simpara>
</listitem>
</varlistentry>
@@ -100,7 +105,9 @@
</term>
<listitem>
<simpara>
-
+ Specifies that the fetch method shall return each row as an array indexed
+ by both column name and number as returned in the corresponding result
set,
+ starting at column 0.
</simpara>
</listitem>
</varlistentry>
@@ -111,13 +118,50 @@
</term>
<listitem>
<simpara>
+ Specifies that the fetch method shall return each row as an object with
+ property names that correspond to the column names returned in the result
+ set.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_BOUND</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Specifies that the fetch method shall return TRUE and assign the values of
+ the columns in the result set to the PHP variables to which they were
+ bound with the <function>PDOStatement::bindParam()</function> method.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_COLUMN</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <constant>PDO_ATTR_AUTOCOMMIT</constant>
+ <constant>PDO_FETCH_CLASS</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_INTO</constant>
(<type>integer</type>)
</term>
<listitem>
@@ -128,7 +172,7 @@
</varlistentry>
<varlistentry>
<term>
- <constant>PDO_ATTR_SCROLL</constant>
+ <constant>PDO_ATTR_AUTOCOMMIT</constant>
(<type>integer</type>)
</term>
<listitem>
@@ -221,6 +265,51 @@
</term>
<listitem>
<simpara>
+ Force column names to a specific case specified by the PDO_CASE_*
+ constants.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ATTR_CURSOR_NAME</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ATTR_CURSOR</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ATTR_ORACLE_NULLS</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ATTR_PERSISTENT</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
</simpara>
</listitem>
@@ -265,7 +354,7 @@
</term>
<listitem>
<simpara>
-
+ Leave column names as returned by the database driver.
</simpara>
</listitem>
</varlistentry>
@@ -275,8 +364,8 @@
(<type>integer</type>)
</term>
<listitem>
- <simpara>
-
+ <simpara>
+ Force column names to lower case.
</simpara>
</listitem>
</varlistentry>
@@ -287,18 +376,101 @@
</term>
<listitem>
<simpara>
-
+ Force column names to upper case.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
- <constant>PDO_ERR_NONE</constant>
+ <constant>PDO_FETCH_ORI_NEXT</constant>
(<type>integer</type>)
</term>
<listitem>
<simpara>
-
+ Fetch the next row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_ORI_PRIOR</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the previous row in the result set. Valid only for scrollable
+ cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_ORI_FIRST</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the first row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_ORI_LAST</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the last row in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_ORI_ABS</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the requested row by row number from the result set. Valid only
+ for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_FETCH_ORI_REL</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Fetch the requested row by relative position from the current position
+ of the cursor in the result set. Valid only for scrollable cursors.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_CURSOR_FWDONLY</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Create a PDOStatement object with a forward-only cursor. This may improve
+ the performance of your application but restricts your PROStatement object
+ to fetching one row at a time from the result set in a forward direction.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_CURSOR_SCROLL</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Create a PDOStatement object with a scrollable cursor. Pass the
+ PDO_FETCH_ORI_* constants to control the rows fetched from the result set.
</simpara>
</listitem>
</varlistentry>
@@ -401,6 +573,29 @@
</simpara>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ERR_NO_PERM</constant>
+ (<type>integer</type>)
+ </term>
+ <listitem>
+ <simpara>
+
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <constant>PDO_ERR_NONE</constant>
+ (<type>string</type>)
+ </term>
+ <listitem>
+ <simpara>
+ Corresponds to SQLSTATE '00000', meaning that the SQL statement was
+ successfully issued with no errors or warnings.
+ </simpara>
+ </listitem>
+ </varlistentry>
</variablelist>
</section>
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDO-prepare.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/pdo/functions/PDO-prepare.xml
diff -u phpdoc/en/reference/pdo/functions/PDO-prepare.xml:1.2
phpdoc/en/reference/pdo/functions/PDO-prepare.xml:1.3
--- phpdoc/en/reference/pdo/functions/PDO-prepare.xml:1.2 Fri Nov 12
08:16:17 2004
+++ phpdoc/en/reference/pdo/functions/PDO-prepare.xml Sun Jan 23 22:11:02 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.PDO-prepare">
<refnamediv>
@@ -13,16 +13,50 @@
<methodsynopsis>
<type>PDOStatement</type><methodname>PDO::prepare</methodname>
<methodparam><type>string</type><parameter>statement</parameter></methodparam>
- <methodparam
choice="opt"><type>int</type><parameter>options</parameter></methodparam>
</methodsynopsis>
&warn.experimental.func;
<para>
- Prepares an SQL statement to be executed by the statement-handle
- <function>PDO::execute</function> method. The SQL statement can contain
zero
- or more named (:name) or question mark (?) parameter markers.
+ Prepares an SQL statement to be executed by the
+ <function>PDOStatement::execute</function> method. The SQL statement can
+ contain zero or more named (:name) or question mark (?) parameter markers
+ for which real values will be substituted when the statement is executed.
</para>
- <example><title>Prepare and execute an SQL statement</title>
+ <para>
+ Calling <function>PDO::prepare</function> and
<function>PDOStatement::execute</function>
+ for statements that will be issued multiple times with different parameter
+ values optimizes the performance of your application and helps prevent SQL
+ injection attacks.
+ </para>
+ </refsect1>
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>statement</parameter></term>
+ <listitem>
+ <para>
+ This must be a valid SQL statement for the target database server.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ If the database server successfully prepares the statement,
+ <function>PDO::prepare</function> returns a PDOStatement object.
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <example>
+ <title>Prepare an SQL statement with named parameters</title>
<programlisting role='php'>
<![CDATA[
<?php
@@ -31,10 +65,41 @@
FROM fruit
WHERE calories < :calories AND colour = :colour');
$sth->execute(array(':calories' => 150, ':colour' => 'red'));
+$red = $sth->fetchAll();
+$sth->execute(array(':calories' => 175, ':colour' => 'yellow'));
+$yellow = $sth->fetchAll();
?>
]]>
</programlisting>
</example>
+ <example>
+ <title>Prepare an SQL statement with question mark parameters</title>
+ <programlisting role='php'>
+<![CDATA[
+<?php
+/* Execute a prepared statement by passing an array of values */
+$sth = $dbh->prepare('SELECT name, colour, calories
+ FROM fruit
+ WHERE calories < ? AND colour = ?');
+$sth->execute(array(150, 'red'));
+$red = $sth->fetchAll();
+$sth->execute(array(175, 'yellow'));
+$yellow = $sth->fetchAll();
+?>
+]]>
+ </programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>PDO::exec</function></member>
+ <member><function>PDO::query</function></member>
+ <member><function>PDOStatement::execute</function></member>
+ </simplelist>
+ </para>
</refsect1>
</refentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml
diff -u phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml:1.2
phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml:1.3
--- phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml:1.2 Thu Nov
11 03:16:32 2004
+++ phpdoc/en/reference/pdo/functions/PDOStatement-bindColumn.xml Sun Jan
23 22:11:02 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.PDOStatement-bindColumn">
<refnamediv>
@@ -16,18 +16,138 @@
<methodparam><type>mixed</type><parameter
role="reference">param</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>type</parameter></methodparam>
<methodparam
choice="opt"><type>int</type><parameter>maxlen</parameter></methodparam>
- <methodparam
choice="opt"><type>mixed</type><parameter>driverdata</parameter></methodparam>
+ <methodparam
choice="opt"><type>mixed</type><parameter>driver_options</parameter></methodparam>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
<para>
On each row fetch <parameter>param</parameter> will contain the value of
the corresponding column. <parameter>column</parameter> is the 1-based
- offset of the column, or the column name. For portability, don't call
- this before <function>PDO::execute</function>.
+ offset of the column, or the column name. For maximum portability, do not
+ call this function before calling
+ <function>PDOStatement::execute</function>.
</para>
</refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>column</parameter></term>
+ <listitem>
+ <para>
+ Number of the column (1-indexed) in the result set.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>param</parameter></term>
+ <listitem>
+ <para>
+ Name of the PHP variable to which the column will be bound.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem>
+ <para>
+ Data type of the parameter, specified by the PDO_PARAM_* constants.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>maxlen</parameter></term>
+ <listitem>
+ <para>
+ Maximum length of the parameter.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>driver_options</parameter></term>
+ <listitem>
+ <para>
+
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Binding result set output to PHP variables</title>
+ <para>
+ Binding columns in the result set to PHP variables is an effective
+ way to make the data contained in each row immediately available to
+ your application. The following example demonstrates how PDO allows
+ you to bind and retrieve columns with a variety of options and with
+ intelligent defaults.
+ </para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+function readData($dbh) {
+ $sql = 'SELECT name, colour, calories FROM fruit';
+ try {
+ $stmt = $dbh->prepare($sql);
+ $stmt->execute();
+
+ /* Bind by column number with an explicit data type & length */
+ $stmt->bindColumn(1, $name, PDO_PARAM_STR, 64);
+
+ /* Bind by column number with default data type & length */
+ $stmt->bindColumn(2, $colour);
+
+ /* Bind by column name with default data type & length */
+ $stmt->bindColumn('CALORIES', $cals);
+
+ while ($row = $stmt->fetch(PDO_FETCH_BOUND)) {
+ $data = $name . "\t" . $colour . "\t" . $cals . "\n";
+ print $data;
+ }
+ }
+ catch (PDOException $e) {
+ print $e->getMessage();
+ }
+}
+readData($dbh);
+?>
+ ]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+ <![CDATA[
+apple red 150
+banana yellow 175
+kiwi green 75
+orange orange 150
+mango red 200
+strawberry red 25
+ ]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><function>PDOStatement::execute</function></member>
+ <member><function>PDOStatement::fetch</function></member>
+ <member><function>PDOStatement::fetchAll</function></member>
+ <member><function>PDOStatement::fetchSingle</function></member>
+ </simplelist>
+ </para>
+ </refsect1>
+
</refentry>
<!-- Keep this comment at the end of the file
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml?r1=1.3&r2=1.4&ty=u
Index: phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml
diff -u phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml:1.3
phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml:1.4
--- phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml:1.3 Fri Nov
19 17:41:59 2004
+++ phpdoc/en/reference/pdo/functions/PDOStatement-fetch.xml Sun Jan 23
22:11:02 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.PDOStatement-fetch">
<refnamediv>
@@ -33,7 +33,8 @@
<listitem><para>
<literal>PDO_FETCH_BOUND</literal>: returns &true; and assigns the
values of the columns in your result set to the PHP variables to which
- they were bound with the <function>PDO::bindParam</function> method
+ they were bound with the <function>PDOStatement::bindParam</function>
+ method
</para></listitem>
<listitem><para>
<literal>PDO_FETCH_LAZY</literal>: combines
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml?r1=1.2&r2=1.3&ty=u
Index: phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml
diff -u phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml:1.2
phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml:1.3
--- phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml:1.2 Thu Nov 11
03:16:32 2004
+++ phpdoc/en/reference/pdo/functions/PDO-lastInsertId.xml Sun Jan 23
22:11:02 2005
@@ -1,27 +1,70 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<refentry id="function.PDO-lastInsertId">
<refnamediv>
<refname>PDO::lastInsertId</refname>
<refpurpose>
- Returns the number id of rows that we affected by the last call to
PDO::exec()
+ Returns the ID of the last inserted row
</refpurpose>
</refnamediv>
- <refsect1>
+ <refsect1 role="description">
<title>Description</title>
<methodsynopsis>
<type>int</type><methodname>PDO::lastInsertId</methodname>
<void/>
</methodsynopsis>
- &warn.undocumented.func;
+ &warn.experimental.func;
<note>
<para>
- Not always meaningful.
+ Due to differences between database server implmenetations, this method
+ may not always return a meaningful result.
</para>
</note>
</refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ Returns an integer representing the row ID of the last row that was
+ inserted into the database. If the PDO driver does not support this
+ capability, <function>PDO::lastInsertID</function> issues a PDOWarning
+ exception.
+ </para>
+ </refsect1>
+
+ <!-- Use when examples exist
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>Retrieving the last insert ID</title>
+ <para>
+ The following example demonstrates how to use the
+ <function>PDO::lastInsertID</function> method to retrieve the row
+ identifier for the last row that has been inserted into the database.
+ </para>
+ <programlisting role="php">
+ <![CDATA[
+ <?php
+ if ($anexample === true) {
+ echo 'Use the PEAR Coding Standards';
+ }
+ ?>
+ ]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+ <![CDATA[
+ Use the PEAR Coding Standards
+ ]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+ -->
+
</refentry>
<!-- Keep this comment at the end of the file
