cvs: peardoc /en/core db.xml
| From: | Martin Jansen | Date: | Mon, 17 Dec 2001 18:14:11 +0000 |
| Subject: | cvs: peardoc /en/core db.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-1588@lists.php.net to get a copy of this message | ||
mj Mon Dec 17 13:14:11 2001 EDT
Modified files:
/peardoc/en/core db.xml
Log:
* Improve some formulations and indent in DB chapter
# Sorry for mixing this changes.
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.3 peardoc/en/core/db.xml:1.4 --- peardoc/en/core/db.xml:1.3 Sun Dec 16 15:14:33 2001 +++ peardoc/en/core/db.xml Mon Dec 17 13:14:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -13,13 +13,13 @@ <refentry id="core.db.dsn"> <refnamediv> <refname>DSN</refname> - <refpurpose>The Data Source Name</refpurpose> + <refpurpose>The data source name</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> To connect to a database through PEAR::DB, you have to create a - valid <acronym>DSN - Data Source Name</acronym>. This DSN + valid <acronym>DSN - data source name</acronym>. This DSN consists of the: </simpara> <para> @@ -41,10 +41,6 @@ Host specification (hostname[:port]) </member> <member> - <parameter>hostspec</parameter>: - Host specification (hostname[:port]) - </member> - <member> <parameter>database</parameter>: Database to use on the DBMS server </member> @@ -77,7 +73,7 @@ phptype </programlisting> - The currently supported (the <parameter>phptype</parameter> DSN part) are: + The currently supported database backends are: <programlisting role="php"> mysql -> MySQL @@ -98,7 +94,8 @@ <para> Please note, that some features may be not supported by all database backends. Please refer to the PEAR DB extensions status document located at: - <parameter>pear base dir</parameter>/DB/STATUS to get the detailed list. + <parameter>pear base dir</parameter>/DB/STATUS to get a detailed list + about what features are supported by which backend. </para> </warning> </para> @@ -113,30 +110,36 @@ <refsect1> <title>Description</title> <simpara> - To connect use <function>DB::connect</function>, this function requires a - valid <link linkend="packages.db.dsn">DSN</link> as parameter and optional - a boolean value, set them true, when you want a persistent connection. In case of - success you get a new instance of the database clase. It is strongly - recommened to check this return value with <function>DB::isError</function>. - To disconnect use the method <function>disconnect</function> of your - database class instance. + To connect to a database you have to use the function + <function>DB::connect</function>, which requires a valid + <link linkend="packages.db.dsn">DSN</link> as parameter and optional + a boolean value, which determines wether to use a persistent connection + or not. In case of success you get a new instance of the database class. + It is strongly recommened to check this return value with + <function>DB::isError</function>. To disconnect use the method + <function>disconnect</function> from your database class instance. </simpara> <para> <programlisting role="php"> <![CDATA[ <?php -// The pear base directory must be in your include_path require_once 'DB.php'; + $user = 'foo'; $pass = 'bar'; $host = 'localhost'; $db_name = 'clients_db'; + // Data Source Name: This is the universal connection string $dsn = "mysql://$user:$pass@$host/$db_name"; -// DB::connect will return a Pear DB object on success -// or a Pear DB Error object on error -// $db = DB::connect($dsn, true);$db = DB::connect($dsn); +// DB::connect will return a PEAR DB object on success +// or an PEAR DB Error object on error + +$db = DB::connect($dsn, true); + +// Alternatively: $db = DB::connect($dsn); + // With DB::isError you can differentiate between an error or // a valid connection. if (DB::isError($db)) { @@ -155,13 +158,14 @@ <refentry id="core.db.query"> <refnamediv> <refname>Query</refname> - <refpurpose>Performing a query against a database</refpurpose> + <refpurpose>Performing a query against a database.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> - Use <function>query</function> with the SQL-statment as string parameter - to do a query. On failure you get a DB Error object, check it with + To perform a query against a database you have to use the function + <function>query</function>, that takes the query string as an + argument. On failure you get a DB Error object, check it with <function>DB::isError</function>. On succes you get <parameter>DB_OK</parameter> (predefined PEAR::DB constant) or when you set a <parameter>SELECT</parameter>-statment a DB Result object. @@ -174,10 +178,11 @@ $sql = "select * from clients"; $result = $db->query($sql); + // Always check that $result is not an error if (DB::isError($result)) { - die ($result->getMessage()); - } + die ($result->getMessage()); +} .... ?> ]]> @@ -213,14 +218,14 @@ // there is no more rows while ($row = $result->fetchRow()) { $id = $row[0]; - } +} ?> <?php ... while ($result->fetchInto($row)) { $id = $row[0]; - } +} ?> ]]> </programlisting> @@ -311,18 +316,22 @@ ... // 1) Set the mode per call: while ($row = $result->fetchRow(DB_FETCHMODE_ASSOC)) { - [..] + [...] } while ($result->fetchInto($row, DB_FETCHMODE_ASSOC)) { - [..] + [...] } // 2) Set the mode for all calls: + $db = DB::connect($dsn); + // this will set a default fetchmode for this Pear DB instance // (for all queries) $db->setFetchMode(DB_FETCHMODE_ASSOC); + $result = $db->query(...); + while ($row = $result->fetchRow()) { $id = $row['id']; } @@ -335,9 +344,9 @@ <title>Fetch rows by number</title> <para> - The Pear DB fetch system also supports an extra parameter - to the fetch statement, so from a result you can fetch rows by - number. This is specially helpful if you only want to show + The PEAR DB fetch system also supports an extra parameter + to the fetch statement. So you can fetch rows from a result + by number. This is especially helpful if you only want to show sets of an entire result (for example in building paginated HTML lists), fetch rows in an special order, etc. @@ -347,10 +356,13 @@ ... // the row to start fetching $from = 50; + // how many results per page $res_per_page = 10; + // the last row to fetch for this page $to = $from + $res_per_page; + foreach (range($from, $to) as $rownum) { if (!$row = $res->fetchrow($fetchmode, $rownum)) { break; @@ -366,8 +378,9 @@ <refsect2> <title>Freeing the result set</title> <para> - It is recommended to finish the result set, after processing to save memory. - Use <function>free</function> to do this + It is recommended to finish the result set after processing in + order to to save memory. + Use <function>free</function> to do this. <programlisting role="php"> <![CDATA[ <?php...$result = $db->query('SELECT * FROM clients'); @@ -384,7 +397,7 @@ <title>Quick data retrieving</title> <para> - Pear DB provides some special ways to retrieve information from a + PEAR DB provides some special ways to retrieve information from a query without the need of using <function>fetch*</function> and loop throw results. </para> @@ -410,20 +423,9 @@ </programlisting> </para> <para> - <function>getRow</function> will fetch the first row and return it - as an array - <programlisting role="php"> - <![CDATA[ -$sql = 'select name, address, phone from clients where id=1'; -if (is_array($row = $db->getRow($sql))) { - list($name, $address, $phone) = $row; -} - ]]> - </programlisting> - </para> - <para> - <function>getCol</function> will return an array with the data of the - selected column. It accepts the column number to retrieve as the second param. + <function>getCol</function> will return an array with the data + of the selected column. It accepts the column number to retrieve + as the second param. <programlisting role="php"> <![CDATA[ $all_client_names = $db->getCol('select name from clients'); @@ -433,22 +435,24 @@ $all_client_names = array('Stig', 'Jon', 'Colin'); </para> <para> - The <function>get*()</function> family methods will do all the dirty job for you, - this is: launch the query, fetch the data and free the result. Please note that as all - PEAR DB functions they will return a PEAR <classname>DB_error</classname> object on errors. + The <function>get*()</function> family methods will do all the + dirty job for you, this is: launch the query, fetch the data + and free the result. Please note that as all PEAR DB functions + they will return a PEAR <classname>DB_error</classname> object + on errors. </para> </refsect2> <refsect2> <title>Getting more info from query results</title> <para> - With Pear DB you have many ways to retrieve useful information from query results. - These are: + With Pear DB you have many ways to retrieve useful information + from query results. These are: <itemizedlist> <listitem> <para> - <function>numRows</function>: Returns the total number of rows returned - from a "SELECT" query. + <function>numRows</function>: Returns the total number of + rows returned from a "SELECT" query. <programlisting role="php"> <![CDATA[ // Number of rows @@ -459,8 +463,8 @@ </listitem> <listitem> <para> - <function>numCols</function>: Returns the total number of columns - returned from a "SELECT" query. + <function>numCols</function>: Returns the total number of + columns returned from a "SELECT" query. <programlisting role="php"> <![CDATA[ // Number of cols @@ -479,24 +483,25 @@ echo 'I have deleted ' . $db->affectedRows() . 'clients'; ]]> </programlisting> - </para> - </listitem> + </para> + </listitem> <listitem> - <para> + <para> <function>tableInfo</function>: Returns an associative array with - information about the returned fields from a "SELECT" query. - <programlisting role="php"> + information about the returned fields from a "SELECT" query. + <programlisting role="php"> <![CDATA[ // Table Info print_r ($res->tableInfo()); ]]> - </programlisting> - </para> + </programlisting> + </para> </listitem> </itemizedlist> - Don't forget to check if the returned result from your action is a Pear Error - object. If you get a error message like <quote>DB_error: database not capable</quote>, - means that your database backend doesn't support this action. + Don't forget to check if the returned result from your action is + a PEAR Error object. If you get a error message like + <quote>DB_error: database not capable</quote>, means that your + database backend doesn't support this action. </para> </refsect2> </refsect1> @@ -510,13 +515,15 @@ <refsect1> <title>Description</title> <para> - Sequences is a way of offering unique IDs for data rows. If you do most of you - work with e.g. MySQL, think of sequences as another way of doing AUTO_INCREMENT. - It's quite simple, first you request an ID, and then you insert that value in - the ID field of the new row you're creating. You can have more than one sequence - for all your tables, just be sure that you always use the same sequence for - any particular table. To get the value of this unique ID use - <function>nextId</function>, if a sequence doesn't exists, it will be created . + Sequences is a way of offering unique IDs for data rows. If you + do most of you work with e.g. MySQL, think of sequences as another + way of doing AUTO_INCREMENT. It's quite simple, first you request + an ID, and then you insert that value in the ID field of the new + row you're creating. You can have more than one sequence for all + your tables, just be sure that you always use the same sequence + for any particular table. To get the value of this unique ID use + <function>nextId</function>, if a sequence doesn't exists, it + will be created. <programlisting role="php"> <![CDATA[ <?php @@ -542,22 +549,24 @@ <refsect2> <title>Purpose</title> <para> - <function>Prepare</function> and <function>execute*</function> gives you more - power and flexibilty for query execution. You can use them, if you have to do - more then one equal queries (i.e. adding a list of adresses to a database) or - if you want to support different databases, which have different implementations + <function>Prepare</function> and <function>execute*</function> + gives you more power and flexibilty for query execution. You can + use them, if you have to do more then one equal queries (i.e. + adding a list of adresses to a database) or if you want to + support different databases, which have different implementations of the SQL standard. </para> <para> - Maybe you want to support two databases with different INSERT syntax: + Maybe you want to support two databases with different INSERT + syntax: <programlisting role="php"> <![CDATA[ db1 : INSERT INTO tbl_name ( col1, col2 ... ) VALUES ( expr1, expr2 ... ) db2 : INSERT INTO tbl_name SET col1=expr1, col2=expr2 ... ]]> </programlisting> - Correspondending to create multi-lingual scripts you can create a array with - queries like this: + Correspondending to create multi-lingual scripts you can create a + array with queries like this: <programlisting role="php"> <![CDATA[ $statment['db1']['INSERT_PERSON'] = "INSERT INTO person ( surname, name, age ) VALUES ( ?, ?, ? )" ; @@ -571,22 +580,24 @@ <title>Prepare</title> <para> To use the features give in <link linkend="packages.db.prep_exec.purpose">Purpose</link> - you have to to two steps. Step one is to <emphasis>prepare</emphasis> the statment and - the second is to <emphasis>excute</emphasis> it. + you have to to two steps. Step one is to + <emphasis>prepare</emphasis> the statment and the second is + to <emphasis>excute</emphasis> it. </para> <para> - <function>Prepare</function> have to called with the generic statment at least once. - It returns a handle for the statment. + <function>Prepare</function> have to called with the generic + statment at least once. It returns a handle for the statment. </para> <para> - To create a generic statment is simple. Write the SQL query as usual, i.e. + To create a generic statment is simple. Write the SQL query + as usual, i.e. <programlisting role="php"> <![CDATA[ SELECT surname, name, age FROM person WHERE name = 'name_to_find' AND age < 'age_limit' ]]> </programlisting> - Now check which parameters should be replaced while script runtime. - Substitut this parameters with a placeholder. + Now check which parameters should be replaced while script + runtime. Substitute this parameters with a placeholder. <programlisting role="php"> <![CDATA[ SELECT surname, name, age FROM person WHERE name = ? AND age < ? @@ -596,20 +607,21 @@ <function>prepare</function>. </para> <para> - <function>Prepare</function> can handle different types of placeholders or wildcards. + <function>Prepare</function> can handle different types of + placeholders or wildcards. <simplelist> <member> - ? - (recommended) stands for a scalar value like strings or numbers, - the value will be quoted depending of the database + ? - (recommended) stands for a scalar value like strings + or numbers, the value will be quoted depending of the database </member> <member> - ! - stands for a scalar value and will inserted into the statment - <quote>as is</quote> + ! - stands for a scalar value and will inserted into the + statement <quote>as is</quote>. </member> <member> - & - requires an existing filename, the content of this file will - be included into the statment (i.e. for saving binary data of a - graphic file in a database) + & - requires an existing filename, the content of this file + will be included into the statment (i.e. for saving binary + data of a graphic file in a database) </member> </simplelist> </para> @@ -617,12 +629,14 @@ <refsect2> <title>Execute/ ExecuteMultiple</title> <para> - After preparing the statment, you can excute the query. This means to assign the - variables to the prepared statment. To do this, - <function>execute</function> requires to arguments, the statment handle of - <function>prepare</function> and a array with the values to assign. The array has - to be numeric ordered. The first entry of the array represents the first wildcard, - the second the second etc. The order is independent from the used wildcard char. + After preparing the statment, you can excute the query. This + means to assign the variables to the prepared statment. To do + this, <function>execute</function> requires to arguments, the + statment handle of <function>prepare</function> and a array + with the values to assign. The array has to be numeric ordered. + The first entry of the array represents the first wildcard, + the second the second etc. The order is independent from the + used wildcard char. <programlisting role="php"> <![CDATA[ <?php @@ -647,9 +661,9 @@ INSERT INTO numbers VALUES( '4', 'four', 'fire') ]]> </programlisting> - <function>ExecuteMultiple</function> works in the same way, but requires - a two dimensional array. So you can avoid the explicit foreach in the eample - above. + <function>ExecuteMultiple</function> works in the same way, but + requires a two dimensional array. So you can avoid the explicit + foreach in the eample above. <programlisting role="php"> <![CDATA[ <?php @@ -664,8 +678,8 @@ ?> ]]> </programlisting> - The result is the same. If one of the records failed, the unfinished records - will not be executed. + The result is the same. If one of the records failed, the + unfinished records will not be executed. </para> <para> If <function>execute*</function> fails a <classname>DB_Error</classname>,
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.3 peardoc/en/core/db.xml:1.4 --- peardoc/en/core/db.xml:1.3 Sun Dec 16 15:14:33 2001 +++ peardoc/en/core/db.xml Mon Dec 17 13:14:11 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.3 $ --> +<!-- $Revision: 1.4 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -13,13 +13,13 @@ <refentry id="core.db.dsn"> <refnamediv> <refname>DSN</refname> - <refpurpose>The Data Source Name</refpurpose> + <refpurpose>The data source name</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> To connect to a database through PEAR::DB, you have to create a - valid <acronym>DSN - Data Source Name</acronym>. This DSN + valid <acronym>DSN - data source name</acronym>. This DSN consists of the: </simpara> <para> @@ -41,10 +41,6 @@ Host specification (hostname[:port]) </member> <member> - <parameter>hostspec</parameter>: - Host specification (hostname[:port]) - </member> - <member> <parameter>database</parameter>: Database to use on the DBMS server </member> @@ -77,7 +73,7 @@ phptype </programlisting> - The currently supported (the <parameter>phptype</parameter> DSN part) are: + The currently supported database backends are: <programlisting role="php"> mysql -> MySQL @@ -98,7 +94,8 @@ <para> Please note, that some features may be not supported by all database backends. Please refer to the PEAR DB extensions status document located at: - <parameter>pear base dir</parameter>/DB/STATUS to get the detailed list. + <parameter>pear base dir</parameter>/DB/STATUS to get a detailed list + about what features are supported by which backend. </para> </warning> </para> @@ -113,30 +110,36 @@ <refsect1> <title>Description</title> <simpara> - To connect use <function>DB::connect</function>, this function requires a - valid <link linkend="packages.db.dsn">DSN</link> as parameter and optional - a boolean value, set them true, when you want a persistent connection. In case of - success you get a new instance of the database clase. It is strongly - recommened to check this return value with <function>DB::isError</function>. - To disconnect use the method <function>disconnect</function> of your - database class instance. + To connect to a database you have to use the function + <function>DB::connect</function>, which requires a valid + <link linkend="packages.db.dsn">DSN</link> as parameter and optional + a boolean value, which determines wether to use a persistent connection + or not. In case of success you get a new instance of the database class. + It is strongly recommened to check this return value with + <function>DB::isError</function>. To disconnect use the method + <function>disconnect</function> from your database class instance. </simpara> <para> <programlisting role="php"> <![CDATA[ <?php -// The pear base directory must be in your include_path require_once 'DB.php'; + $user = 'foo'; $pass = 'bar'; $host = 'localhost'; $db_name = 'clients_db'; + // Data Source Name: This is the universal connection string $dsn = "mysql://$user:$pass@$host/$db_name"; -// DB::connect will return a Pear DB object on success -// or a Pear DB Error object on error -// $db = DB::connect($dsn, true);$db = DB::connect($dsn); +// DB::connect will return a PEAR DB object on success +// or an PEAR DB Error object on error + +$db = DB::connect($dsn, true); + +// Alternatively: $db = DB::connect($dsn); + // With DB::isError you can differentiate between an error or // a valid connection. if (DB::isError($db)) { @@ -155,13 +158,14 @@ <refentry id="core.db.query"> <refnamediv> <refname>Query</refname> - <refpurpose>Performing a query against a database</refpurpose> + <refpurpose>Performing a query against a database.</refpurpose> </refnamediv> <refsect1> <title>Description</title> <simpara> - Use <function>query</function> with the SQL-statment as string parameter - to do a query. On failure you get a DB Error object, check it with + To perform a query against a database you have to use the function + <function>query</function>, that takes the query string as an + argument. On failure you get a DB Error object, check it with <function>DB::isError</function>. On succes you get <parameter>DB_OK</parameter> (predefined PEAR::DB constant) or when you set a <parameter>SELECT</parameter>-statment a DB Result object. @@ -174,10 +178,11 @@ $sql = "select * from clients"; $result = $db->query($sql); + // Always check that $result is not an error if (DB::isError($result)) { - die ($result->getMessage()); - } + die ($result->getMessage()); +} .... ?> ]]> @@ -213,14 +218,14 @@ // there is no more rows while ($row = $result->fetchRow()) { $id = $row[0]; - } +} ?> <?php ... while ($result->fetchInto($row)) { $id = $row[0]; - } +} ?> ]]> </programlisting> @@ -311,18 +316,22 @@ ... // 1) Set the mode per call: while ($row = $result->fetchRow(DB_FETCHMODE_ASSOC)) { - [..] + [...] } while ($result->fetchInto($row, DB_FETCHMODE_ASSOC)) { - [..] + [...] } // 2) Set the mode for all calls: + $db = DB::connect($dsn); + // this will set a default fetchmode for this Pear DB instance // (for all queries) $db->setFetchMode(DB_FETCHMODE_ASSOC); + $result = $db->query(...); + while ($row = $result->fetchRow()) { $id = $row['id']; } @@ -335,9 +344,9 @@ <title>Fetch rows by number</title> <para> - The Pear DB fetch system also supports an extra parameter - to the fetch statement, so from a result you can fetch rows by - number. This is specially helpful if you only want to show + The PEAR DB fetch system also supports an extra parameter + to the fetch statement. So you can fetch rows from a result + by number. This is especially helpful if you only want to show sets of an entire result (for example in building paginated HTML lists), fetch rows in an special order, etc. @@ -347,10 +356,13 @@ ... // the row to start fetching $from = 50; + // how many results per page $res_per_page = 10; + // the last row to fetch for this page $to = $from + $res_per_page; + foreach (range($from, $to) as $rownum) { if (!$row = $res->fetchrow($fetchmode, $rownum)) { break; @@ -366,8 +378,9 @@ <refsect2> <title>Freeing the result set</title> <para> - It is recommended to finish the result set, after processing to save memory. - Use <function>free</function> to do this + It is recommended to finish the result set after processing in + order to to save memory. + Use <function>free</function> to do this. <programlisting role="php"> <![CDATA[ <?php...$result = $db->query('SELECT * FROM clients'); @@ -384,7 +397,7 @@ <title>Quick data retrieving</title> <para> - Pear DB provides some special ways to retrieve information from a + PEAR DB provides some special ways to retrieve information from a query without the need of using <function>fetch*</function> and loop throw results. </para> @@ -410,20 +423,9 @@ </programlisting> </para> <para> - <function>getRow</function> will fetch the first row and return it - as an array - <programlisting role="php"> - <![CDATA[ -$sql = 'select name, address, phone from clients where id=1'; -if (is_array($row = $db->getRow($sql))) { - list($name, $address, $phone) = $row; -} - ]]> - </programlisting> - </para> - <para> - <function>getCol</function> will return an array with the data of the - selected column. It accepts the column number to retrieve as the second param. + <function>getCol</function> will return an array with the data + of the selected column. It accepts the column number to retrieve + as the second param. <programlisting role="php"> <![CDATA[ $all_client_names = $db->getCol('select name from clients'); @@ -433,22 +435,24 @@ $all_client_names = array('Stig', 'Jon', 'Colin'); </para> <para> - The <function>get*()</function> family methods will do all the dirty job for you, - this is: launch the query, fetch the data and free the result. Please note that as all - PEAR DB functions they will return a PEAR <classname>DB_error</classname> object on errors. + The <function>get*()</function> family methods will do all the + dirty job for you, this is: launch the query, fetch the data + and free the result. Please note that as all PEAR DB functions + they will return a PEAR <classname>DB_error</classname> object + on errors. </para> </refsect2> <refsect2> <title>Getting more info from query results</title> <para> - With Pear DB you have many ways to retrieve useful information from query results. - These are: + With Pear DB you have many ways to retrieve useful information + from query results. These are: <itemizedlist> <listitem> <para> - <function>numRows</function>: Returns the total number of rows returned - from a "SELECT" query. + <function>numRows</function>: Returns the total number of + rows returned from a "SELECT" query. <programlisting role="php"> <![CDATA[ // Number of rows @@ -459,8 +463,8 @@ </listitem> <listitem> <para> - <function>numCols</function>: Returns the total number of columns - returned from a "SELECT" query. + <function>numCols</function>: Returns the total number of + columns returned from a "SELECT" query. <programlisting role="php"> <![CDATA[ // Number of cols @@ -479,24 +483,25 @@ echo 'I have deleted ' . $db->affectedRows() . 'clients'; ]]> </programlisting> - </para> - </listitem> + </para> + </listitem> <listitem> - <para> + <para> <function>tableInfo</function>: Returns an associative array with - information about the returned fields from a "SELECT" query. - <programlisting role="php"> + information about the returned fields from a "SELECT" query. + <programlisting role="php"> <![CDATA[ // Table Info print_r ($res->tableInfo()); ]]> - </programlisting> - </para> + </programlisting> + </para> </listitem> </itemizedlist> - Don't forget to check if the returned result from your action is a Pear Error - object. If you get a error message like <quote>DB_error: database not capable</quote>, - means that your database backend doesn't support this action. + Don't forget to check if the returned result from your action is + a PEAR Error object. If you get a error message like + <quote>DB_error: database not capable</quote>, means that your + database backend doesn't support this action. </para> </refsect2> </refsect1> @@ -510,13 +515,15 @@ <refsect1> <title>Description</title> <para> - Sequences is a way of offering unique IDs for data rows. If you do most of you - work with e.g. MySQL, think of sequences as another way of doing AUTO_INCREMENT. - It's quite simple, first you request an ID, and then you insert that value in - the ID field of the new row you're creating. You can have more than one sequence - for all your tables, just be sure that you always use the same sequence for - any particular table. To get the value of this unique ID use - <function>nextId</function>, if a sequence doesn't exists, it will be created . + Sequences is a way of offering unique IDs for data rows. If you + do most of you work with e.g. MySQL, think of sequences as another + way of doing AUTO_INCREMENT. It's quite simple, first you request + an ID, and then you insert that value in the ID field of the new + row you're creating. You can have more than one sequence for all + your tables, just be sure that you always use the same sequence + for any particular table. To get the value of this unique ID use + <function>nextId</function>, if a sequence doesn't exists, it + will be created. <programlisting role="php"> <![CDATA[ <?php @@ -542,22 +549,24 @@ <refsect2> <title>Purpose</title> <para> - <function>Prepare</function> and <function>execute*</function> gives you more - power and flexibilty for query execution. You can use them, if you have to do - more then one equal queries (i.e. adding a list of adresses to a database) or - if you want to support different databases, which have different implementations + <function>Prepare</function> and <function>execute*</function> + gives you more power and flexibilty for query execution. You can + use them, if you have to do more then one equal queries (i.e. + adding a list of adresses to a database) or if you want to + support different databases, which have different implementations of the SQL standard. </para> <para> - Maybe you want to support two databases with different INSERT syntax: + Maybe you want to support two databases with different INSERT + syntax: <programlisting role="php"> <![CDATA[ db1 : INSERT INTO tbl_name ( col1, col2 ... ) VALUES ( expr1, expr2 ... ) db2 : INSERT INTO tbl_name SET col1=expr1, col2=expr2 ... ]]> </programlisting> - Correspondending to create multi-lingual scripts you can create a array with - queries like this: + Correspondending to create multi-lingual scripts you can create a + array with queries like this: <programlisting role="php"> <![CDATA[ $statment['db1']['INSERT_PERSON'] = "INSERT INTO person ( surname, name, age ) VALUES ( ?, ?, ? )" ; @@ -571,22 +580,24 @@ <title>Prepare</title> <para> To use the features give in <link linkend="packages.db.prep_exec.purpose">Purpose</link> - you have to to two steps. Step one is to <emphasis>prepare</emphasis> the statment and - the second is to <emphasis>excute</emphasis> it. + you have to to two steps. Step one is to + <emphasis>prepare</emphasis> the statment and the second is + to <emphasis>excute</emphasis> it. </para> <para> - <function>Prepare</function> have to called with the generic statment at least once. - It returns a handle for the statment. + <function>Prepare</function> have to called with the generic + statment at least once. It returns a handle for the statment. </para> <para> - To create a generic statment is simple. Write the SQL query as usual, i.e. + To create a generic statment is simple. Write the SQL query + as usual, i.e. <programlisting role="php"> <![CDATA[ SELECT surname, name, age FROM person WHERE name = 'name_to_find' AND age < 'age_limit' ]]> </programlisting> - Now check which parameters should be replaced while script runtime. - Substitut this parameters with a placeholder. + Now check which parameters should be replaced while script + runtime. Substitute this parameters with a placeholder. <programlisting role="php"> <![CDATA[ SELECT surname, name, age FROM person WHERE name = ? AND age < ? @@ -596,20 +607,21 @@ <function>prepare</function>. </para> <para> - <function>Prepare</function> can handle different types of placeholders or wildcards. + <function>Prepare</function> can handle different types of + placeholders or wildcards. <simplelist> <member> - ? - (recommended) stands for a scalar value like strings or numbers, - the value will be quoted depending of the database + ? - (recommended) stands for a scalar value like strings + or numbers, the value will be quoted depending of the database </member> <member> - ! - stands for a scalar value and will inserted into the statment - <quote>as is</quote> + ! - stands for a scalar value and will inserted into the + statement <quote>as is</quote>. </member> <member> - & - requires an existing filename, the content of this file will - be included into the statment (i.e. for saving binary data of a - graphic file in a database) + & - requires an existing filename, the content of this file + will be included into the statment (i.e. for saving binary + data of a graphic file in a database) </member> </simplelist> </para> @@ -617,12 +629,14 @@ <refsect2> <title>Execute/ ExecuteMultiple</title> <para> - After preparing the statment, you can excute the query. This means to assign the - variables to the prepared statment. To do this, - <function>execute</function> requires to arguments, the statment handle of - <function>prepare</function> and a array with the values to assign. The array has - to be numeric ordered. The first entry of the array represents the first wildcard, - the second the second etc. The order is independent from the used wildcard char. + After preparing the statment, you can excute the query. This + means to assign the variables to the prepared statment. To do + this, <function>execute</function> requires to arguments, the + statment handle of <function>prepare</function> and a array + with the values to assign. The array has to be numeric ordered. + The first entry of the array represents the first wildcard, + the second the second etc. The order is independent from the + used wildcard char. <programlisting role="php"> <![CDATA[ <?php @@ -647,9 +661,9 @@ INSERT INTO numbers VALUES( '4', 'four', 'fire') ]]> </programlisting> - <function>ExecuteMultiple</function> works in the same way, but requires - a two dimensional array. So you can avoid the explicit foreach in the eample - above. + <function>ExecuteMultiple</function> works in the same way, but + requires a two dimensional array. So you can avoid the explicit + foreach in the eample above. <programlisting role="php"> <![CDATA[ <?php @@ -664,8 +678,8 @@ ?> ]]> </programlisting> - The result is the same. If one of the records failed, the unfinished records - will not be executed. + The result is the same. If one of the records failed, the + unfinished records will not be executed. </para> <para> If <function>execute*</function> fails a <classname>DB_Error</classname>,