cvs: peardoc /en/package/database/db intro-fetch.xml

From: Date: Tue, 13 Apr 2004 19:11:21 +0000
Subject: cvs: peardoc /en/package/database/db intro-fetch.xml
Groups: php.pear.doc 
Request: Send a blank email to pear-doc+get-3364@lists.php.net to get a copy of this message
danielc Tue Apr 13 15:11:21 2004 EDT Modified files: /peardoc/en/package/database/db intro-fetch.xml Log: Fix indenting/leading whitespace.

http://cvs.php.net/diff.php/peardoc/en/package/database/db/intro-fetch.xml?r1=1.22&r2=1.23&ty=u Index: peardoc/en/package/database/db/intro-fetch.xml diff -u peardoc/en/package/database/db/intro-fetch.xml:1.22 peardoc/en/package/database/db/intro-fetch.xml:1.23 --- peardoc/en/package/database/db/intro-fetch.xml:1.22 Tue Apr 13 14:55:00 2004 +++ peardoc/en/package/database/db/intro-fetch.xml Tue Apr 13 15:11:21 2004 @@ -1,10 +1,11 @@ -<!-- $Revision: 1.22 $ --> +<!-- $Revision: 1.23 $ --> <refentry id="package.database.db.intro-fetch"> <refnamediv> <refname>Introduction - Fetch &amp; Get</refname> <refpurpose>Fetching rows from queries</refpurpose> </refnamediv> + <refsect1 id="package.database.db.intro-fetch.desc"> &title.desc; @@ -56,27 +57,27 @@ echo $row[0] . "\n"; } ?> - ]]> - </programlisting> - </example> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.format"> - <title>Choosing Formats for Fetched Rows</title> - <para> - The fetch modes supported are: - <itemizedlist> - <listitem> - <para> - <constant>DB_FETCHMODE_ORDERED</constant> (default) - </para> - <para> - The <function>fetch*</function> returns an ordered array. - The order is taken from the select statement. - <example> - <title>Fetch a ordered array</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.format"> + <title>Choosing Formats for Fetched Rows</title> + <para> + The fetch modes supported are: + <itemizedlist> + <listitem> + <para> + <constant>DB_FETCHMODE_ORDERED</constant> (default) + </para> + <para> + The <function>fetch*</function> returns an ordered array. + The order is taken from the select statement. + <example> + <title>Fetch a ordered array</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $db->setFetchMode(DB_FETCHMODE_ORDERED); @@ -98,22 +99,22 @@ * Column a is 28 */ ?> - ]]> - </programlisting> - </example> - </para> - </listitem> - <listitem> - <para> - <constant>DB_FETCHMODE_ASSOC</constant> - </para> - <para> - Returns an associative array with the column - names as the array keys - <example> - <title>Fetch a assoc. array</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </listitem> + <listitem> + <para> + <constant>DB_FETCHMODE_ASSOC</constant> + </para> + <para> + Returns an associative array with the column + names as the array keys + <example> + <title>Fetch a assoc. array</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $db->setFetchMode(DB_FETCHMODE_ASSOC); @@ -135,26 +136,26 @@ * Column a is 28 */ ?> - ]]> - </programlisting> - </example> - </para> - </listitem> - <listitem> - <para> - <constant>DB_FETCHMODE_OBJECT</constant> - </para> - <para> - Returns an object with column names as properties - </para> - <para> - If <function>setFetchMode</function> is called without the optional - second argument, <function>fetchRow</function> returns a - <classname>stdClass</classname> object. - <example> - <title>Fetching into an object</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </listitem> + <listitem> + <para> + <constant>DB_FETCHMODE_OBJECT</constant> + </para> + <para> + Returns an object with column names as properties + </para> + <para> + If <function>setFetchMode</function> is called without the optional + second argument, <function>fetchRow</function> returns a + <classname>stdClass</classname> object. + <example> + <title>Fetching into an object</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $db->setFetchMode(DB_FETCHMODE_OBJECT); @@ -176,18 +177,18 @@ * Column a is 28 */ ?> - ]]> - </programlisting> - </example> - </para> - <para> - If <function>setFetchMode</function>'s optional parameter is passed - <literal>DB_row</literal>, <function>fetchRow</function> returns a - &class.db-row; object. - <example> - <title>Fetching into a DB_row object</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + <para> + If <function>setFetchMode</function>'s optional parameter is passed + <literal>DB_row</literal>, <function>fetchRow</function> returns a + &class.db-row; object. + <example> + <title>Fetching into a DB_row object</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $db->setFetchMode(DB_FETCHMODE_OBJECT, 'DB_row'); @@ -209,24 +210,24 @@ * Column a is 28 */ ?> - ]]> - </programlisting> - </example> - </para> - </listitem> - </itemizedlist> - </para> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.how"> - <title>How to Set Formats</title> - <para> - You can set the fetch mode per result call or for your whole DB - instance. - <example> - <title>Per call</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </listitem> + </itemizedlist> + </para> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.how"> + <title>How to Set Formats</title> + <para> + You can set the fetch mode per result call or for your whole DB + instance. + <example> + <title>Per call</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $res =& $db->query('SELECT * FROM users'); @@ -235,13 +236,13 @@ echo $row['id'] . "\n"; } ?> - ]]> - </programlisting> - </example> - <example> - <title>Once per instance</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + <example> + <title>Once per instance</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $db->setFetchMode(DB_FETCHMODE_ASSOC); @@ -252,24 +253,24 @@ echo $row['id'] . "\n"; } ?> - ]]> - </programlisting> - </example> - </para> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.number"> - <title>Fetch Rows by Number</title> - <para> - 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. - <example> - <title>Fetching by number</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.number"> + <title>Fetch Rows by Number</title> + <para> + 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. + <example> + <title>Fetching by number</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... @@ -290,23 +291,23 @@ .... } ?> - ]]> - </programlisting> - </example> - </para> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.free"> - <title>Freeing Result Sets</title> - <para> - It is recommended to finish the result set after processing in - order to save memory. - Use <link linkend="package.database.db.db-result.free"> - <function>free</function></link> to do this. - <example> - <title>Freeing</title> - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.free"> + <title>Freeing Result Sets</title> + <para> + It is recommended to finish the result set after processing in + order to save memory. + Use <link linkend="package.database.db.db-result.free"> + <function>free</function></link> to do this. + <example> + <title>Freeing</title> + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $res =& $db->query('SELECT name, address FROM clients'); @@ -315,37 +316,37 @@ } $res->free(); ?> - ]]> - </programlisting> - </example> - </para> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.quick"> - <title>Quick Data Retrieving</title> - <para> - &class.db; provides some special ways to retrieve information - from a query without the need of using - <function>fetch*</function> and looping through results. - </para> - <para> - <link linkend="package.database.db.db-common.getone"> - <function>getOne</function></link> retrieves the first result of the - first column from a query - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </example> + </para> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.quick"> + <title>Quick Data Retrieving</title> + <para> + &class.db; provides some special ways to retrieve information + from a query without the need of using + <function>fetch*</function> and looping through results. + </para> + <para> + <link linkend="package.database.db.db-common.getone"> + <function>getOne</function></link> retrieves the first result of the + first column from a query + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $numrows = $db->getOne('select count(id) from clients'); ?> - ]]> - </programlisting> - </para> - <para> - <link linkend="package.database.db.db-common.getrow"><function>getRow</function> - </link> returns the first row as an array. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + <para> + <link linkend="package.database.db.db-common.getrow"><function>getRow</function> + </link> returns the first row as an array. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $sql = 'select name, address from clients where id=1'; @@ -353,16 +354,16 @@ echo $row['name'] . ', ' . $row['address'] . "\n"; } ?> - ]]> - </programlisting> - </para> - <para> - <link linkend="package.database.db.db-common.getcol"> - <function>getCol</function></link> returns an array with the data - of the selected column. It accepts the column number to retrieve - as the second parameter. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + <para> + <link linkend="package.database.db.db-common.getcol"> + <function>getCol</function></link> returns an array with the data + of the selected column. It accepts the column number to retrieve + as the second parameter. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $data =& $db->getCol('SELECT name FROM clients'); @@ -376,16 +377,16 @@ * ) */ ?> - ]]> - </programlisting> - </para> - <para> - <link linkend="package.database.db.db-common.getassoc"> - <function>getAssoc</function></link> fetches the entire result set - of a query and return it as an associative array using the - first column as the key. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + <para> + <link linkend="package.database.db.db-common.getassoc"> + <function>getAssoc</function></link> fetches the entire result set + of a query and return it as an associative array using the + first column as the key. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $data =& $db->getAssoc('SELECT name, surname, phone FROM mytable'); @@ -398,15 +399,15 @@ * ) */ ?> - ]]> - </programlisting> - </para> - <para> - <link linkend="package.database.db.db-common.getall"> - <function>getAll</function></link> - fetches all the rows returned from a query- - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + <para> + <link linkend="package.database.db.db-common.getall"> + <function>getAll</function></link> + fetches all the rows returned from a query- + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $data =& $db->getAll('SELECT id, text, date FROM mytable'); @@ -419,100 +420,100 @@ * ) */ ?> - ]]> - </programlisting> - </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 &class.db-error; object - on errors. - </para> - </refsect2> - - <refsect2 id="package.database.db.intro-fetch.desc.more"> - <title>Getting More Information From Query Results</title> - <para> - With &class.db; you have many ways to retrieve useful information - from query results. These are: - <itemizedlist> - <listitem> - <para> - <link linkend="package.database.db.db-result.numrows"> - <function>numRows</function></link>: Returns the total number of - rows returned from a <command>SELECT</command> query. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </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 &class.db-error; object + on errors. + </para> + </refsect2> + + <refsect2 id="package.database.db.intro-fetch.desc.more"> + <title>Getting More Information From Query Results</title> + <para> + With &class.db; you have many ways to retrieve useful information + from query results. These are: + <itemizedlist> + <listitem> + <para> + <link linkend="package.database.db.db-result.numrows"> + <function>numRows</function></link>: Returns the total number of + rows returned from a <command>SELECT</command> query. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $res =& $db->query('SELECT * FROM phptest'); echo $res->numRows(); ?> - ]]> - </programlisting> - </para> - </listitem> - <listitem> - <para> - <link linkend="package.database.db.db-result.numcols"> - <function>numCols</function></link>: Returns the total number of - columns returned from a <command>SELECT</command> query. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + </listitem> + <listitem> + <para> + <link linkend="package.database.db.db-result.numcols"> + <function>numCols</function></link>: Returns the total number of + columns returned from a <command>SELECT</command> query. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $res =& $db->query('SELECT * FROM phptest'); echo $res->numCols(); ?> - ]]> - </programlisting> - </para> - </listitem> - <listitem> - <para> - <link linkend="package.database.db.db-common.affectedrows"> - <function>affectedRows</function></link>: Returns the number of rows - affected by a data manipulation query (<command>INSERT</command>, - <command>UPDATE</command> or <command>DELETE</command>). - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + </listitem> + <listitem> + <para> + <link linkend="package.database.db.db-common.affectedrows"> + <function>affectedRows</function></link>: Returns the number of rows + affected by a data manipulation query (<command>INSERT</command>, + <command>UPDATE</command> or <command>DELETE</command>). + <programlisting role="php"> + <![CDATA[ <?php // remember that this statement won't return a result object $db->query('DELETE * FROM clients'); echo 'I have deleted ' . $db->affectedRows() . ' clients'; ?> - ]]> - </programlisting> - </para> - </listitem> - <listitem> - <para> - <link linkend="package.database.db.db-common.tableinfo"> - <function>tableInfo</function></link>: Returns an associative array - with information about the returned fields from a - <command>SELECT</command> query. - <programlisting role="php"> - <![CDATA[ + ]]> + </programlisting> + </para> + </listitem> + <listitem> + <para> + <link linkend="package.database.db.db-common.tableinfo"> + <function>tableInfo</function></link>: Returns an associative array + with information about the returned fields from a + <command>SELECT</command> query. + <programlisting role="php"> + <![CDATA[ <?php // Once you have a valid DB object named $db... $res =& $db->query('SELECT * FROM phptest'); print_r($db->tableInfo($res)); ?> - ]]> - </programlisting> - </para> - </listitem> - </itemizedlist> - Don't forget to check if the returned result from your action is - a &class.db-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> - + ]]> + </programlisting> + </para> + </listitem> + </itemizedlist> + Don't forget to check if the returned result from your action is + a &class.db-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> </refentry> + <!-- Keep this comment at the end of the file Local variables: mode: sgml
« previous php.pear.doc (#3364) next »