cvs: peardoc /en/core db.xml
| From: | Martin Jansen | Date: | Mon, 17 Dec 2001 18:19:37 +0000 |
| Subject: | cvs: peardoc /en/core db.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-1589@lists.php.net to get a copy of this message | ||
mj Mon Dec 17 13:19:37 2001 EDT
Modified files:
/peardoc/en/core db.xml
Log:
* Set maximum chars per line to 70 in db.xml
# Can we make this a standard?
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.4 peardoc/en/core/db.xml:1.5 --- peardoc/en/core/db.xml:1.4 Mon Dec 17 13:14:11 2001 +++ peardoc/en/core/db.xml Mon Dec 17 13:19:37 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -19,7 +19,7 @@ <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> @@ -92,10 +92,11 @@ <warning id="core.db.features.warning"> <title>Important!</title> <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 a detailed list - about what features are supported by which backend. + 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 a detailed list about what + features are supported by which backend. </para> </warning> </para> @@ -112,12 +113,13 @@ <simpara> 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. + <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"> @@ -163,12 +165,13 @@ <refsect1> <title>Description</title> <simpara> - 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. + 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. </simpara> <para> <programlisting role="php"> @@ -202,11 +205,13 @@ <refsect2> <title>Fetch functions</title> <simpara> - The <classname>DB_Result</classname> object provides two functions to fetch rows: - <function>fetchRow</function> and <function>fetchInto</function>. - <function>fetchRow</function> returns a row or false, when the result set is empty. - <function>fetchInto</function> requires a variable, which will directly assigned by reference - to the result row. It will return false, when result set is empty too. + The <classname>DB_Result</classname> object provides two + functions to fetch rows: <function>fetchRow</function> and + <function>fetchInto</function>. <function>fetchRow</function> + returns a row or false, when the result set is empty. + <function>fetchInto</function> requires a variable, which will + directly assigned by reference to the result row. It will return + false, when result set is empty too. </simpara> <para> <programlisting role="php"> @@ -397,9 +402,9 @@ <title>Quick data retrieving</title> <para> - PEAR DB provides some special ways to retrieve information from a - query without the need of using <function>fetch*</function> and loop - throw results. + 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> <para> <function>getOne</function> retrieves the first result of the @@ -411,8 +416,8 @@ </programlisting> </para> <para> - <function>getRow</function> will fetch the first row and return it - as an array + <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'; @@ -476,10 +481,12 @@ <listitem> <para> <function>affectedRows</function>: Returns the number of rows - affected by a data manipulation query ("INSERT", "UPDATE" or "DELETE"). + affected by a data manipulation query ("INSERT", "UPDATE" or + "DELETE"). <programlisting role="php"> <![CDATA[ -// remember that this statement won't return a result object$db->query($sql); +// remember that this statement won't return a result object +$db->query($sql); echo 'I have deleted ' . $db->affectedRows() . 'clients'; ]]> </programlisting> @@ -487,8 +494,9 @@ </listitem> <listitem> <para> - <function>tableInfo</function>: Returns an associative array with - information about the returned fields from a "SELECT" query. + <function>tableInfo</function>: Returns an associative array + with information about the returned fields from a "SELECT" + query. <programlisting role="php"> <![CDATA[ // Table Info @@ -516,14 +524,14 @@ <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. + 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 @@ -550,11 +558,11 @@ <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 - of the SQL standard. + 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 @@ -565,8 +573,8 @@ 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 ( ?, ?, ? )" ; @@ -579,7 +587,8 @@ <refsect2> <title>Prepare</title> <para> - To use the features give in <link linkend="packages.db.prep_exec.purpose">Purpose</link> + 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. @@ -682,8 +691,9 @@ unfinished records will not be executed. </para> <para> - If <function>execute*</function> fails a <classname>DB_Error</classname>, - else a <parameter>DB_OK</parameter> will returned. + If <function>execute*</function> fails a + <classname>DB_Error</classname>, else a + <parameter>DB_OK</parameter> will returned. </para> </refsect2> </refsect1>
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.4 peardoc/en/core/db.xml:1.5 --- peardoc/en/core/db.xml:1.4 Mon Dec 17 13:14:11 2001 +++ peardoc/en/core/db.xml Mon Dec 17 13:19:37 2001 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -19,7 +19,7 @@ <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> @@ -92,10 +92,11 @@ <warning id="core.db.features.warning"> <title>Important!</title> <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 a detailed list - about what features are supported by which backend. + 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 a detailed list about what + features are supported by which backend. </para> </warning> </para> @@ -112,12 +113,13 @@ <simpara> 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. + <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"> @@ -163,12 +165,13 @@ <refsect1> <title>Description</title> <simpara> - 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. + 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. </simpara> <para> <programlisting role="php"> @@ -202,11 +205,13 @@ <refsect2> <title>Fetch functions</title> <simpara> - The <classname>DB_Result</classname> object provides two functions to fetch rows: - <function>fetchRow</function> and <function>fetchInto</function>. - <function>fetchRow</function> returns a row or false, when the result set is empty. - <function>fetchInto</function> requires a variable, which will directly assigned by reference - to the result row. It will return false, when result set is empty too. + The <classname>DB_Result</classname> object provides two + functions to fetch rows: <function>fetchRow</function> and + <function>fetchInto</function>. <function>fetchRow</function> + returns a row or false, when the result set is empty. + <function>fetchInto</function> requires a variable, which will + directly assigned by reference to the result row. It will return + false, when result set is empty too. </simpara> <para> <programlisting role="php"> @@ -397,9 +402,9 @@ <title>Quick data retrieving</title> <para> - PEAR DB provides some special ways to retrieve information from a - query without the need of using <function>fetch*</function> and loop - throw results. + 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> <para> <function>getOne</function> retrieves the first result of the @@ -411,8 +416,8 @@ </programlisting> </para> <para> - <function>getRow</function> will fetch the first row and return it - as an array + <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'; @@ -476,10 +481,12 @@ <listitem> <para> <function>affectedRows</function>: Returns the number of rows - affected by a data manipulation query ("INSERT", "UPDATE" or "DELETE"). + affected by a data manipulation query ("INSERT", "UPDATE" or + "DELETE"). <programlisting role="php"> <![CDATA[ -// remember that this statement won't return a result object$db->query($sql); +// remember that this statement won't return a result object +$db->query($sql); echo 'I have deleted ' . $db->affectedRows() . 'clients'; ]]> </programlisting> @@ -487,8 +494,9 @@ </listitem> <listitem> <para> - <function>tableInfo</function>: Returns an associative array with - information about the returned fields from a "SELECT" query. + <function>tableInfo</function>: Returns an associative array + with information about the returned fields from a "SELECT" + query. <programlisting role="php"> <![CDATA[ // Table Info @@ -516,14 +524,14 @@ <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. + 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 @@ -550,11 +558,11 @@ <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 - of the SQL standard. + 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 @@ -565,8 +573,8 @@ 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 ( ?, ?, ? )" ; @@ -579,7 +587,8 @@ <refsect2> <title>Prepare</title> <para> - To use the features give in <link linkend="packages.db.prep_exec.purpose">Purpose</link> + 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. @@ -682,8 +691,9 @@ unfinished records will not be executed. </para> <para> - If <function>execute*</function> fails a <classname>DB_Error</classname>, - else a <parameter>DB_OK</parameter> will returned. + If <function>execute*</function> fails a + <classname>DB_Error</classname>, else a + <parameter>DB_OK</parameter> will returned. </para> </refsect2> </refsect1>