misc tweaks

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@190460 c90b9560-bf6c-de11-be94-00142212c4b1
This commit is contained in:
Wez Furlong 2005-07-11 04:38:55 +00:00
parent 8381f855ac
commit ffc3345912
17 changed files with 159 additions and 121 deletions

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<section id="pdo.constants">
&reftitle.constants;
@ -266,7 +266,9 @@
</term>
<listitem>
<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.
</simpara>
</listitem>
</varlistentry>
@ -370,6 +372,19 @@
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>PDO_ATTR_DRIVER_NAME</constant>
(<type>string</type>)
</term>
<listitem>
<simpara>
Returns the name of the driver.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>
<constant>PDO_ATTR_ORACLE_NULLS</constant>
@ -426,7 +441,7 @@
<listitem>
<simpara>
Do not raise an error or exception if an error occurs. The developer is
expected to explicitly check for errors.
expected to explicitly check for errors. This is the default mode.
</simpara>
</listitem>
</varlistentry>

View file

@ -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-beginTransaction">
<refnamediv>
@ -17,9 +17,10 @@
</methodsynopsis>
&warn.experimental.func;
<para>
Turns off autocommit mode. Call <function>PDO::commit</function> or
<function>PDO::rollback</function> to end the transaction and return to
autocommit mode.
Turns off autocommit mode. While autocommit mode is turned off, changes
made to the database via the PDO object instance are not committed until
you end the transaction by calling either
<function>PDO::commit</function> or <function>PDO::rollback</function>.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.11 $ -->
<!-- $Revision: 1.12 $ -->
<refentry id="function.PDO-construct">
<refnamediv>
<refname>PDO::__construct</refname>
@ -99,6 +99,22 @@
<para><userinput>sqlite::memory:</userinput></para>
</listitem>
</varlistentry>
<varlistentry>
<term><constant>sqlite (version 2)</constant></term>
<listitem>
<para><userinput>sqlite2:/path/to/database</userinput></para>
<para>To create a database in memory, use:</para>
<para><userinput>sqlite2::memory:</userinput></para>
<note>
<para>
The SQLite 2 PDO driver provides access to old SQLite 2
databases that you may have created with earlier versions
of PHP. It is recommended that you migrate to SQLite 3 (the
PDO_SQLITE driver), as it has superior features and performance.
</para>
</note>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-errorCode">
<refnamediv>
@ -21,17 +21,23 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a SQLSTATE, a five-character alphanumeric identifier defined in the ANSI SQL
standard.
Returns a SQLSTATE, a five-character alphanumeric identifier defined in
the ANSI SQL-92 standard. Briefly, an SQLSTATE consists of a
two-character class value followed by a three-character subclass value. A
class value of 01 indicates a warning and is accompanied by a return code
of SQL_SUCCESS_WITH_INFO. Class values other than '01', except for the
class 'IM', indicate an error. The class 'IM' is specific to warnings
and errors that derive from the implementation of PDO (or perhaps ODBC,
if you're using the ODBC driver) itself. The subclass value '000' in any
class indicates that there is no subclass for that SQLSTATE.
</para>
<para>
<function>PDO::errorCode</function> only retrieves error codes for operations
performed directly on the database handle. If you create a PDOStatement
object through <function>PDO::prepare</function> or
<function>PDO::query</function> and invoke an error on the statement
handle, <function>PDO::errorCode</function> will return
<literal>PDO_ERR_NONE</literal>. You must call
<function>PDOStatement::errorCode</function> to return the error
handle, <function>PDO::errorCode</function> will not reflect that error.
You must call <function>PDOStatement::errorCode</function> to return the error
code for an operation performed on a particular statement handle.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-errorInfo">
<refnamediv>
@ -52,15 +52,14 @@
</para>
<para>
<function>PDO::errorInfo</function> only retrieves error information
for operations performed directly on the database handle. If you create
a PDOStatement object through <function>PDO::prepare</function> or
<function>PDO::errorInfo</function> only retrieves error information for
operations performed directly on the database handle. If you create a
PDOStatement object through <function>PDO::prepare</function> or
<function>PDO::query</function> and invoke an error on the statement
handle, <function>PDO::errorInfo</function> will insert an error code
of <literal>PDO_ERR_NONE</literal> into the first element of the returned
array. You must call <function>PDOStatement::errorInfo</function> to
return the error information for an operation performed on a particular
statement handle.
handle, <function>PDO::errorInfo</function> will not reflect the error
from the statement handle. You must call
<function>PDOStatement::errorInfo</function> to return the error
information for an operation performed on a particular statement handle.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-exec">
<refnamediv>
@ -18,7 +18,7 @@
&warn.experimental.func;
<para>
<function>PDO::exec</function> prepares and executes an SQL statement in
<function>PDO::exec</function> executes an SQL statement in
a single function call, returning the number of rows affected by the
statement.
</para>
@ -26,7 +26,7 @@
<function>PDO::exec</function> does not return results from a SELECT
statement. For a SELECT statement that you only need to issue once
during your program, consider issuing <function>PDO::query</function>.
For a SELECT statement that you need to issue multiple times, prepare
For a statement that you need to issue multiple times, prepare
a PDOStatement object with <function>PDO::prepare</function> and issue
the statement with <function>PDOStatement::execute</function>.
</para>
@ -89,7 +89,6 @@ $dbh = new PDO('odbc:sample', 'db2inst1', 'ibmdb2');
$count = $dbh->exec("DELETE FROM fruit WHERE colour = 'red'");
/* Return number of rows that were deleted */
print("Return number of rows that were deleted:\n");
print("Deleted $count rows.\n");
?>
]]>
@ -97,7 +96,6 @@ print("Deleted $count rows.\n");
&example.outputs;
<screen>
<![CDATA[
Return number of rows that were deleted:
Deleted 1 rows.
]]>
</screen>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-getAttribute">
<refnamediv>
@ -24,8 +24,8 @@
</para>
<para>
Note that some databases may not support all of the database connection
attributes.
Note that some database/driver combinations may not support all of the
database connection attributes.
</para>
</refsect1>
@ -45,6 +45,7 @@
<member><literal>PDO_ATTR_CASE</literal></member>
<member><literal>PDO_ATTR_CLIENT_VERSION</literal></member>
<member><literal>PDO_ATTR_CONNECTION_STATUS</literal></member>
<member><literal>PDO_ATTR_DRIVER_NAME</literal></member>
<member><literal>PDO_ATTR_ERRMODE</literal></member>
<member><literal>PDO_ATTR_ORACLE_NULLS</literal></member>
<member><literal>PDO_ATTR_PERSISTENT</literal></member>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.7 $ -->
<!-- $Revision: 1.8 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-lastInsertId">
<refnamediv>
@ -19,12 +19,13 @@
<para>
Returns the ID of the last inserted row, or the last value from a
sequence object.
sequence object, depending on the underlying driver.
</para>
<note>
<para>
Due to differences between database server implementations, this method
may not always return a meaningful result.
This method may not return a meaningful/consistent result across different PDO
drivers, because the underlying database may not even support the notion
of auto-increment fields or sequences.
</para>
</note>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-prepare">
<refnamediv>
@ -22,14 +22,23 @@
<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.
You cannot use named and question mark parameter markers within the same
SQL statement.
You cannot use both named and question mark parameter markers within the same
SQL statement; pick one or the other parameter style.
</para>
<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.
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 by allowing the driver to negotiate
client and/or server side caching of the query plan and meta information,
and helps to prevent SQL injection attacks by eliminating the need to
manually quote the parameters.
</para>
<para>
PDO will emulate prepared statements/bound parameters for drivers that do
not natively support them, and can also rewrite named or question mark
style parameter markers to something more appropriate, if the driver
supports one style but not the other.
</para>
</refsect1>
<refsect1 role="parameters">
@ -53,6 +62,8 @@
returns. You would most commonly use this to set the
<literal>PDO_ATTR_CURSOR</literal> value to
<literal>PDO_CURSOR_SCROLL</literal> to request a scrollable cursor.
Some drivers have driver specific options that may be set at
prepare-time.
</para>
</listitem>
</varlistentry>

View file

@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
<!-- $Revision: 1.3 $ -->
<!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-query">
<refnamediv>
@ -18,14 +18,15 @@
&warn.experimental.func;
<para>
<function>PDO::query</function> prepares and executes an SQL statement in
<function>PDO::query</function> executes an SQL statement in
a single function call, returning the result set (if any) returned by the
statement as a PDOStatement object.
</para>
<para>
For a SELECT statement that you need to issue multiple times, prepare
a PDOStatement object with <function>PDO::prepare</function> and issue
the statement with <function>PDOStatement::execute</function>.
For a query that you need to issue multiple times, you will realize better
performance if you prepare a PDOStatement object using
<function>PDO::prepare</function> and issue the statement with multiple
calls to <function>PDOStatement::execute</function>.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?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.PDO-quote">
<refnamediv>
@ -20,14 +20,17 @@
<para>
<function>PDO::quote</function> places quotes around the input
string and escapes and single quotes within the input string.
Quoting input strings has been a common means of attempting to
prevent SQL injection attacks; however, an even safer approach
is to use prepared statements with named parameters or placeholders
for the input values.
string and escapes and single quotes within the input string, using a
quoting style appropriate to the underlying driver.
</para>
<para>
Not all PDO drivers implement this method.
If you're using this function to build SQL, it is recommended that you
using prepared statements and bound parameters instead, as it is not only
more convenient, but often much faster.
</para>
<para>
Not all PDO drivers implement this method (notably PDO_ODBC). Consider
using prepared statements instead.
</para>
</refsect1>
<refsect1 role="parameters">
@ -58,7 +61,8 @@
&reftitle.returnvalues;
<para>
Returns a quoted string that is theoretically safe to pass into an
SQL statement.
SQL statement. Returns &false; if the driver does not support quoting in
this way.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.4 $ -->
<!-- $Revision: 1.5 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDO-rollBack">
<refnamediv>
@ -18,14 +18,13 @@
&warn.experimental.func;
<para>
When issued against databases that support transactions,
<function>PDO::rollBack</function> rolls back any work in progress
and returns the connection state to autocommit mode.
Rolls back the current transaction, as initiated by
<function>PDO::beginTransaction</function>. It is an error to call this
method if no transaction is active.
</para>
<para>
You must issue <function>PDO::beginTransaction</function> to set the
connection state to manual commit mode before issuing
<function>PDO::rollBack</function> has any effect.
If the database was set to autocommit mode, this function will restore
autocommit mode after it has rolled back the transaction.
</para>
</refsect1>

View file

@ -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-setAttribute">
<refnamediv>
@ -18,8 +18,9 @@
&warn.experimental.func;
<para>
Sets a database connection attribute. The generic PDO connection attributes
include:
Sets an attribute on the database handle. Some of the available generic
attributes are listed below; some drivers may make use of
additional driver specific attributes.
<itemizedlist>
<listitem><para>
<literal>PDO_ATTR_CASE</literal>: Force column names to a specific case.
@ -37,7 +38,6 @@
</itemizedlist>
</para></listitem>
</itemizedlist>
PDO drivers may define further driver-specific attributes.
</para>
</refsect1>
</refentry>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.5 $ -->
<!-- $Revision: 1.6 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-bindColumn">
<refnamediv>
@ -15,19 +15,23 @@
<methodparam><type>mixed</type><parameter>column</parameter></methodparam>
<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>driver_options</parameter></methodparam>
</methodsynopsis>
&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 maximum portability, do not
call this function before calling
<function>PDOStatement::execute</function>.
<function>PDOStatement::bindColumn</function> arranges to have a
particular variable bound to a given column in the result-set from a
query. Each call to <function>PDOStatement::fetch</function> or
<function>PDOStatement::fetchAll</function> will update all the variables
that are bound to columns.
</para>
<note>
<para>
Since information about the columns is not always available to PDO until
the statement is executed, portable applications should call this
function <emphasis>after</emphasis> <function>PDO::execute</function>.
</para>
</note>
</refsect1>
<refsect1 role="parameters">
@ -38,7 +42,9 @@
<term><parameter>column</parameter></term>
<listitem>
<para>
Number of the column (1-indexed) in the result set.
Number of the column (1-indexed) or name of the column in the result set.
If using the column name, be aware that the name should match the
case of the column, as returned by the driver.
</para>
</listitem>
</varlistentry>
@ -58,23 +64,7 @@
</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>
</variablelist>
</para>
</refsect1>
@ -99,14 +89,12 @@ function readData($dbh) {
$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 */
/* Bind by column number */
$stmt->bindColumn(1, $name);
$stmt->bindColumn(2, $colour);
/* Bind by column name with default data type & length */
$stmt->bindColumn('CALORIES', $cals);
/* Bind by column name */
$stmt->bindColumn('calories', $cals);
while ($row = $stmt->fetch(PDO_FETCH_BOUND)) {
$data = $name . "\t" . $colour . "\t" . $cals . "\n";

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.6 $ -->
<!-- $Revision: 1.7 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<refentry id="function.PDOStatement-bindParam">
<refnamediv>
@ -20,18 +20,15 @@
</methodsynopsis>
&warn.experimental.func;
<para>
Binds an SQL statement parameter to the specified variable name. The SQL statement
parameter can either be a named placeholder or a question mark placeholder.
Binds a parameter to a corresponding named or question mark placeholder
in the SQL statement that was use to prepare the statement.
</para>
<para>
Output parameters will set the value of the bound PHP variable to the value
returned by the database when the SQL statement is executed. This enables you
to call stored procedures with output or input/output parameters, for example,
for databases that support such features.
</para>
<para>
For non-NULL input-only variables, you can pass an array of input values to
<function>PDOStatement::execute</function> instead.
Most parameters are input parameters, that is, parameters that are used
in a read-only fashion to build up the query. Some drivers support the
invocation of stored procedures that return data as output parameters,
and some also as intput/output parameters that both send in data and are
updated to receive it.
</para>
</refsect1>
@ -69,10 +66,6 @@
use the bitwise OR operator to set the PDO_PARAM_INPUT_OUTPUT bits
for the <parameter>data_type</parameter> parameter.
</para>
<para>
To pass a NULL value as an input parameter, declare the
PDO_PARAM_NULL constant.
</para>
</listitem>
</varlistentry>
<varlistentry>
@ -135,6 +128,7 @@ $sth->execute();
</programlisting>
</example>
<!--
<example><title>Pass a NULL value into a prepared statement</title>
<programlisting role='php'>
<![CDATA[
@ -155,7 +149,7 @@ $sth->execute();
]]>
</programlisting>
</example>
-->
<example><title>Call a stored procedure with an INOUT parameter</title>
<programlisting role='php'>
<![CDATA[

View file

@ -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-errorCode">
<refnamediv>
@ -20,8 +20,8 @@
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
Returns a SQLSTATE, a five-character alphanumeric identifier defined in the ANSI SQL
standard. <function>PDOStatement::errorCode</function> only retrieves error codes
Identical to <function>PDO::errorCode</function>, except that
<function>PDOStatement::errorCode</function> only retrieves error codes
for operations performed with PDOStatement objects.
</para>
</refsect1>

View file

@ -1,5 +1,5 @@
<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.24 $ -->
<!-- $Revision: 1.25 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
<reference id="ref.pdo">
<title>PDO Functions</title>
@ -190,7 +190,7 @@ bash# echo extension=pdo.so >> /usr/local/php5/lib/php.ini
</row>
<row>
<entry>PDO_ODBC</entry>
<entry>ODBC v3 (IBM DB2 and unixODBC)</entry>
<entry>ODBC v3 (IBM DB2, unixODBC and win32 ODBC)</entry>
</row>
<row>
<entry>PDO_PGSQL</entry>
@ -200,6 +200,10 @@ bash# echo extension=pdo.so >> /usr/local/php5/lib/php.ini
<entry>PDO_SQLITE</entry>
<entry>SQLite 3.x</entry>
</row>
<row>
<entry>sqlite</entry>
<entry>SQLite 2.x (PHP 5.1 and up)</entry>
</row>
</tbody>
</tgroup>
</informaltable>