wez Sun Sep 18 10:03:32 2005 EDT
Modified files:
/phpdoc/en/reference/pdo constants.xml reference.xml
Log:
flesh out some more
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/constants.xml?r1=1.10&r2=1.11&ty=u
Index: phpdoc/en/reference/pdo/constants.xml
diff -u phpdoc/en/reference/pdo/constants.xml:1.10
phpdoc/en/reference/pdo/constants.xml:1.11
--- phpdoc/en/reference/pdo/constants.xml:1.10 Thu Sep 15 16:57:50 2005
+++ phpdoc/en/reference/pdo/constants.xml Sun Sep 18 10:03:30 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc.
-->
<section id="pdo.constants">
&reftitle.constants;
@@ -68,7 +68,7 @@
</term>
<listitem>
<simpara>
-
+ Represents a recordset type. Not currently supported by any drivers.
</simpara>
</listitem>
</varlistentry>
@@ -280,7 +280,8 @@
<simpara>
Setting the prefetch size allows you to balance speed against memory
usage for your application. Not all database/driver combinations support
- setting of the prefetch size.
+ setting of the prefetch size. A larger prefetch size results in
+ increased performance at the cost of higher memory usage.
</simpara>
</listitem>
</varlistentry>
@@ -302,7 +303,8 @@
</term>
<listitem>
<simpara>
-
+ See the <link linkend='pdo.error-handling'>Errors and error
+ handling</link> section for more information about this attribute.
</simpara>
</listitem>
</varlistentry>
@@ -313,7 +315,8 @@
</term>
<listitem>
<simpara>
-
+ This is a read only attribute; it will return information about the
+ version of the database server to which PDO is connected.
</simpara>
</listitem>
</varlistentry>
@@ -324,7 +327,8 @@
</term>
<listitem>
<simpara>
-
+ This is a read only attribute; it will return information about the
+ version of the client libraries that the PDO driver is using.
</simpara>
</listitem>
</varlistentry>
@@ -335,7 +339,8 @@
</term>
<listitem>
<simpara>
-
+ This is a read only attribute; it will return some meta information about
the
+ database server to which PDO is connected.
</simpara>
</listitem>
</varlistentry>
@@ -369,7 +374,8 @@
</term>
<listitem>
<simpara>
-
+ Get or set the name to use for a cursor. Most useful when using
+ scrollable cursors and positioned updates.
</simpara>
</listitem>
</varlistentry>
@@ -380,7 +386,11 @@
</term>
<listitem>
<simpara>
-
+ Selects the cursor type. PDO currently supports either
+ <constant>PDO_CURSOR_FWDONLY</constant> and
+ <constant>PDO_CURSOR_SCROLL</constant>. Stick with
+ <constant>PDO_CURSOR_FWDONLY</constant> unless you know that you need a
+ scrollable cursor.
</simpara>
</listitem>
</varlistentry>
@@ -417,7 +427,7 @@
</term>
<listitem>
<simpara>
- Convert empty strings to SQL NULL values.
+ Convert empty strings to SQL NULL values on data fetches.
</simpara>
</listitem>
</varlistentry>
@@ -429,6 +439,8 @@
<listitem>
<simpara>
Request a persistent connection, rather than creating a new connection.
+ See <link linkend='pdo.connections'>Connections and Connection
+ management</link> for more information on this attribute.
</simpara>
</listitem>
</varlistentry>
@@ -441,7 +453,8 @@
<simpara>
Prepend the containing catalog name to each column name returned in the
result set. The catalog name and column name are separated by a decimal
- (.) character.
+ (.) character. Support of this attribute is at the driver level; it may
+ not be supported by your driver.
</simpara>
</listitem>
</varlistentry>
@@ -454,7 +467,8 @@
<simpara>
Prepend the containing table name to each column name returned in the
result set. The table name and column name are separated by a decimal (.)
- character.
+ character. Support of this attribute is at the driver level; it may not
+ be supported by your driver.
</simpara>
</listitem>
</varlistentry>
@@ -467,6 +481,8 @@
<simpara>
Do not raise an error or exception if an error occurs. The developer is
expected to explicitly check for errors. This is the default mode.
+ See <link linkend='pdo.error-handling'>Errors and error handling</link>
+ for more information about this attribute.
</simpara>
</listitem>
</varlistentry>
@@ -478,6 +494,8 @@
<listitem>
<simpara>
Issue a PHP E_WARNING message if an error occurs.
+ See <link linkend='pdo.error-handling'>Errors and error handling</link>
+ for more information about this attribute.
</simpara>
</listitem>
</varlistentry>
@@ -488,7 +506,9 @@
</term>
<listitem>
<simpara>
- Throw a PDOException if an error occurs.
+ Throw a <classname>PDOException</classname> if an error occurs.
+ See <link linkend='pdo.error-handling'>Errors and error handling</link>
+ for more information about this attribute.
</simpara>
</listitem>
</varlistentry>
@@ -601,9 +621,9 @@
</term>
<listitem>
<simpara>
- Create a PDOStatement object with a forward-only cursor. This may improve
- the performance of your application but restricts your PDOStatement object
- to fetching one row at a time from the result set in a forward direction.
+ Create a PDOStatement object with a forward-only cursor. This is the
+ default cursor choice, as it is the fastest and most common data access
+ pattern in PHP.
</simpara>
</listitem>
</varlistentry>
@@ -627,7 +647,11 @@
<listitem>
<simpara>
Corresponds to SQLSTATE '00000', meaning that the SQL statement was
- successfully issued with no errors or warnings.
+ successfully issued with no errors or warnings. This constant is for
+ your convenience when checking <function>PDO::errorCode</function> or
+ <function>PDOStatement::errorCode</function> to determine if an error
+ occurred. You will usually know if this is the case by examining the
+ return code from the method that raised the error condition anyway.
</simpara>
</listitem>
</varlistentry>
http://cvs.php.net/diff.php/phpdoc/en/reference/pdo/reference.xml?r1=1.37&r2=1.38&ty=u
Index: phpdoc/en/reference/pdo/reference.xml
diff -u phpdoc/en/reference/pdo/reference.xml:1.37
phpdoc/en/reference/pdo/reference.xml:1.38
--- phpdoc/en/reference/pdo/reference.xml:1.37 Sun Sep 11 23:44:38 2005
+++ phpdoc/en/reference/pdo/reference.xml Sun Sep 18 10:03:30 2005
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.37 $ -->
+<!-- $Revision: 1.38 $ -->
<!-- Purpose: database.abstract -->
<!-- Membership: pecl, bundled -->
<!-- State:experimental -->
@@ -608,7 +608,7 @@
<itemizedlist>
<listitem>
<para>
- PDO_ERRMODE_SILENT
+ <constant>PDO_ERRMODE_SILENT</constant>
</para>
<para>
This is the default mode. PDO will simply set the error code for you
@@ -625,7 +625,7 @@
</listitem>
<listitem>
<para>
- PDO_ERRMODE_WARNING
+ <constant>PDO_ERRMODE_WARNING</constant>
</para>
<para>
In addition to setting the error code, PDO will emit a traditional
@@ -636,23 +636,28 @@
</listitem>
<listitem>
<para>
- PDO_ERRMODE_EXCEPTION
+ <constant>PDO_ERRMODE_EXCEPTION</constant>
</para>
<para>
- In addition to setting the error code, PDO will throw a PDOException
+ In addition to setting the error code, PDO will throw a
+ <classname>PDOException</classname>
and set its properties to reflect the error code and error
information. This setting is also useful during debugging, as it will
effectively "blow up" the script at the point of the error, very
quickly pointing a finger at potential problem areas in your code
(remember: transactions are automatically rolled back if the exception
causes the script to terminate).
- </para>
- <para>
+ </para>
+ <para>
Exception mode is also useful because you can structure your error
handling more clearly than with traditional PHP-style warnings, and
with less code/nesting than by running in silent mode and explicitly
checking the return value of each database call.
</para>
+ <para>
+ See <link linkend='language.exceptions'>Exceptions</link> for more
+ information about Exceptions in PHP.
+ </para>
</listitem>
</itemizedlist>
<para>
@@ -674,9 +679,11 @@
"large" data in your database. Large typically means "around 4kb or
more", although some databases can happily handle up to 32kb before data
becomes
"large". Large objects can be either textual or binary in nature. PDO
- allows you to work with this large data type by using the PDO_PARAM_LOB
+ allows you to work with this large data type by using the
+ <constant>PDO_PARAM_LOB</constant>
type code in your <function>PDOStatement::bindParam</function> or
- <function>PDOStatement::bindColumn</function> calls. PDO_PARAM_LOB tells
+ <function>PDOStatement::bindColumn</function> calls.
+ <constant>PDO_PARAM_LOB</constant> tells
PDO to map the data as a stream, so that you can manipulate it using the
<link linkend='ref.stream'>PHP Streams API</link>.
</para>
@@ -952,6 +959,35 @@
</itemizedlist>
</section>
</section>
+
+ <section id='pdo.class.PDOException'>
+ <title><classname>PDOException</classname></title>
+ <para>
+ Represents an error raised by PDO. You should not throw a
+ <classname>PDOException</classname> from your own code.
+ See <link linkend='language.exceptions'>Exceptions</link> for more
+ information about Exceptions in PHP.
+ </para>
+ <example>
+ <title>The PDOException class</title>
+ <programlisting role='php'>
+<![CDATA[
+<?php
+class PDOException extends Exception
+{
+ public $errorInfo = null; // corresponds to PDO::errorInfo()
+ // or PDOStatement::errorInfo()
+ protected $message; // textual error message
+ // use Exception::getMessage() to access it
+ protected $code; // SQLSTATE error code
+ // use Exception::getCode() to access it
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </section>
+
</section>
&reference.pdo.constants;
</partintro>
