cvs: peardoc /en/core db.xml
| From: | Alexander Merz | Date: | Tue, 15 Jan 2002 14:58:50 +0000 |
| Subject: | cvs: peardoc /en/core db.xml | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-1958@lists.php.net to get a copy of this message | ||
alexmerz Tue Jan 15 09:58:50 2002 EDT
Modified files:
/peardoc/en/core db.xml
Log:
DB-API finished, need a beer now
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.9 peardoc/en/core/db.xml:1.10 --- peardoc/en/core/db.xml:1.9 Sat Dec 29 05:29:36 2001 +++ peardoc/en/core/db.xml Tue Jan 15 09:58:50 2002 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> +<!-- $Revision: 1.10 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -104,7 +104,7 @@ </refsect1> </refentry> - <refentry id="core.db.connect"> + <refentry id="core.db.tut_connect"> <refnamediv> <refname>Connect</refname> <refpurpose>Connecting and disconnecting</refpurpose> @@ -158,7 +158,7 @@ </para> </refsect1> </refentry> - <refentry id="core.db.query"> + <refentry id="core.db.tut_query"> <refnamediv> <refname>Query</refname> <refpurpose>Performing a query against a database.</refpurpose> @@ -195,7 +195,7 @@ </refsect1> </refentry> - <refentry id="core.db.fetch"> + <refentry id="core.db.tut_fetch"> <refnamediv> <refname>Fetch</refname> <refpurpose>Fetching rows from the query</refpurpose> @@ -574,7 +574,7 @@ </refsect1> </refentry> - <refentry id="core.db.sequences"> + <refentry id="core.db.tut_sequences"> <refnamediv> <refname>Sequences</refname> <refpurpose>Database sequences</refpurpose> @@ -605,7 +605,7 @@ </para> </refsect1> </refentry> - <refentry id="core.db.execute"> + <refentry id="core.db.tut_execute"> <refnamediv> <refname>Execute</refname> <refpurpose>Prepare & Execute/ExecuteMultiple</refpurpose> @@ -661,7 +661,8 @@ as usual, i.e. <programlisting> <![CDATA[ -SELECT surname, name, age FROM person WHERE name = 'name_to_find' AND age < 'age_limit' +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 @@ -757,7 +758,1035 @@ </refsect2> </refsect1> </refentry> - </reference> + + <refentry id="core.db.quote"> + <refnamediv> + <refname>DB::quote()</refname> + <refpurpose>Quotes a string so it can be safely used in a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.quote.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>quote</function></funcdef> + <paramdef>string <parameter>$string</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$string</parameter> - the input string to quote + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - NULL, if a NULL string was given, + else the quoted string. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.provides"> + <refnamediv> + <refname>DB::provides()</refname> + <refpurpose>Tell whether a DB implementation or its backend extension + supports a given feature.</refpurpose> + </refnamediv> + <refsect1 id="core.db.provides.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>boolean <function>provides</function></funcdef> + <paramdef>string <parameter>$feature</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$feature</parameter> - name of the feature (see the DB + class doc) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>boolean</parameter> - whether the used DB implementation + supports $feature + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.setfetchmode"> + <refnamediv> + <refname>DB::setFetchMode()</refname> + <refpurpose>Sets which fetch mode should be used by default on queries + on the connection.</refpurpose> + </refnamediv> + <refsect1 id="core.db.setfetchmode.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>setFetchMode</function></funcdef> + <paramdef>integer <parameter>$fetchmode</parameter></paramdef> + <paramdef>string + <parameter><optional>$object_class</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$fetchmode</parameter> - + <parameter>DB_FETCHMODE_ORDERED</parameter>, + <parameter>DB_FETCHMODE_OBJECT</parameter> or + <parameter>DB_FETCHMODE_ASSOC</parameter>, possibly bit-wise OR'ed with + <parameter>DB_FETCHMODE_FLIPPED</parameter>. See + <link linkend="core.db.tut_fetch">"Fetch"-section</link> + for further information. + </para> + </listitem> + <listitem> + <para> + <parameter>$object_class</parameter> - The class of the object + to be returned by the fetch methods when + the <parameter>DB_FETCHMODE_OBJECT</parameter> mode is selected. + If no class is specified by default a cast + to object from the assoc array row will be done. + There is also the posibility to use and extend the + 'DB_Row' class. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - Nothing or a + <parameter>PEAR_ERROR</parameter>, + if <parameter>$fetchmode</parameter> contains a unknown value. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.prepare"> + <refnamediv> + <refname>DB::prepare()</refname> + <refpurpose>Prepares a query for multiple execution with + execute().</refpurpose> + </refnamediv> + <refsect1 id="core.db.prepare.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>prepare</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Prepare</function> requires a generic query as + string like "INSERT INTO numbers VALUES(?,?,?)". + The ? are wildcards. Types of wildcards: + <simplelist> + <member> + <parameter>?</parameter> - a quoted scalar value, i.e. strings, integers + </member> + <member> + <parameter>&</parameter> - requires a file name, the content of the file + insert into the query (i.e. saving binary data + in a db). + </member> + <member> + <parameter>!</parameter> - value is inserted 'as is' + </member> + </simplelist> + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the query to prepare + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - the query handle + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.execute"> + <refnamediv> + <refname>DB::execute()</refname> + <refpurpose>Executes a prepared SQL query</refpurpose> + </refnamediv> + <refsect1 id="core.db.execute.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>execute</function></funcdef> + <paramdef>string <parameter>$stmt</parameter></paramdef> + <paramdef>array <parameter>$data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + With <function>execute</function> the generic query of prepare is + assigned with the given data array. The values + of the array inserted into the query in the same + order like the array order. + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$stmt</parameter> - query handle from + <link linkend="core.db.prepare"><function>prepare</function> + </link> + </para> + </listitem> + <listitem> + <para> + <parameter>$data</parameter> - numeric array containing the + data to insert into the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.executemultiple"> + <refnamediv> + <refname>DB::executeMultiple()</refname> + <refpurpose>Several executes a prepared SQL query</refpurpose> + </refnamediv> + <refsect1 id="core.db.executemultiple.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>executeMultiple</function></funcdef> + <paramdef>string <parameter>$stmt</parameter></paramdef> + <paramdef>array <parameter>$data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function does several <function>execute</function> calls on the same + statement handle. $data must be an array indexed numerically + from 0, one execute call is done for every "row" in the array. + If an error occurs during <function>execute</function>, + <function>executeMultiple</function> does not + execute the unfinished rows, but rather returns that error. + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$stmt</parameter> - query handle from + <link linkend="core.db.prepare"><function>prepare</function> + </link> + </para> + </listitem> + <listitem> + <para> + <parameter>$data</parameter> - numeric array containing the + data to insert into the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.query"> + <refnamediv> + <refname>DB::query()</refname> + <refpurpose>Send a query to the database</refpurpose> + </refnamediv> + <refsect1 id="core.db.query.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&query</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + See <link linkend="core.db.tut_query">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - $params the data to be added to + the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.limitquery"> + <refnamediv> + <refname>DB::limitQuery()</refname> + <refpurpose>Generates a limited query + <emphasis>EXPERIMENTAL!</emphasis></refpurpose> + </refnamediv> + <refsect1 id="core.db.limitquery.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&limitQuery</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>integer <parameter>$from</parameter></paramdef> + <paramdef>integer <parameter>$count</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$from</parameter> - the row to start to fetching + </para> + </listitem> + <listitem> + <para> + <parameter>$count</parameter> - the numbers of rows to fetch + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getone"> + <refnamediv> + <refname>DB::getOne()</refname> + <refpurpose>Fetch the first column of the first row from a + query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getone.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getOne</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the first column of the first row of data returned from + a query. Takes care of doing the query and freeing the results + when finished. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used + with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the returned value + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getrow"> + <refnamediv> + <refname>DB::getRow()</refname> + <refpurpose>Fetch the first row from a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getrow.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getRow</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + <paramdef>integer + <parameter><optional>$fetchmode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the first row of data returned from a query. Takes care + of doing the query and freeing the results when finished. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used + with this array as execute parameters + </para> + </listitem> + <listitem> + <para> + <parameter>$fetchmode</parameter> - the fetch mode to use, default + is <parameter>DB_FETCHMODE_DEFAULT</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the first row of results as an array + indexed from + 0 or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getcol"> + <refnamediv> + <refname>DB::getCol()</refname> + <refpurpose>Fetch a single column from a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getcol.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getCol</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>mixed <parameter><optional>$col</optional></parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch a single column from a result set and return it as an + indexed array. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$col</parameter> - which column to return (integer [column + number, starting at 0] or string [column name]), default is + <parameter>0</parameter> + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will be + used with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the first row of results as an array + indexed from 0 or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getassoc"> + <refnamediv> + <refname>DB::getAssoc()</refname> + <refpurpose> + Fetch the result set as an + associative array using the first column as the key. + </refpurpose> + </refnamediv> + <refsect1 id="core.db.getassoc.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>&getAssoc</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef> + boolean + <parameter><optional>$force_array</optional></parameter></paramdef> + <paramdef> + array <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the entire result set of a query and return it as an + associative array using the first column as the key. + + If the result set contains more than two columns, the value + will be an array of the values from column 2-n. If the result + set contains only two columns, the returned value will be a + scalar with the value of the second column (unless forced to an + array with the $force_array parameter). A DB error code is + returned on errors. If the result set contains fewer than two + columns, a <parameter>DB_ERROR_TRUNCATED</parameter> error is returned. + </para> + <para> + A using example: + <example> + <title>"mytable"</title> + <programlisting> + <![CDATA[ +ID TEXT DATE +---------------------- +1 'one' 944679408 +2 'two' 944679408 +3 'three' 944679408 + ]]> + </programlisting> + </example> + Then the call getAssoc('SELECT id,text FROM mytable') returns: + <example> + <title>returned array - version 1</title> + <programlisting> + <![CDATA[ +array( + '1' => 'one', + '2' => 'two', + '3' => 'three', + ) + ]]> + </programlisting> + </example> + ...while the call getAssoc('SELECT id,text,date FROM mytable') returns: + <example> + <title>returned array - version 2</title> + <programlisting> + <![CDATA[ +array( + '1' => array('one', '944679408'), + '2' => array('two', '944679408'), + '3' => array('three', '944679408') + ) + ]]> + </programlisting> + </example> + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$force_array</parameter> - used only when the query returns + exactly two columns. If true, the values of the returned array + will be one-element arrays instead of scalars. + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will be + used with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>array</parameter> - associative array with results from the + query. + </para> + </listitem> + </itemizedlist> + </para> + <note> + <para> + Keep in mind that database functions in PHP usually return string + values for results regardless of the database's internal type. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="core.db.getall"> + <refnamediv> + <refname>DB::getAll()</refname> + <refpurpose>Fetch all the rows returned from a query.</refpurpose> + </refnamediv> + <refsect1 id="core.db.getall.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getAll</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + <paramdef>integer + <parameter><optional>$fetchmode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used with this array as execute parameters + </para> + </listitem> + <listitem> + <para> + <parameter>$fetchmode</parameter> - the fetch mode to use, default: + <parameter>DB_FETCHMODE_DEFAULT</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - an nested array or a + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.affectedrows"> + <refnamediv> + <refname>DB::affectedRows()</refname> + <refpurpose>returns the affected rows of a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.affectedrows.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>affectedRows</function></funcdef> + <paramdef></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - number of rows or + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.nextid"> + <refnamediv> + <refname>DB::nextId()</refname> + <refpurpose>returns the next free id of a sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.nextid.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>nextId</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + <paramdef>boolean + <parameter><option>$on_demand</option></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the sequence + </para> + </listitem> + <listitem> + <para> + <parameter>$ondemand</parameter> - when true the sequence is + automatic created, if it not exists. Default ist <parameter> + true</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - a free id or + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.createsequence"> + <refnamediv> + <refname>DB::createSequence()</refname> + <refpurpose>creates a new sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.createsequence.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>createSequence</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the new sequence + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of creating query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.dropsequence"> + <refnamediv> + <refname>DB::dropSequence()</refname> + <refpurpose>deletes a sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.dropsequence.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>dropSequence</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the sequence + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of the dropping query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.tableinfo"> + <refnamediv> + <refname>DB::tableInfo()</refname> + <refpurpose>returns meta data about the result set</refpurpose> + </refnamediv> + <refsect1 id="core.db.tableinfo.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>tableInfo</function></funcdef> + <paramdef>DB_Result <parameter>$result</parameter></paramdef> + <paramdef>mode + <parameter><optional>$mode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$result</parameter> - the result object to analyse + </para> + </listitem> + <listitem> + <para> + <parameter>$mode</parameter> - depends on database implementation + <itemizedlist> + <listitem> + <para> + FrontBase, MS-SQL, MySQL, PostgreSQL + <itemizedlist> + <listitem><para><parameter>false</parameter> (default) + returns this array + <programlisting> + <![CDATA[ +[0]["table"] table name +[0]["name"] field name +[0]["type"] field type +[0]["len"] field length +[0]["flags"] field flags + ]]> + </programlisting> + </para> + </listitem> + <listitem><para><parameter>DB_TABLEINFO_ORDER</parameter> + returns this array + <programlisting> + <![CDATA[ +["num_fields"] number of metadata records +[0]["table"] table name +[0]["name"] field name +[0]["type"] field type +[0]["len"] field length +[0]["flags"] field flags +["order"][field name] index of field named "field name" + ]]> + </programlisting> + The last one is used, if you have a field name, but no index. + Test: if (isset($result['meta']['myfield'])) { ... + </para> + </listitem> + <listitem><para><parameter>DB_TABLEINFO_ORDERTABLE</parameter> + returns the same as above. But additionally + <programlisting> + <![CDATA[ +["ordertable"][table name][field name] index of field named "field name" + ]]> + </programlisting> + This is, because if you have fields from different + tables with the same field name * they override each + other with <parameter>DB_TABLEINFO_ORDER</parameter>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + InterBase, Informix, mSQL, Oracle8, ODBC, Sybase - No information + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of the dropping query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getlistof"> + <refnamediv> + <refname>DB::getListOf()</refname> + <refpurpose>list internal DB info</refpurpose> + </refnamediv> + <refsect1 id="core.db.getlistof.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>getListOf</function></funcdef> + <paramdef>string <parameter>$type</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$type</parameter> - type of requested info + valid values for $type are db dependent, often: + <parameter>"databases"</parameter>, <parameter>"users"</parameter>, + <parameter>"view"</parameter>, <parameter>"functions"</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the requested data + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + +</reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml
Index: peardoc/en/core/db.xml diff -u peardoc/en/core/db.xml:1.9 peardoc/en/core/db.xml:1.10 --- peardoc/en/core/db.xml:1.9 Sat Dec 29 05:29:36 2001 +++ peardoc/en/core/db.xml Tue Jan 15 09:58:50 2002 @@ -1,5 +1,5 @@ <?xml encoding="iso-8859-1"?> -<!-- $Revision: 1.9 $ --> +<!-- $Revision: 1.10 $ --> <reference id="core.db"> <title>PEAR DB: a unified API for accessing SQL-databases</title> @@ -104,7 +104,7 @@ </refsect1> </refentry> - <refentry id="core.db.connect"> + <refentry id="core.db.tut_connect"> <refnamediv> <refname>Connect</refname> <refpurpose>Connecting and disconnecting</refpurpose> @@ -158,7 +158,7 @@ </para> </refsect1> </refentry> - <refentry id="core.db.query"> + <refentry id="core.db.tut_query"> <refnamediv> <refname>Query</refname> <refpurpose>Performing a query against a database.</refpurpose> @@ -195,7 +195,7 @@ </refsect1> </refentry> - <refentry id="core.db.fetch"> + <refentry id="core.db.tut_fetch"> <refnamediv> <refname>Fetch</refname> <refpurpose>Fetching rows from the query</refpurpose> @@ -574,7 +574,7 @@ </refsect1> </refentry> - <refentry id="core.db.sequences"> + <refentry id="core.db.tut_sequences"> <refnamediv> <refname>Sequences</refname> <refpurpose>Database sequences</refpurpose> @@ -605,7 +605,7 @@ </para> </refsect1> </refentry> - <refentry id="core.db.execute"> + <refentry id="core.db.tut_execute"> <refnamediv> <refname>Execute</refname> <refpurpose>Prepare & Execute/ExecuteMultiple</refpurpose> @@ -661,7 +661,8 @@ as usual, i.e. <programlisting> <![CDATA[ -SELECT surname, name, age FROM person WHERE name = 'name_to_find' AND age < 'age_limit' +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 @@ -757,7 +758,1035 @@ </refsect2> </refsect1> </refentry> - </reference> + + <refentry id="core.db.quote"> + <refnamediv> + <refname>DB::quote()</refname> + <refpurpose>Quotes a string so it can be safely used in a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.quote.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>quote</function></funcdef> + <paramdef>string <parameter>$string</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$string</parameter> - the input string to quote + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - NULL, if a NULL string was given, + else the quoted string. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.provides"> + <refnamediv> + <refname>DB::provides()</refname> + <refpurpose>Tell whether a DB implementation or its backend extension + supports a given feature.</refpurpose> + </refnamediv> + <refsect1 id="core.db.provides.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>boolean <function>provides</function></funcdef> + <paramdef>string <parameter>$feature</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$feature</parameter> - name of the feature (see the DB + class doc) + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>boolean</parameter> - whether the used DB implementation + supports $feature + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.setfetchmode"> + <refnamediv> + <refname>DB::setFetchMode()</refname> + <refpurpose>Sets which fetch mode should be used by default on queries + on the connection.</refpurpose> + </refnamediv> + <refsect1 id="core.db.setfetchmode.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>setFetchMode</function></funcdef> + <paramdef>integer <parameter>$fetchmode</parameter></paramdef> + <paramdef>string + <parameter><optional>$object_class</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$fetchmode</parameter> - + <parameter>DB_FETCHMODE_ORDERED</parameter>, + <parameter>DB_FETCHMODE_OBJECT</parameter> or + <parameter>DB_FETCHMODE_ASSOC</parameter>, possibly bit-wise OR'ed with + <parameter>DB_FETCHMODE_FLIPPED</parameter>. See + <link linkend="core.db.tut_fetch">"Fetch"-section</link> + for further information. + </para> + </listitem> + <listitem> + <para> + <parameter>$object_class</parameter> - The class of the object + to be returned by the fetch methods when + the <parameter>DB_FETCHMODE_OBJECT</parameter> mode is selected. + If no class is specified by default a cast + to object from the assoc array row will be done. + There is also the posibility to use and extend the + 'DB_Row' class. + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - Nothing or a + <parameter>PEAR_ERROR</parameter>, + if <parameter>$fetchmode</parameter> contains a unknown value. + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.prepare"> + <refnamediv> + <refname>DB::prepare()</refname> + <refpurpose>Prepares a query for multiple execution with + execute().</refpurpose> + </refnamediv> + <refsect1 id="core.db.prepare.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>resource <function>prepare</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + <function>Prepare</function> requires a generic query as + string like "INSERT INTO numbers VALUES(?,?,?)". + The ? are wildcards. Types of wildcards: + <simplelist> + <member> + <parameter>?</parameter> - a quoted scalar value, i.e. strings, integers + </member> + <member> + <parameter>&</parameter> - requires a file name, the content of the file + insert into the query (i.e. saving binary data + in a db). + </member> + <member> + <parameter>!</parameter> - value is inserted 'as is' + </member> + </simplelist> + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the query to prepare + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - the query handle + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.execute"> + <refnamediv> + <refname>DB::execute()</refname> + <refpurpose>Executes a prepared SQL query</refpurpose> + </refnamediv> + <refsect1 id="core.db.execute.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>execute</function></funcdef> + <paramdef>string <parameter>$stmt</parameter></paramdef> + <paramdef>array <parameter>$data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + With <function>execute</function> the generic query of prepare is + assigned with the given data array. The values + of the array inserted into the query in the same + order like the array order. + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$stmt</parameter> - query handle from + <link linkend="core.db.prepare"><function>prepare</function> + </link> + </para> + </listitem> + <listitem> + <para> + <parameter>$data</parameter> - numeric array containing the + data to insert into the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.executemultiple"> + <refnamediv> + <refname>DB::executeMultiple()</refname> + <refpurpose>Several executes a prepared SQL query</refpurpose> + </refnamediv> + <refsect1 id="core.db.executemultiple.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>executeMultiple</function></funcdef> + <paramdef>string <parameter>$stmt</parameter></paramdef> + <paramdef>array <parameter>$data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + This function does several <function>execute</function> calls on the same + statement handle. $data must be an array indexed numerically + from 0, one execute call is done for every "row" in the array. + If an error occurs during <function>execute</function>, + <function>executeMultiple</function> does not + execute the unfinished rows, but rather returns that error. + See <link linkend="core.db.tut_execute">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$stmt</parameter> - query handle from + <link linkend="core.db.prepare"><function>prepare</function> + </link> + </para> + </listitem> + <listitem> + <para> + <parameter>$data</parameter> - numeric array containing the + data to insert into the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.query"> + <refnamediv> + <refname>DB::query()</refname> + <refpurpose>Send a query to the database</refpurpose> + </refnamediv> + <refsect1 id="core.db.query.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&query</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + See <link linkend="core.db.tut_query">"Execute"-section</link> + for further information. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - $params the data to be added to + the query + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.limitquery"> + <refnamediv> + <refname>DB::limitQuery()</refname> + <refpurpose>Generates a limited query + <emphasis>EXPERIMENTAL!</emphasis></refpurpose> + </refnamediv> + <refsect1 id="core.db.limitquery.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&limitQuery</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>integer <parameter>$from</parameter></paramdef> + <paramdef>integer <parameter>$count</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$from</parameter> - the row to start to fetching + </para> + </listitem> + <listitem> + <para> + <parameter>$count</parameter> - the numbers of rows to fetch + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>resource</parameter> - a new <classname>DB_Result</classname> + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getone"> + <refnamediv> + <refname>DB::getOne()</refname> + <refpurpose>Fetch the first column of the first row from a + query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getone.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getOne</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the first column of the first row of data returned from + a query. Takes care of doing the query and freeing the results + when finished. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query or the statement to + prepare + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used + with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the returned value + or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getrow"> + <refnamediv> + <refname>DB::getRow()</refname> + <refpurpose>Fetch the first row from a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getrow.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getRow</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + <paramdef>integer + <parameter><optional>$fetchmode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the first row of data returned from a query. Takes care + of doing the query and freeing the results when finished. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used + with this array as execute parameters + </para> + </listitem> + <listitem> + <para> + <parameter>$fetchmode</parameter> - the fetch mode to use, default + is <parameter>DB_FETCHMODE_DEFAULT</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the first row of results as an array + indexed from + 0 or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getcol"> + <refnamediv> + <refname>DB::getCol()</refname> + <refpurpose>Fetch a single column from a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.getcol.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getCol</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>mixed <parameter><optional>$col</optional></parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch a single column from a result set and return it as an + indexed array. + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$col</parameter> - which column to return (integer [column + number, starting at 0] or string [column name]), default is + <parameter>0</parameter> + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will be + used with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the first row of results as an array + indexed from 0 or a <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getassoc"> + <refnamediv> + <refname>DB::getAssoc()</refname> + <refpurpose> + Fetch the result set as an + associative array using the first column as the key. + </refpurpose> + </refnamediv> + <refsect1 id="core.db.getassoc.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>array <function>&getAssoc</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef> + boolean + <parameter><optional>$force_array</optional></parameter></paramdef> + <paramdef> + array <parameter><optional>$params</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Fetch the entire result set of a query and return it as an + associative array using the first column as the key. + + If the result set contains more than two columns, the value + will be an array of the values from column 2-n. If the result + set contains only two columns, the returned value will be a + scalar with the value of the second column (unless forced to an + array with the $force_array parameter). A DB error code is + returned on errors. If the result set contains fewer than two + columns, a <parameter>DB_ERROR_TRUNCATED</parameter> error is returned. + </para> + <para> + A using example: + <example> + <title>"mytable"</title> + <programlisting> + <![CDATA[ +ID TEXT DATE +---------------------- +1 'one' 944679408 +2 'two' 944679408 +3 'three' 944679408 + ]]> + </programlisting> + </example> + Then the call getAssoc('SELECT id,text FROM mytable') returns: + <example> + <title>returned array - version 1</title> + <programlisting> + <![CDATA[ +array( + '1' => 'one', + '2' => 'two', + '3' => 'three', + ) + ]]> + </programlisting> + </example> + ...while the call getAssoc('SELECT id,text,date FROM mytable') returns: + <example> + <title>returned array - version 2</title> + <programlisting> + <![CDATA[ +array( + '1' => array('one', '944679408'), + '2' => array('two', '944679408'), + '3' => array('three', '944679408') + ) + ]]> + </programlisting> + </example> + </para> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$force_array</parameter> - used only when the query returns + exactly two columns. If true, the values of the returned array + will be one-element arrays instead of scalars. + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will be + used with this array as execute parameters + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>array</parameter> - associative array with results from the + query. + </para> + </listitem> + </itemizedlist> + </para> + <note> + <para> + Keep in mind that database functions in PHP usually return string + values for results regardless of the database's internal type. + </para> + </note> + </refsect1> + </refentry> + + <refentry id="core.db.getall"> + <refnamediv> + <refname>DB::getAll()</refname> + <refpurpose>Fetch all the rows returned from a query.</refpurpose> + </refnamediv> + <refsect1 id="core.db.getall.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>&getAll</function></funcdef> + <paramdef>string <parameter>$query</parameter></paramdef> + <paramdef>array + <parameter><optional>$params</optional></parameter></paramdef> + <paramdef>integer + <parameter><optional>$fetchmode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$query</parameter> - the SQL query + </para> + </listitem> + <listitem> + <para> + <parameter>$params</parameter> - if supplied, prepare/execute will + be used with this array as execute parameters + </para> + </listitem> + <listitem> + <para> + <parameter>$fetchmode</parameter> - the fetch mode to use, default: + <parameter>DB_FETCHMODE_DEFAULT</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - an nested array or a + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.affectedrows"> + <refnamediv> + <refname>DB::affectedRows()</refname> + <refpurpose>returns the affected rows of a query</refpurpose> + </refnamediv> + <refsect1 id="core.db.affectedrows.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>affectedRows</function></funcdef> + <paramdef></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - number of rows or + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.nextid"> + <refnamediv> + <refname>DB::nextId()</refname> + <refpurpose>returns the next free id of a sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.nextid.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>nextId</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + <paramdef>boolean + <parameter><option>$on_demand</option></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the sequence + </para> + </listitem> + <listitem> + <para> + <parameter>$ondemand</parameter> - when true the sequence is + automatic created, if it not exists. Default ist <parameter> + true</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - a free id or + <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.createsequence"> + <refnamediv> + <refname>DB::createSequence()</refname> + <refpurpose>creates a new sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.createsequence.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>createSequence</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the new sequence + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of creating query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.dropsequence"> + <refnamediv> + <refname>DB::dropSequence()</refname> + <refpurpose>deletes a sequence</refpurpose> + </refnamediv> + <refsect1 id="core.db.dropsequence.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>dropSequence</function></funcdef> + <paramdef>string <parameter>$seq_name</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$seq_name</parameter> - name of the sequence + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of the dropping query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.tableinfo"> + <refnamediv> + <refname>DB::tableInfo()</refname> + <refpurpose>returns meta data about the result set</refpurpose> + </refnamediv> + <refsect1 id="core.db.tableinfo.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>tableInfo</function></funcdef> + <paramdef>DB_Result <parameter>$result</parameter></paramdef> + <paramdef>mode + <parameter><optional>$mode</optional></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$result</parameter> - the result object to analyse + </para> + </listitem> + <listitem> + <para> + <parameter>$mode</parameter> - depends on database implementation + <itemizedlist> + <listitem> + <para> + FrontBase, MS-SQL, MySQL, PostgreSQL + <itemizedlist> + <listitem><para><parameter>false</parameter> (default) + returns this array + <programlisting> + <![CDATA[ +[0]["table"] table name +[0]["name"] field name +[0]["type"] field type +[0]["len"] field length +[0]["flags"] field flags + ]]> + </programlisting> + </para> + </listitem> + <listitem><para><parameter>DB_TABLEINFO_ORDER</parameter> + returns this array + <programlisting> + <![CDATA[ +["num_fields"] number of metadata records +[0]["table"] table name +[0]["name"] field name +[0]["type"] field type +[0]["len"] field length +[0]["flags"] field flags +["order"][field name] index of field named "field name" + ]]> + </programlisting> + The last one is used, if you have a field name, but no index. + Test: if (isset($result['meta']['myfield'])) { ... + </para> + </listitem> + <listitem><para><parameter>DB_TABLEINFO_ORDERTABLE</parameter> + returns the same as above. But additionally + <programlisting> + <![CDATA[ +["ordertable"][table name][field name] index of field named "field name" + ]]> + </programlisting> + This is, because if you have fields from different + tables with the same field name * they override each + other with <parameter>DB_TABLEINFO_ORDER</parameter>. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + InterBase, Informix, mSQL, Oracle8, ODBC, Sybase - No information + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the result of the dropping query + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + + <refentry id="core.db.getlistof"> + <refnamediv> + <refname>DB::getListOf()</refname> + <refpurpose>list internal DB info</refpurpose> + </refnamediv> + <refsect1 id="core.db.getlistof.desc"> + <title>Description</title> + <funcsynopsis> + <funcprototype> + <funcdef>mixed <function>getListOf</function></funcdef> + <paramdef>string <parameter>$type</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <para> + Parameter + <itemizedlist> + <listitem> + <para> + <parameter>$type</parameter> - type of requested info + valid values for $type are db dependent, often: + <parameter>"databases"</parameter>, <parameter>"users"</parameter>, + <parameter>"view"</parameter>, <parameter>"functions"</parameter> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Returns + <itemizedlist> + <listitem> + <para> + <parameter>mixed</parameter> - the requested data + or <classname>DB_Error</classname> when fail + </para> + </listitem> + </itemizedlist> + </para> + </refsect1> + </refentry> + +</reference> <!-- Keep this comment at the end of the file Local variables: mode: sgml